C API Reference

c_io.h


Type Definitions

Io_Storage typedef
typedef struct Io_Storage Io_Storage

Io_Stream typedef
typedef struct Io_Stream Io_Stream


Enums

Io_OpenMode enum
A bitmask type which controls the initial state of a stream upon opening. The semantics are analogous to C++'s std::ios_base::openmode except that streams are always opened in binary mode and reads and writes occur at the internally maintained read and write positions, which are initialized at the beginning and end of the stream respectively.

Values:
  • IO_OPEN_MODE_READ = 0x01: Allow read operations on the stream. Read operations always occur at the read position, which is initialized to the beginning of the stream.
  • IO_OPEN_MODE_WRITE = 0x02: Allow write operations on the stream. Write operations always occur at the write position, which is initialized to the end of the stream.
  • IO_OPEN_MODE_TRUNCATE = 0x04: Specify that any existing content should be truncated upon opening.
  • IO_OPEN_MODE_APPEND = 0x08: Specify that writes should be appended to the stream's existing content, if any exists.


Functions

Io_Storage_Create function
Io_Storage* Io_Storage_Create(void)

Creates a generic storage object.

Storage objects can be used in conjunction with other APIs to efficiently manage the lifetime of various data (e.g. trace items).

Memory stored in a given storage object remains valid until either the storage object is cleared or it is destroyed.

Returns:

  • Io_Storage*:

    Parameters
    • void:
  • Io_Storage_Destroy function
    void Io_Storage_Destroy(Io_Storage* storage)


    Returns:

  • void:

    Parameters
    • Io_Storage*:
  • Io_Storage_Clear function
    void Io_Storage_Clear(Io_Storage* storage)

    Clears the storage object.

    This marks memory previously stored in this storage object as available to re-use/overwrite but does not actually free the memory. This leads to fewer allocations than, for example, using a new storage object each time.

    Returns:

  • void:

    Parameters
    • Io_Storage*:
  • Io_CreateRingBufferStream function
    Io_Stream* Io_CreateRingBufferStream(uint32_t capacity_bytes)

    Creates an I/O stream implemented as a ring buffer.

    The ring buffer stream has a maximum write capacity equal to the number of bytes specified upon creation. Attempted writes which would exceed this capacity will succeed, but return the lower, actual number of bytes written. Reading from the stream increases write capacity by the amount of bytes successfully read.

    The stream has no readable data when first created.

    Returns a pointer to a valid ring buffer stream. Never returns NULL.

    Returns:

  • Io_Stream*:

    Parameters
    • uint32_t:
  • Io_CreateFileStream function
    Io_Stream* Io_CreateFileStream(const char* filename, uint32_t open_mode)

    Creates an I/O stream implemented as a read/write file.

    The file stream has a conceptually infinite capacity; its true capacity depends on the underlying filesystem.

    The open_mode argument should be passed as a combination of Io_OpenMode values.

    Returns a pointer to a file stream. Never returns NULL. Call Io_Stream_GetLastError to check if an error occurred during file stream creation.

    Returns:

  • Io_Stream*:

    Parameters
    • const char*:
    • uint32_t:
  • Io_Stream_Destroy function
    void Io_Stream_Destroy(Io_Stream* stream)


    Returns:

  • void:

    Parameters
    • Io_Stream*:
  • Io_Stream_Write function
    int64_t Io_Stream_Write(Io_Stream* stream, const uint8_t* bytes, uint32_t length)

    Writes as much of the given data as possible to the stream.

    Returns the actual number of bytes written. This may be less than the given length iff the stream has finite capacity and there is insufficient remaining capacity for the full write.

    Returns -1 on error. Call Io_Stream_GetLastError to get the associated error message.

    Returns:

  • int64_t:

    Parameters
    • Io_Stream*:
    • const uint8_t*:
    • uint32_t:
  • Io_Stream_GetRemainingWriteCapacityBytes function
    uint32_t Io_Stream_GetRemainingWriteCapacityBytes(Io_Stream* stream)

    Gets the remaining write capacity in bytes.

    Returns the maximum value for stream implementations with conceptually infinite capacity, like file streams, regardless of how much data has previously been written.

    Returns:

  • uint32_t:

    Parameters
    • Io_Stream*:
  • Io_Stream_Read function
    int64_t Io_Stream_Read(Io_Stream* stream, uint8_t* bytes, uint32_t length)

    Reads as much of the stream's data as possible into the given buffer.

    Returns the actual number of bytes read. This may be less than the given length iff the stream has less data than the requested amount.

    Returns -1 on error. Call Io_Stream_GetLastError to get the associated error message.

    Returns:

  • int64_t:

    Parameters
    • Io_Stream*:
    • uint8_t*:
    • uint32_t:
  • Io_Stream_Peek function
    int64_t Io_Stream_Peek(Io_Stream* , uint8_t* bytes, uint32_t length)

    Reads as much of the stream's data as possible into the given buffer without advancing the read position i.e. a subsequent read of the same size would provide the same data.

    Returns the actual number of bytes read. This may be less than the given length iff the stream has less data than the requested amount.

    Returns -1 on error. Call Io_Stream_GetLastError() to get the associated error message.

    Returns:

  • int64_t:

    Parameters
    • Io_Stream*:
    • uint8_t*:
    • uint32_t:
  • Io_Stream_Ignore function
    int64_t Io_Stream_Ignore(Io_Stream* , uint32_t length)

    Extracts the given number of bytes from the stream and discards them.

    Returns the actual number of bytes extracted i.e. the number of bytes by which the read position has advanced. This may be less than the given length iff the stream has less data than the requested amount.

    Returns -1 on error. Call Io_Stream_GetLastError() to get the associated error message.

    Returns:

  • int64_t:

    Parameters
    • Io_Stream*:
    • uint32_t:
  • Io_Stream_GetLastError function
    const char* Io_Stream_GetLastError(Io_Stream* stream)

    Returns the last error which occurred during an API call on this stream. Returns nullptr if no such error has occurred.

    Returns:

  • const char*:

    Parameters
    • Io_Stream*:
  • Io_Stream_ClearError function
    void Io_Stream_ClearError(Io_Stream* stream)

    Clears the stream's current error such that the next call to Io_Stream_GetLastError returns nullptr.

    Returns:

  • void:

    Parameters
    • Io_Stream*:
  • c_schema.h

    This file defines an interface for manipulating objects corresponding to the types defined in the SpatialOS schema in a dynamic way.

    Schema_Object is the main type for data manipulation, and roughly-speaking corresponds to an instance of a "type" as defined in schema. Each Schema_Object is owned by a "root" schema type instance, of which there are four: Schema_CommandRequest, Schema_CommandResponse, Schema_ComponentData, and Schema_ComponentUpdate.

    Each field defined in schema has a field ID, a type and an arity. For each type, there is a family of functions that can be used to read and write fields of that type for a particular field ID inside a Schema_Object. The mapping from schema type to function family is given below:


    .schema type function family
    int32 Int32
    int64 Int64
    uint32 Uint32
    uint64 Uint64
    sint32 Sint32
    sint64 Sint64
    fixed32 Fixed32
    fixed64 Fixed64
    sfixed32 Sfixed32
    sfixed64 Sfixed64
    bool Bool
    float Float
    double Double
    string Bytes
    EntityId EntityId (alias for Int64)
    Entity Object
    bytes Bytes
    user-defined enum Enum (alias for Uint32)
    user-defined type Object

    The arity of a field is either singular, option, or list. The same function family can be used for manipulating fields of any arity: a singular field is simply a field whose ID occurs exactly once; an option field is a field whose ID occurs zero or one times; and a list field is a field whose ID occurs any number of times.

    Therefore, typically, where X is the function family, we use the Schema_GetX and Schema_AddX functions to read and write singular fields; the Schema_GetXCount, Schema_GetX and Schema_AddX functions to read and write option fields, and the Schema_GetXCount, Schema_IndexX and Schema_AddX functions to read and write list fields. However, these functions are all interopable: internally, Schema_GetX just retrieves the last occurence of the given field ID, for instance.

    A Map field is an Object that contains a list of Object fields. Each object represents an entry in the map, and has the key under field ID 1 (SCHEMA_MAP_KEY_FIELD_ID) and the value under field ID 2 (SCHEMA_MAP_VALUE_FIELD_ID).

    An Entity field is a set of Component data. It is represented as an Object with one field per component data. A given component is stored with a field Id equal to the component Id.

    It is the responsibility of the user to ensure that Schema_Objects are accessed and mutated in a way consistent with the schema definitions of their corresponding types. Typically, this is done by writing a custom code generator for the schema AST.


    Macros

    SCHEMA_MAP_KEY_FIELD_ID macro
    1

    SCHEMA_MAP_VALUE_FIELD_ID macro
    2


    Type Definitions

    Schema_GenericData typedef
    typedef struct Schema_GenericData Schema_GenericData

    Schema_CommandRequest typedef
    typedef struct Schema_CommandRequest Schema_CommandRequest

    Schema_CommandResponse typedef
    typedef struct Schema_CommandResponse Schema_CommandResponse

    Schema_ComponentData typedef
    typedef struct Schema_ComponentData Schema_ComponentData

    Schema_ComponentUpdate typedef
    typedef struct Schema_ComponentUpdate Schema_ComponentUpdate

    Schema_FieldId typedef
    typedef uint32_t Schema_FieldId

    Schema_ComponentId typedef
    typedef uint32_t Schema_ComponentId

    Schema_EntityId typedef
    typedef int64_t Schema_EntityId

    Schema_Bundle typedef
    typedef struct Schema_Bundle Schema_Bundle

    Schema_Object typedef
    typedef struct Schema_Object Schema_Object
    An object, roughly corresponding to an instance of a "type" as defined in schema.

    Schema_Json typedef
    typedef struct Schema_Json Schema_Json
    An opaque type used for storing serialized JSON schema data.

    Schema_ErrorCallback typedef
    typedef void Schema_ErrorCallback(void *user_data, const char *error)
    An error callback, used to signal one or more error messages (separated by "\n") for debugging.


    Structs

    Schema_JsonParameters struct
    Configuration parameters for JSON serialization.


    Fields:
    • uint8_t enable_pretty_printing: If enabled, JSON will be printed with indentation for better readability.


    Functions

    Schema_Bundle_Load function
    Schema_Bundle* Schema_Bundle_Load(const uint8_t* buffer, uint32_t length)

    Load a serialized schema bundle from a byte buffer.

    This byte buffer should contain a fully loaded binary schema bundle. You can load a schema bundle generated by the schema compiler using the --bundle_out argument yourself, or alternatively, you can generate a file containing a set of C functions to access the binary schema bundle data (Worker_GetSchemaBundleData and Worker_GetSchemaBundleLength) using the schema compiler flag --cpp_bundle_out.

    Make sure to call Schema_Bundle_GetError after loading to check if there were any errors when loading.

    Returns:

  • Schema_Bundle*:

    Parameters
    • const uint8_t*:
    • uint32_t:
  • Schema_Bundle_GetError function
    const char* Schema_Bundle_GetError(const Schema_Bundle* bundle)

    Returns a null-terminated string containing one or more error messages (separated by "\n") if any errors were encountered when loading the schema bundle. Note that the string buffer returned is stored inside the schema bundle, and therefore will be freed when the bundle is destroyed. Will return NULL if there were no errors.

    Returns:

  • const char*:

    Parameters
    • const Schema_Bundle*:
  • Schema_Bundle_Destroy function
    void Schema_Bundle_Destroy(Schema_Bundle* bundle)

    Free the resources associated with a schema bundle.

    Returns:

  • void:

    Parameters
    • Schema_Bundle*:
  • Schema_CreateGenericData function
    Schema_GenericData* Schema_CreateGenericData(void)

    Allocate a generic data object (i.e. arbitrary schema object) type instance.

    Returns:

  • Schema_GenericData*:

    Parameters
    • void:
  • Schema_CopyGenericData function
    Schema_GenericData* Schema_CopyGenericData(const Schema_GenericData* source)

    Performs a deep copy of the source generic data object and returns the new copy.

    Returns:

  • Schema_GenericData*:

    Parameters
    • const Schema_GenericData*:
  • Schema_DestroyGenericData function
    void Schema_DestroyGenericData(Schema_GenericData* request)

    Free the resources associated with a generic data object type instance.

    Returns:

  • void:

    Parameters
    • Schema_GenericData*:
  • Schema_GetGenericDataObject function
    Schema_Object* Schema_GetGenericDataObject(Schema_GenericData* request)

    Get the generic data object as a Schema_Object.

    Returns:

  • Schema_Object*:

    Parameters
    • Schema_GenericData*:
  • Schema_CreateCommandRequest function
    Schema_CommandRequest* Schema_CreateCommandRequest(void)

    Allocate a command request schema type instance.

    Returns:

  • Schema_CommandRequest*:

    Parameters
    • void:
  • Schema_CopyCommandRequest function
    Schema_CommandRequest* Schema_CopyCommandRequest(const Schema_CommandRequest* source)

    Performs a deep copy of the source command request and returns the new copy.

    Returns:

  • Schema_CommandRequest*:

    Parameters
    • const Schema_CommandRequest*:
  • Schema_DestroyCommandRequest function
    void Schema_DestroyCommandRequest(Schema_CommandRequest* request)

    Free the resources associated with a command request schema type instance.

    Returns:

  • void:

    Parameters
    • Schema_CommandRequest*:
  • Schema_GetCommandRequestObject function
    Schema_Object* Schema_GetCommandRequestObject(Schema_CommandRequest* request)

    Get the command request as a Schema_Object.

    Returns:

  • Schema_Object*:

    Parameters
    • Schema_CommandRequest*:
  • Schema_CreateCommandResponse function
    Schema_CommandResponse* Schema_CreateCommandResponse(void)

    Allocate a command response schema type instance.

    Returns:

  • Schema_CommandResponse*:

    Parameters
    • void:
  • Schema_CopyCommandResponse function
    Schema_CommandResponse* Schema_CopyCommandResponse(const Schema_CommandResponse* source)

    Performs a deep copy of the source command response and returns the new copy.

    Returns:

  • Schema_CommandResponse*:

    Parameters
    • const Schema_CommandResponse*:
  • Schema_DestroyCommandResponse function
    void Schema_DestroyCommandResponse(Schema_CommandResponse* response)

    Free the resources associated with a command response schema type instance.

    Returns:

  • void:

    Parameters
    • Schema_CommandResponse*:
  • Schema_GetCommandResponseObject function
    Schema_Object* Schema_GetCommandResponseObject(Schema_CommandResponse* response)

    Get the command response as a Schema_Object.

    Returns:

  • Schema_Object*:

    Parameters
    • Schema_CommandResponse*:
  • Schema_CreateComponentData function
    Schema_ComponentData* Schema_CreateComponentData(void)

    Allocate a component data snapshot schema type instance.

    Returns:

  • Schema_ComponentData*:

    Parameters
    • void:
  • Schema_CopyComponentData function
    Schema_ComponentData* Schema_CopyComponentData(const Schema_ComponentData* source)

    Performs a deep copy of the source component data and returns the new copy.

    Returns:

  • Schema_ComponentData*:

    Parameters
    • const Schema_ComponentData*:
  • Schema_DestroyComponentData function
    void Schema_DestroyComponentData(Schema_ComponentData* data)

    Free the resources associated with a component data snapshot schema type instance.

    Returns:

  • void:

    Parameters
    • Schema_ComponentData*:
  • Schema_GetComponentDataFields function
    Schema_Object* Schema_GetComponentDataFields(Schema_ComponentData* data)

    Get the component data snapshot as a Schema_Object.

    Returns:

  • Schema_Object*:

    Parameters
    • Schema_ComponentData*:
  • Schema_CreateComponentUpdate function
    Schema_ComponentUpdate* Schema_CreateComponentUpdate(void)

    Allocate a component update schema type instance.

    Returns:

  • Schema_ComponentUpdate*:

    Parameters
    • void:
  • Schema_CopyComponentUpdate function
    Schema_ComponentUpdate* Schema_CopyComponentUpdate(const Schema_ComponentUpdate* source)

    Performs a deep copy of the source component update and returns the new copy.

    Returns:

  • Schema_ComponentUpdate*:

    Parameters
    • const Schema_ComponentUpdate*:
  • Schema_DestroyComponentUpdate function
    void Schema_DestroyComponentUpdate(Schema_ComponentUpdate* update)

    Free the resources associated with a component update schema type instance.

    Returns:

  • void:

    Parameters
    • Schema_ComponentUpdate*:
  • Schema_GetComponentUpdateFields function
    Schema_Object* Schema_GetComponentUpdateFields(Schema_ComponentUpdate* update)

    Get an object representing the non-event fields in a component update. This object should be used as if it had one field for each field in the component, whose type corresponds to the type of the field as defined in schema. Note that when an option, list or map field in a component is set to the empty value, it will not / should not appear here. Instead, use Schema_IndexComponentUpdateClearedField and related functions.

    Returns:

  • Schema_Object*:

    Parameters
    • Schema_ComponentUpdate*:
  • Schema_GetComponentUpdateEvents function
    Schema_Object* Schema_GetComponentUpdateEvents(Schema_ComponentUpdate* update)

    Get an object representing the event fields in a component update. This object should be used as if it had one field for each event in the component. Each field behaves like a list (may have multiple instances of the same event), and the field ID of an event is its 1-based position in the order the events appear in the component in the schema.

    Returns:

  • Schema_Object*:

    Parameters
    • Schema_ComponentUpdate*:
  • Schema_ClearComponentUpdateClearedFields function
    void Schema_ClearComponentUpdateClearedFields(Schema_ComponentUpdate* update)

    Clears the list of fields that this update sets to the empty value (for option, list and map fields in a component).

    Returns:

  • void:

    Parameters
    • Schema_ComponentUpdate*:
  • Schema_IsComponentUpdateFieldCleared function
    uint8_t Schema_IsComponentUpdateFieldCleared(Schema_ComponentUpdate* update, Schema_FieldId field_id)

    Checks whether this updates sets an option, list of map field in a component to the empty value.

    Returns:

  • uint8_t:

    Parameters
    • Schema_ComponentUpdate*:
    • Schema_FieldId:
  • Schema_AddComponentUpdateClearedField function
    void Schema_AddComponentUpdateClearedField(Schema_ComponentUpdate* update, Schema_FieldId field_id)

    Specifies that this update sets an option, list or map field in a component to the empty value.

    Returns:

  • void:

    Parameters
    • Schema_ComponentUpdate*:
    • Schema_FieldId:
  • Schema_GetComponentUpdateClearedFieldCount function
    uint32_t Schema_GetComponentUpdateClearedFieldCount(const Schema_ComponentUpdate* update)

    Returns the number of option, list and map fields in a component that this update sets to the empty value.

    Returns:

  • uint32_t:

    Parameters
    • const Schema_ComponentUpdate*:
  • Schema_IndexComponentUpdateClearedField function
    Schema_FieldId Schema_IndexComponentUpdateClearedField(const Schema_ComponentUpdate* update, uint32_t index)

    Returns the field ID of an option, list or map field which is set to the empty value by this update.

    Returns:

  • Schema_FieldId:

    Parameters
    • const Schema_ComponentUpdate*:
    • uint32_t:
  • Schema_GetComponentUpdateClearedFieldList function
    void Schema_GetComponentUpdateClearedFieldList(const Schema_ComponentUpdate* update, Schema_FieldId* output_array)

    Returns all field IDs of option, list, or map fields which are set to the empty value by this component. The output_array should have space for Schema_GetComponentUpdateClearedFieldCount(update) field IDs.

    Returns:

  • void:

    Parameters
    • const Schema_ComponentUpdate*:
    • Schema_FieldId*:
  • Schema_ApplyComponentUpdateToData function
    uint8_t Schema_ApplyComponentUpdateToData(const Schema_ComponentUpdate* update, Schema_ComponentData* target_data)

    Merges a component update 'update' into an at-rest component data object 'target_data'. This is semantically equivalent to a component update being "applied" to the at-rest component data.

    This function will mutate the component data object by appending the bytes representation of the update to the end of the component data. This is efficient because if the component update is small, it wouldn't need to reshuffle any fields under the hood, but will have unbounded memory growth (proportional to the serialized component update after each function call).

    To avoid mutating the data and having unbounded memory growth, use this function in combination with Schema_CopyComponentData to copy the component data first. Note that calling Schema_CopyComponentData on a component data will only require storage for the serialized size of the component data in the returned object, hence why memory growth is no longer unbounded when this is used.

    Returns 1 if success, 0 if there was a failure. Call Schema_GetError(Schema_GetComponentDataFields(target_data)) to get the error message.

    Returns:

  • uint8_t:

    Parameters
    • const Schema_ComponentUpdate*:
    • Schema_ComponentData*:
  • Schema_MergeComponentUpdateIntoUpdate function
    uint8_t Schema_MergeComponentUpdateIntoUpdate(Schema_ComponentUpdate* update, Schema_ComponentUpdate* target_update)

    Merges a component update 'update' into another component update object 'target_update'. This is semantically equivalent to combining two component updates into a single component update such that, when applied to some at-rest component data, it will be semantically equivalent to applying 'target_update' followed by 'update'. 'target_update' will be mutated to contain the resulting combined update.

    Unlike Schema_ApplyComponentUpdateToData, this function will not have unbounded memory growth. To avoid mutating 'target_update', use this function in combination with Schema_CopyComponentUpdate to create a copy which will contain the resulting merged update.

    'update' will be empty after this operation, so ensure to call Schema_DestroyComponentUpdate(update) to avoid leaking memory.

    Returns 1 if success, 0 if there was a failure. Call Schema_GetError(Schema_GetComponentUpdateFields(target_update)) to get the error message.

    Returns:

  • uint8_t:

    Parameters
    • Schema_ComponentUpdate*:
    • Schema_ComponentUpdate*:
  • Schema_ConvertComponentDataIntoUpdate function
    Schema_ComponentUpdate* Schema_ConvertComponentDataIntoUpdate(const Schema_Bundle* bundle, Schema_ComponentId component_id, Schema_ComponentData* data, void* callback_user_data, Schema_ErrorCallback* error_callback)

    Takes an at-rest component data object 'data', and converts it into a component update with all fields set. The resulting component update has the property that if applied to a component data object, it is guaranteed to result in the original at-rest component data object 'data'. Any fields contained in 'data' which are not present in the component definition will be dropped.

    This operation requires a component definition to be provided at runtime in a schema bundle. See Schema_Bundle_Load for more information.

    If successful, 'data' will become empty after this operation. Otherwise, 'data' will be left in a valid but unspecified state. After calling this function, we recommend immediately calling Schema_DestroyComponentData(data) to avoid leaking memory.

    A new component update object will be returned to the caller on success, otherwise NULL will be returned on failure.

    An error callback can be optionally provided to get more information as to why the operation failed. 'callback_user_data' is an arbitrary value that will be passed to the callback. If unused, or no error callback is specified, this parameter can be set to NULL.

    Returns:

  • Schema_ComponentUpdate*:

    Parameters
    • const Schema_Bundle*:
    • Schema_ComponentId:
    • Schema_ComponentData*:
    • void*:
    • Schema_ErrorCallback*:
  • Schema_Clear function
    void Schema_Clear(Schema_Object* object)

    Completely clears all fields in the given object.

    Returns:

  • void:

    Parameters
    • Schema_Object*:
  • Schema_ClearField function
    void Schema_ClearField(Schema_Object* object, Schema_FieldId field_id)

    Completely clears the given field ID in the given object.

    Returns:

  • void:

    Parameters
    • Schema_Object*:
    • Schema_FieldId:
  • Schema_ShallowCopy function
    void Schema_ShallowCopy(const Schema_Object* src, Schema_Object* dst)

    Copies all fields from src to dst. The copy is shallow; changes made to object fields in the source will also be reflected in the copied fields.

    If src == dst, or if the objects are not associated with the same root schema type instance, no operation is performed.

    Returns:

  • void:

    Parameters
    • const Schema_Object*:
    • Schema_Object*:
  • Schema_ShallowCopyField function
    void Schema_ShallowCopyField(const Schema_Object* src, Schema_Object* dst, Schema_FieldId field_id)

    Copies over a field from src to dst. If multiple fields with the given field_id exist all are copied. The copy is shallow; changes made to object fields in the source will also be reflected in the copied fields.

    If src == dst, or if the objects are not associated with the same root schema type instance, no operation is performed.

    Returns:

  • void:

    Parameters
    • const Schema_Object*:
    • Schema_Object*:
    • Schema_FieldId:
  • Schema_AllocateObject function
    Schema_Object* Schema_AllocateObject(const Schema_Object* object)

    Allocates an orphaned Schema_Object in memory owned by the given Schema_Object instance. The returned object is owned by the associated schema type instance, but is not reachable from any other object. The memory is freed by a call to the Schema_DestroyX function associated with the parent object.

    Returns:

  • Schema_Object*:

    Parameters
    • const Schema_Object*:
  • Schema_AllocateBuffer function
    uint8_t* Schema_AllocateBuffer(Schema_Object* object, uint32_t length)

    Allocates a buffer of the specified length in bytes from memory owned by the given Schema_Object instance. The memory is freed by a call to the Schema_DestroyX function associated with the parent object.

    Note: this is useful for allocating memory that must live as long as the root schema type instance, for example to pass to Schema_MergeFromBuffer.

    Returns:

  • uint8_t*:

    Parameters
    • Schema_Object*:
    • uint32_t:
  • Schema_MergeFromBuffer function
    uint8_t Schema_MergeFromBuffer(Schema_Object* object, const uint8_t* buffer, uint32_t length)

    Merges the given buffer into the given object, appending all fields. This function can fail; if the return value is zero, call Schema_GetError to obtain an error string.

    Note: the provided buffer is not copied, and must live as long as the root schema type instance.

    Returns:

  • uint8_t:

    Parameters
    • Schema_Object*:
    • const uint8_t*:
    • uint32_t:
  • Schema_GetWriteBufferLength function
    uint32_t Schema_GetWriteBufferLength(const Schema_Object* object)

    Computes the serialized length of the given Schema_Object.

    Returns:

  • uint32_t:

    Parameters
    • const Schema_Object*:
  • Schema_SerializeToBuffer function
    uint8_t Schema_SerializeToBuffer(const Schema_Object* object, uint8_t* buffer, uint32_t length)

    Serializes the given object into the provided buffer, which must have space at least equal to the length returned by Schema_WriteBufferLength. This function can fail; if the return value is zero, call Schema_GetError to obtain an error string.

    length must equal the value returned by Schema_GetWriteBufferLength. Otherwise, the behavior is undefined.

    Returns:

  • uint8_t:

    Parameters
    • const Schema_Object*:
    • uint8_t*:
    • uint32_t:
  • Schema_GetError function
    const char* Schema_GetError(const Schema_Object* object)

    Obtains the most recent error encountered by any object associated with the given object. The buffer is owned by the schema object that manages the memory of object, and may get replaced after calling another Schema function. Returns NULL if no error has occurred within the given object.

    Returns:

  • const char*:

    Parameters
    • const Schema_Object*:
  • Schema_GetUniqueFieldIdCount function
    uint32_t Schema_GetUniqueFieldIdCount(const Schema_Object* object)

    Returns the number of unique field IDs used in the Schema_Object.

    Returns:

  • uint32_t:

    Parameters
    • const Schema_Object*:
  • Schema_GetUniqueFieldIds function
    void Schema_GetUniqueFieldIds(const Schema_Object* object, uint32_t* buffer)

    Returns the sorted list of unique field IDs used in the Schema_Object. The buffer parameter must have space remaining for as many field IDs as indicated by Schema_GetUniqueFieldIdCount.

    Returns:

  • void:

    Parameters
    • const Schema_Object*:
    • uint32_t*:
  • Schema_AddFloat function
    void Schema_AddFloat(Schema_Object* object, Schema_FieldId field_id, float value)


    Returns:

  • void:

    Parameters
    • Schema_Object*:
    • Schema_FieldId:
    • float:
  • Schema_AddDouble function
    void Schema_AddDouble(Schema_Object* object, Schema_FieldId field_id, double value)


    Returns:

  • void:

    Parameters
    • Schema_Object*:
    • Schema_FieldId:
    • double:
  • Schema_AddBool function
    void Schema_AddBool(Schema_Object* object, Schema_FieldId field_id, uint8_t value)


    Returns:

  • void:

    Parameters
    • Schema_Object*:
    • Schema_FieldId:
    • uint8_t:
  • Schema_AddInt32 function
    void Schema_AddInt32(Schema_Object* object, Schema_FieldId field_id, int32_t value)


    Returns:

  • void:

    Parameters
    • Schema_Object*:
    • Schema_FieldId:
    • int32_t:
  • Schema_AddInt64 function
    void Schema_AddInt64(Schema_Object* object, Schema_FieldId field_id, int64_t value)


    Returns:

  • void:

    Parameters
    • Schema_Object*:
    • Schema_FieldId:
    • int64_t:
  • Schema_AddUint32 function
    void Schema_AddUint32(Schema_Object* object, Schema_FieldId field_id, uint32_t value)


    Returns:

  • void:

    Parameters
    • Schema_Object*:
    • Schema_FieldId:
    • uint32_t:
  • Schema_AddUint64 function
    void Schema_AddUint64(Schema_Object* object, Schema_FieldId field_id, uint64_t value)


    Returns:

  • void:

    Parameters
    • Schema_Object*:
    • Schema_FieldId:
    • uint64_t:
  • Schema_AddSint32 function
    void Schema_AddSint32(Schema_Object* object, Schema_FieldId field_id, int32_t value)


    Returns:

  • void:

    Parameters
    • Schema_Object*:
    • Schema_FieldId:
    • int32_t:
  • Schema_AddSint64 function
    void Schema_AddSint64(Schema_Object* object, Schema_FieldId field_id, int64_t value)


    Returns:

  • void:

    Parameters
    • Schema_Object*:
    • Schema_FieldId:
    • int64_t:
  • Schema_AddFixed32 function
    void Schema_AddFixed32(Schema_Object* object, Schema_FieldId field_id, uint32_t value)


    Returns:

  • void:

    Parameters
    • Schema_Object*:
    • Schema_FieldId:
    • uint32_t:
  • Schema_AddFixed64 function
    void Schema_AddFixed64(Schema_Object* object, Schema_FieldId field_id, uint64_t value)


    Returns:

  • void:

    Parameters
    • Schema_Object*:
    • Schema_FieldId:
    • uint64_t:
  • Schema_AddSfixed32 function
    void Schema_AddSfixed32(Schema_Object* object, Schema_FieldId field_id, int32_t value)


    Returns:

  • void:

    Parameters
    • Schema_Object*:
    • Schema_FieldId:
    • int32_t:
  • Schema_AddSfixed64 function
    void Schema_AddSfixed64(Schema_Object* object, Schema_FieldId field_id, int64_t value)


    Returns:

  • void:

    Parameters
    • Schema_Object*:
    • Schema_FieldId:
    • int64_t:
  • Schema_AddEntityId function
    void Schema_AddEntityId(Schema_Object* object, Schema_FieldId field_id, Schema_EntityId value)


    Returns:

  • void:

    Parameters
    • Schema_Object*:
    • Schema_FieldId:
    • Schema_EntityId:
  • Schema_AddEnum function
    void Schema_AddEnum(Schema_Object* object, Schema_FieldId field_id, uint32_t value)


    Returns:

  • void:

    Parameters
    • Schema_Object*:
    • Schema_FieldId:
    • uint32_t:
  • Schema_AddBytes function
    void Schema_AddBytes(Schema_Object* object, Schema_FieldId field_id, const uint8_t* buffer, uint32_t length)


    Returns:

  • void:

    Parameters
    • Schema_Object*:
    • Schema_FieldId:
    • const uint8_t*:
    • uint32_t:
  • Schema_AddObject function
    Schema_Object* Schema_AddObject(Schema_Object* object, Schema_FieldId field_id)


    Returns:

  • Schema_Object*:

    Parameters
    • Schema_Object*:
    • Schema_FieldId:
  • Schema_AddFloatList function
    void Schema_AddFloatList(Schema_Object* object, Schema_FieldId field_id, const float* values, uint32_t count)


    Returns:

  • void:

    Parameters
    • Schema_Object*:
    • Schema_FieldId:
    • const float*:
    • uint32_t:
  • Schema_AddDoubleList function
    void Schema_AddDoubleList(Schema_Object* object, Schema_FieldId field_id, const double* values, uint32_t count)


    Returns:

  • void:

    Parameters
    • Schema_Object*:
    • Schema_FieldId:
    • const double*:
    • uint32_t:
  • Schema_AddBoolList function
    void Schema_AddBoolList(Schema_Object* object, Schema_FieldId field_id, const uint8_t* values, uint32_t count)


    Returns:

  • void:

    Parameters
    • Schema_Object*:
    • Schema_FieldId:
    • const uint8_t*:
    • uint32_t:
  • Schema_AddInt32List function
    void Schema_AddInt32List(Schema_Object* object, Schema_FieldId field_id, const int32_t* values, uint32_t count)


    Returns:

  • void:

    Parameters
    • Schema_Object*:
    • Schema_FieldId:
    • const int32_t*:
    • uint32_t:
  • Schema_AddInt64List function
    void Schema_AddInt64List(Schema_Object* object, Schema_FieldId field_id, const int64_t* values, uint32_t count)


    Returns:

  • void:

    Parameters
    • Schema_Object*:
    • Schema_FieldId:
    • const int64_t*:
    • uint32_t:
  • Schema_AddUint32List function
    void Schema_AddUint32List(Schema_Object* object, Schema_FieldId field_id, const uint32_t* values, uint32_t count)


    Returns:

  • void:

    Parameters
    • Schema_Object*:
    • Schema_FieldId:
    • const uint32_t*:
    • uint32_t:
  • Schema_AddUint64List function
    void Schema_AddUint64List(Schema_Object* object, Schema_FieldId field_id, const uint64_t* values, uint32_t count)


    Returns:

  • void:

    Parameters
    • Schema_Object*:
    • Schema_FieldId:
    • const uint64_t*:
    • uint32_t:
  • Schema_AddSint32List function
    void Schema_AddSint32List(Schema_Object* object, Schema_FieldId field_id, const int32_t* values, uint32_t count)


    Returns:

  • void:

    Parameters
    • Schema_Object*:
    • Schema_FieldId:
    • const int32_t*:
    • uint32_t:
  • Schema_AddSint64List function
    void Schema_AddSint64List(Schema_Object* object, Schema_FieldId field_id, const int64_t* values, uint32_t count)


    Returns:

  • void:

    Parameters
    • Schema_Object*:
    • Schema_FieldId:
    • const int64_t*:
    • uint32_t:
  • Schema_AddFixed32List function
    void Schema_AddFixed32List(Schema_Object* object, Schema_FieldId field_id, const uint32_t* values, uint32_t count)


    Returns:

  • void:

    Parameters
    • Schema_Object*:
    • Schema_FieldId:
    • const uint32_t*:
    • uint32_t:
  • Schema_AddFixed64List function
    void Schema_AddFixed64List(Schema_Object* object, Schema_FieldId field_id, const uint64_t* values, uint32_t count)


    Returns:

  • void:

    Parameters
    • Schema_Object*:
    • Schema_FieldId:
    • const uint64_t*:
    • uint32_t:
  • Schema_AddSfixed32List function
    void Schema_AddSfixed32List(Schema_Object* object, Schema_FieldId field_id, const int32_t* values, uint32_t count)


    Returns:

  • void:

    Parameters
    • Schema_Object*:
    • Schema_FieldId:
    • const int32_t*:
    • uint32_t:
  • Schema_AddSfixed64List function
    void Schema_AddSfixed64List(Schema_Object* object, Schema_FieldId field_id, const int64_t* values, uint32_t count)


    Returns:

  • void:

    Parameters
    • Schema_Object*:
    • Schema_FieldId:
    • const int64_t*:
    • uint32_t:
  • Schema_AddEntityIdList function
    void Schema_AddEntityIdList(Schema_Object* object, Schema_FieldId field_id, const Schema_EntityId* values, uint32_t count)


    Returns:

  • void:

    Parameters
    • Schema_Object*:
    • Schema_FieldId:
    • const Schema_EntityId*:
    • uint32_t:
  • Schema_AddEnumList function
    void Schema_AddEnumList(Schema_Object* object, Schema_FieldId field_id, const uint32_t* values, uint32_t count)


    Returns:

  • void:

    Parameters
    • Schema_Object*:
    • Schema_FieldId:
    • const uint32_t*:
    • uint32_t:
  • Schema_GetFloatCount function
    uint32_t Schema_GetFloatCount(const Schema_Object* object, Schema_FieldId field_id)


    Returns:

  • uint32_t:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
  • Schema_GetDoubleCount function
    uint32_t Schema_GetDoubleCount(const Schema_Object* object, Schema_FieldId field_id)


    Returns:

  • uint32_t:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
  • Schema_GetBoolCount function
    uint32_t Schema_GetBoolCount(const Schema_Object* object, Schema_FieldId field_id)


    Returns:

  • uint32_t:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
  • Schema_GetInt32Count function
    uint32_t Schema_GetInt32Count(const Schema_Object* object, Schema_FieldId field_id)


    Returns:

  • uint32_t:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
  • Schema_GetInt64Count function
    uint32_t Schema_GetInt64Count(const Schema_Object* object, Schema_FieldId field_id)


    Returns:

  • uint32_t:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
  • Schema_GetUint32Count function
    uint32_t Schema_GetUint32Count(const Schema_Object* object, Schema_FieldId field_id)


    Returns:

  • uint32_t:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
  • Schema_GetUint64Count function
    uint32_t Schema_GetUint64Count(const Schema_Object* object, Schema_FieldId field_id)


    Returns:

  • uint32_t:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
  • Schema_GetSint32Count function
    uint32_t Schema_GetSint32Count(const Schema_Object* object, Schema_FieldId field_id)


    Returns:

  • uint32_t:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
  • Schema_GetSint64Count function
    uint32_t Schema_GetSint64Count(const Schema_Object* object, Schema_FieldId field_id)


    Returns:

  • uint32_t:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
  • Schema_GetFixed32Count function
    uint32_t Schema_GetFixed32Count(const Schema_Object* object, Schema_FieldId field_id)


    Returns:

  • uint32_t:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
  • Schema_GetFixed64Count function
    uint32_t Schema_GetFixed64Count(const Schema_Object* object, Schema_FieldId field_id)


    Returns:

  • uint32_t:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
  • Schema_GetSfixed32Count function
    uint32_t Schema_GetSfixed32Count(const Schema_Object* object, Schema_FieldId field_id)


    Returns:

  • uint32_t:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
  • Schema_GetSfixed64Count function
    uint32_t Schema_GetSfixed64Count(const Schema_Object* object, Schema_FieldId field_id)


    Returns:

  • uint32_t:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
  • Schema_GetEntityIdCount function
    uint32_t Schema_GetEntityIdCount(const Schema_Object* object, Schema_FieldId field_id)


    Returns:

  • uint32_t:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
  • Schema_GetEnumCount function
    uint32_t Schema_GetEnumCount(const Schema_Object* object, Schema_FieldId field_id)


    Returns:

  • uint32_t:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
  • Schema_GetBytesCount function
    uint32_t Schema_GetBytesCount(const Schema_Object* object, Schema_FieldId field_id)


    Returns:

  • uint32_t:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
  • Schema_GetObjectCount function
    uint32_t Schema_GetObjectCount(const Schema_Object* object, Schema_FieldId field_id)


    Returns:

  • uint32_t:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
  • Schema_GetFloat function
    float Schema_GetFloat(const Schema_Object* object, Schema_FieldId field_id)


    Returns:

  • float:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
  • Schema_GetDouble function
    double Schema_GetDouble(const Schema_Object* object, Schema_FieldId field_id)


    Returns:

  • double:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
  • Schema_GetBool function
    uint8_t Schema_GetBool(const Schema_Object* object, Schema_FieldId field_id)


    Returns:

  • uint8_t:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
  • Schema_GetInt32 function
    int32_t Schema_GetInt32(const Schema_Object* object, Schema_FieldId field_id)


    Returns:

  • int32_t:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
  • Schema_GetInt64 function
    int64_t Schema_GetInt64(const Schema_Object* object, Schema_FieldId field_id)


    Returns:

  • int64_t:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
  • Schema_GetUint32 function
    uint32_t Schema_GetUint32(const Schema_Object* object, Schema_FieldId field_id)


    Returns:

  • uint32_t:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
  • Schema_GetUint64 function
    uint64_t Schema_GetUint64(const Schema_Object* object, Schema_FieldId field_id)


    Returns:

  • uint64_t:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
  • Schema_GetSint32 function
    int32_t Schema_GetSint32(const Schema_Object* object, Schema_FieldId field_id)


    Returns:

  • int32_t:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
  • Schema_GetSint64 function
    int64_t Schema_GetSint64(const Schema_Object* object, Schema_FieldId field_id)


    Returns:

  • int64_t:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
  • Schema_GetFixed32 function
    uint32_t Schema_GetFixed32(const Schema_Object* object, Schema_FieldId field_id)


    Returns:

  • uint32_t:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
  • Schema_GetFixed64 function
    uint64_t Schema_GetFixed64(const Schema_Object* object, Schema_FieldId field_id)


    Returns:

  • uint64_t:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
  • Schema_GetSfixed32 function
    int32_t Schema_GetSfixed32(const Schema_Object* object, Schema_FieldId field_id)


    Returns:

  • int32_t:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
  • Schema_GetSfixed64 function
    int64_t Schema_GetSfixed64(const Schema_Object* object, Schema_FieldId field_id)


    Returns:

  • int64_t:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
  • Schema_GetEntityId function
    Schema_EntityId Schema_GetEntityId(const Schema_Object* object, Schema_FieldId field_id)


    Returns:

  • Schema_EntityId:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
  • Schema_GetEnum function
    uint32_t Schema_GetEnum(const Schema_Object* object, Schema_FieldId field_id)


    Returns:

  • uint32_t:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
  • Schema_GetBytesLength function
    uint32_t Schema_GetBytesLength(const Schema_Object* object, Schema_FieldId field_id)


    Returns:

  • uint32_t:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
  • Schema_GetBytes function
    const uint8_t* Schema_GetBytes(const Schema_Object* object, Schema_FieldId field_id)


    Returns:

  • const uint8_t*:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
  • Schema_GetObject function
    Schema_Object* Schema_GetObject(Schema_Object* object, Schema_FieldId field_id)


    Returns:

  • Schema_Object*:

    Parameters
    • Schema_Object*:
    • Schema_FieldId:
  • Schema_IndexFloat function
    float Schema_IndexFloat(const Schema_Object* object, Schema_FieldId field_id, uint32_t index)


    Returns:

  • float:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
    • uint32_t:
  • Schema_IndexDouble function
    double Schema_IndexDouble(const Schema_Object* object, Schema_FieldId field_id, uint32_t index)


    Returns:

  • double:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
    • uint32_t:
  • Schema_IndexBool function
    uint8_t Schema_IndexBool(const Schema_Object* object, Schema_FieldId field_id, uint32_t index)


    Returns:

  • uint8_t:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
    • uint32_t:
  • Schema_IndexInt32 function
    int32_t Schema_IndexInt32(const Schema_Object* object, Schema_FieldId field_id, uint32_t index)


    Returns:

  • int32_t:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
    • uint32_t:
  • Schema_IndexInt64 function
    int64_t Schema_IndexInt64(const Schema_Object* object, Schema_FieldId field_id, uint32_t index)


    Returns:

  • int64_t:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
    • uint32_t:
  • Schema_IndexUint32 function
    uint32_t Schema_IndexUint32(const Schema_Object* object, Schema_FieldId field_id, uint32_t index)


    Returns:

  • uint32_t:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
    • uint32_t:
  • Schema_IndexUint64 function
    uint64_t Schema_IndexUint64(const Schema_Object* object, Schema_FieldId field_id, uint32_t index)


    Returns:

  • uint64_t:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
    • uint32_t:
  • Schema_IndexSint32 function
    int32_t Schema_IndexSint32(const Schema_Object* object, Schema_FieldId field_id, uint32_t index)


    Returns:

  • int32_t:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
    • uint32_t:
  • Schema_IndexSint64 function
    int64_t Schema_IndexSint64(const Schema_Object* object, Schema_FieldId field_id, uint32_t index)


    Returns:

  • int64_t:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
    • uint32_t:
  • Schema_IndexFixed32 function
    uint32_t Schema_IndexFixed32(const Schema_Object* object, Schema_FieldId field_id, uint32_t index)


    Returns:

  • uint32_t:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
    • uint32_t:
  • Schema_IndexFixed64 function
    uint64_t Schema_IndexFixed64(const Schema_Object* object, Schema_FieldId field_id, uint32_t index)


    Returns:

  • uint64_t:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
    • uint32_t:
  • Schema_IndexSfixed32 function
    int32_t Schema_IndexSfixed32(const Schema_Object* object, Schema_FieldId field_id, uint32_t index)


    Returns:

  • int32_t:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
    • uint32_t:
  • Schema_IndexSfixed64 function
    int64_t Schema_IndexSfixed64(const Schema_Object* object, Schema_FieldId field_id, uint32_t index)


    Returns:

  • int64_t:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
    • uint32_t:
  • Schema_IndexEntityId function
    Schema_EntityId Schema_IndexEntityId(const Schema_Object* object, Schema_FieldId field_id, uint32_t index)


    Returns:

  • Schema_EntityId:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
    • uint32_t:
  • Schema_IndexEnum function
    uint32_t Schema_IndexEnum(const Schema_Object* object, Schema_FieldId field_id, uint32_t index)


    Returns:

  • uint32_t:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
    • uint32_t:
  • Schema_IndexBytesLength function
    uint32_t Schema_IndexBytesLength(const Schema_Object* object, Schema_FieldId field_id, uint32_t index)


    Returns:

  • uint32_t:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
    • uint32_t:
  • Schema_IndexBytes function
    const uint8_t* Schema_IndexBytes(const Schema_Object* object, Schema_FieldId field_id, uint32_t index)


    Returns:

  • const uint8_t*:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
    • uint32_t:
  • Schema_IndexObject function
    Schema_Object* Schema_IndexObject(Schema_Object* object, Schema_FieldId field_id, uint32_t index)


    Returns:

  • Schema_Object*:

    Parameters
    • Schema_Object*:
    • Schema_FieldId:
    • uint32_t:
  • Schema_GetFloatList function
    void Schema_GetFloatList(const Schema_Object* object, Schema_FieldId field_id, float* output_array)


    Returns:

  • void:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
    • float*:
  • Schema_GetDoubleList function
    void Schema_GetDoubleList(const Schema_Object* object, Schema_FieldId field_id, double* output_array)


    Returns:

  • void:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
    • double*:
  • Schema_GetBoolList function
    void Schema_GetBoolList(const Schema_Object* object, Schema_FieldId field_id, uint8_t* output_array)


    Returns:

  • void:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
    • uint8_t*:
  • Schema_GetInt32List function
    void Schema_GetInt32List(const Schema_Object* object, Schema_FieldId field_id, int32_t* output_array)


    Returns:

  • void:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
    • int32_t*:
  • Schema_GetInt64List function
    void Schema_GetInt64List(const Schema_Object* object, Schema_FieldId field_id, int64_t* output_array)


    Returns:

  • void:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
    • int64_t*:
  • Schema_GetUint32List function
    void Schema_GetUint32List(const Schema_Object* object, Schema_FieldId field_id, uint32_t* output_array)


    Returns:

  • void:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
    • uint32_t*:
  • Schema_GetUint64List function
    void Schema_GetUint64List(const Schema_Object* object, Schema_FieldId field_id, uint64_t* output_array)


    Returns:

  • void:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
    • uint64_t*:
  • Schema_GetSint32List function
    void Schema_GetSint32List(const Schema_Object* object, Schema_FieldId field_id, int32_t* output_array)


    Returns:

  • void:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
    • int32_t*:
  • Schema_GetSint64List function
    void Schema_GetSint64List(const Schema_Object* object, Schema_FieldId field_id, int64_t* output_array)


    Returns:

  • void:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
    • int64_t*:
  • Schema_GetFixed32List function
    void Schema_GetFixed32List(const Schema_Object* object, Schema_FieldId field_id, uint32_t* output_array)


    Returns:

  • void:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
    • uint32_t*:
  • Schema_GetFixed64List function
    void Schema_GetFixed64List(const Schema_Object* object, Schema_FieldId field_id, uint64_t* output_array)


    Returns:

  • void:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
    • uint64_t*:
  • Schema_GetSfixed32List function
    void Schema_GetSfixed32List(const Schema_Object* object, Schema_FieldId field_id, int32_t* output_array)


    Returns:

  • void:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
    • int32_t*:
  • Schema_GetSfixed64List function
    void Schema_GetSfixed64List(const Schema_Object* object, Schema_FieldId field_id, int64_t* output_array)


    Returns:

  • void:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
    • int64_t*:
  • Schema_GetEntityIdList function
    void Schema_GetEntityIdList(const Schema_Object* object, Schema_FieldId field_id, Schema_EntityId* output_array)


    Returns:

  • void:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
    • Schema_EntityId*:
  • Schema_GetEnumList function
    void Schema_GetEnumList(const Schema_Object* object, Schema_FieldId field_id, uint32_t* output_array)


    Returns:

  • void:

    Parameters
    • const Schema_Object*:
    • Schema_FieldId:
    • uint32_t*:
  • Schema_Json_Destroy function
    void Schema_Json_Destroy(Schema_Json* json)

    Free the resources associated with a Schema_Json instance.

    Returns:

  • void:

    Parameters
    • Schema_Json*:
  • Schema_Json_GetJsonString function
    const char* Schema_Json_GetJsonString(const Schema_Json* json)

    Get a null-terminated JSON string from a Schema_Json instance.

    The returned pointer will be valid until the source Schema_Json object is destroyed with Schema_Json_Destroy.

    Returns:

  • const char*:

    Parameters
    • const Schema_Json*:
  • Schema_Json_GetLastError function
    const char* Schema_Json_GetLastError(void)

    Get a null-terminated string containing the last set of errors that occurred while performing JSON operations. If multiple errors occur, they will be separated by a newline ("\n"). Returns NULL if no error occurred.

    The returned pointer will remain valid until another SchemaJson* function (with the exception Schema_Json_GetLastWarning) is called from the same thread.

    Returns:

  • const char*:

    Parameters
    • void:
  • Schema_Json_GetLastWarning function
    const char* Schema_Json_GetLastWarning(void)

    Get a null-terminated string containing the last warning that occurred while performing JSON operations. If multiple warnings occur, they will be separated by a newline ("\n"). Returns NULL if no warning occurred.

    The returned pointer will remain valid until another SchemaJson* function (with the exception Schema_Json_GetLastError) is called from the same thread.

    Returns:

  • const char*:

    Parameters
    • void:
  • Schema_Json_LoadObject function
    uint8_t Schema_Json_LoadObject(const Schema_Bundle* bundle, const char* qualified_type_name, const char* json_string, Schema_Object* object)

    Loads a Schema_Object from the provided null-terminated JSON string given the provided schema bundle and qualified type name.

    Returns 1 if no error occurred. Returns 0 if there was a failure to read any data from the JSON; use Schema_Json_GetLastError to get a string description of the error that occurred.

    Note: Warnings may also be generated in some cases. Use Schema_Json_GetLastWarning to get a string description of any warning that occurred during this operation.

    Returns:

  • uint8_t:

    Parameters
    • const Schema_Bundle*:
    • const char*:
    • const char*:
    • Schema_Object*:
  • Schema_Json_DumpObject function
    Schema_Json* Schema_Json_DumpObject(const Schema_Bundle* bundle, const char* qualified_type_name, Schema_Object* object)

    Dumps the given Schema_Object instance into a Schema_Json using the provided bundle and qualified type name.

    It is the caller's responsibility to free the returned Schema_Json* by calling Schema_Json_Destroy.

    Note: Returns NULL if an error occurred. Use Schema_Json_GetLastError to get a string description of the error that occurred during this operation.

    Note: Warnings may also be generated in some cases. Use Schema_Json_GetLastWarning to get a string description of any warning that occurred during this operation.

    Returns:

  • Schema_Json*:

    Parameters
    • const Schema_Bundle*:
    • const char*:
    • Schema_Object*:
  • Schema_Json_LoadComponentData function
    Schema_ComponentData* Schema_Json_LoadComponentData(const Schema_Bundle* bundle, Schema_ComponentId component_id, const char* json_string)

    Loads a Schema_ComponentData from the provided JSON string given the provided schema bundle and component ID.

    It is the caller's responsibility to free the returned Schema_ComponentData* by calling Schema_DestroyComponentData.

    Note: Returns NULL if an error occurred. Use Schema_Json_GetLastError to get a string description of the error that occurred during this operation.

    Note: Warnings may also be generated in some cases. Use Schema_Json_GetLastWarning to get a string description of any warning that occurred during this operation.

    Returns:

  • Schema_ComponentData*:

    Parameters
    • const Schema_Bundle*:
    • Schema_ComponentId:
    • const char*:
  • Schema_Json_DumpComponentData function
    Schema_Json* Schema_Json_DumpComponentData(const Schema_Bundle* bundle, Schema_ComponentId component_id, Schema_ComponentData* data)

    Dumps the given Schema_ComponentData instance into a Schema_Json using the provided bundle and component ID.

    It is the caller's responsibility to free the returned Schema_Json* by calling Schema_Json_Destroy.

    Note: Returns NULL if an error occurred. Use Schema_Json_GetLastError to get a string description of the error that occurred during this operation.

    Note: Warnings may also be generated in some cases. Use Schema_Json_GetLastWarning to get a string description of any warning that occurred during this operation.

    Returns:

  • Schema_Json*:

    Parameters
    • const Schema_Bundle*:
    • Schema_ComponentId:
    • Schema_ComponentData*:
  • Schema_Json_LoadComponentUpdate function
    Schema_ComponentUpdate* Schema_Json_LoadComponentUpdate(const Schema_Bundle* bundle, Schema_ComponentId component_id, const char* json_string)

    Loads a Schema_ComponentUpdate from the provided JSON string given the provided schema bundle and component ID.

    It is the caller's responsibility to free the returned Schema_ComponentUpdate* by calling Schema_DestroyComponentUpdate.

    Note: Returns NULL if an error occurred. Use Schema_Json_GetLastError to get a string description of the error that occurred during this operation.

    Note: Warnings may also be generated in some cases. Use Schema_Json_GetLastWarning to get a string description of any warning that occurred during this operation.

    Returns:

  • Schema_ComponentUpdate*:

    Parameters
    • const Schema_Bundle*:
    • Schema_ComponentId:
    • const char*:
  • Schema_Json_DumpComponentUpdate function
    Schema_Json* Schema_Json_DumpComponentUpdate(const Schema_Bundle* bundle, Schema_ComponentId component_id, Schema_ComponentUpdate* update)

    Dumps the given Schema_ComponentUpdate instance into a Schema_Json using the provided bundle and component ID.

    It is the caller's responsibility to free the returned Schema_Json* by calling Schema_Json_Destroy.

    Note: Returns NULL if an error occurred. Use Schema_Json_GetLastError to get a string description of the error that occurred during this operation.

    Note: Warnings may also be generated in some cases. Use Schema_Json_GetLastWarning to get a string description of any warning that occurred during this operation.

    Returns:

  • Schema_Json*:

    Parameters
    • const Schema_Bundle*:
    • Schema_ComponentId:
    • Schema_ComponentUpdate*:
  • Schema_Json_LoadCommandRequest function
    Schema_CommandRequest* Schema_Json_LoadCommandRequest(const Schema_Bundle* bundle, Schema_ComponentId component_id, Schema_FieldId command_index, const char* json_string)

    Loads a Schema_CommandRequest from the provided JSON string given the provided schema bundle and component ID.

    It is the caller's responsibility to free the returned Schema_CommandRequest* by calling Schema_DestroyCommandRequest.

    Note: Returns NULL if an error occurred. Use Schema_Json_GetLastError to get a string description of the error that occurred during this operation.

    Note: Warnings may also be generated in some cases. Use Schema_Json_GetLastWarning to get a string description of any warning that occurred during this operation.

    Returns:

  • Schema_CommandRequest*:

    Parameters
    • const Schema_Bundle*:
    • Schema_ComponentId:
    • Schema_FieldId:
    • const char*:
  • Schema_Json_DumpCommandRequest function
    Schema_Json* Schema_Json_DumpCommandRequest(const Schema_Bundle* bundle, Schema_ComponentId component_id, Schema_FieldId command_index, Schema_CommandRequest* request)

    Dumps the given Schema_CommandRequest instance into a Schema_Json using the provided schema bundle, component ID and command index.

    It is the caller's responsibility to free the returned Schema_Json* by calling Schema_Json_Destroy.

    Note: Returns NULL if an error occurred. Use Schema_Json_GetLastError to get a string description of the error that occurred during this operation.

    Note: Warnings may also be generated in some cases. Use Schema_Json_GetLastWarning to get a string description of any warning that occurred during this operation.

    Returns:

  • Schema_Json*:

    Parameters
    • const Schema_Bundle*:
    • Schema_ComponentId:
    • Schema_FieldId:
    • Schema_CommandRequest*:
  • Schema_Json_LoadCommandResponse function
    Schema_CommandResponse* Schema_Json_LoadCommandResponse(const Schema_Bundle* bundle, Schema_ComponentId component_id, Schema_FieldId command_index, const char* json_string)

    Loads a Schema_CommandResponse from the provided JSON string given the provided bundle, component ID, and command index.

    It is the caller's responsibility to free the returned Schema_CommandResponse* by calling Schema_DestroyCommandResponse.

    Note: Returns NULL if an error occurred. Use Schema_Json_GetLastError to get a string description of the error that occurred during this operation.

    Note: Warnings may also be generated in some cases. Use Schema_Json_GetLastWarning to get a string description of any warning that occurred during this operation.

    Returns:

  • Schema_CommandResponse*:

    Parameters
    • const Schema_Bundle*:
    • Schema_ComponentId:
    • Schema_FieldId:
    • const char*:
  • Schema_Json_DumpCommandResponse function
    Schema_Json* Schema_Json_DumpCommandResponse(const Schema_Bundle* bundle, Schema_ComponentId component_id, Schema_FieldId command_index, Schema_CommandResponse* response)

    Dumps the given Schema_CommandResponse instance into a Schema_Json using the provided schema bundle, component ID and command index.

    It is the caller's responsibility to free the returned Schema_Json* by calling Schema_Json_Destroy.

    Note: Returns NULL if an error occurred. Use Schema_Json_GetLastError to get a string description of the error that occurred during this operation.

    Note: Warnings may also be generated in some cases. Use Schema_Json_GetLastWarning to get a string description of any warning that occurred during this operation.

    Returns:

  • Schema_Json*:

    Parameters
    • const Schema_Bundle*:
    • Schema_ComponentId:
    • Schema_FieldId:
    • Schema_CommandResponse*:
  • c_trace.h


    Macros

    WORKER_SDK_C_INCLUDE_IMPROBABLE_C_COMMON_TRACE macro



    Type Definitions

    Trace_EventTracer typedef
    typedef struct Trace_EventTracer Trace_EventTracer

    Io_Storage typedef
    typedef struct Io_Storage Io_Storage

    Io_Stream typedef
    typedef struct Io_Stream Io_Stream

    Trace_EventData typedef
    typedef struct Trace_EventData Trace_EventData
    Data for an event. This is a collection of key-value pairs (fields). Use TraceEventData* to read or write fields.

    Trace_Callback typedef
    typedef void Trace_Callback(void *user_data, const Trace_Item *item)
    The callback type for spans or events added to the Trace_EventTracer. The Trace_Item will only be valid for the duration of the callback.


    Enums

    Trace_ItemType enum
    Item type, used by the Trace_Item struct.

    Values:
    • TRACE_ITEM_TYPE_SPAN = 1:
    • TRACE_ITEM_TYPE_EVENT = 2:


    Structs

    Trace_SpanId struct
    An identifier for a span which can reasonably be expected to be unique across an entire deployment.


    Fields:
    • unsigned char data:
    Trace_Span struct
    Data for a span added to the event-tracer.


    Fields:
    • Trace_SpanId id:
    • uint32_t cause_count:
    • const Trace_SpanId* causes:
    Trace_Event struct
    Data for an event added to the event-tracer.


    Fields:
    • Trace_SpanId span_id:
    • uint64_t unix_timestamp_millis:
    • const char* message:
    • const char* type:
    • const Trace_EventData* data: Use the TraceEventData* methods to read the data.
    Trace_Item struct
    An item added to the event-tracer.


    Fields:
    • uint8_t item_type: The type of the item, defined using Trace_ItemType.
    • union Trace_Item::Trace_Item_Union item:
    Trace_Item_Union struct


    Fields:
    • Trace_Span span:
    • Trace_Event event:
    Trace_EventTracer_Parameters struct
    Parameters for configuring the event-tracer.


    Fields:
    • Trace_Callback* callback: The callback to invoke when a span or event is added to the event-tracer.
    • void* user_data: User data to provide to the callback above.


    Functions

    Trace_SpanId_Null function
    Trace_SpanId Trace_SpanId_Null(void)

    Returns a span ID representing a special null ID. This can be used to indicate that a span should not be actively traced.

    Returns:

  • Trace_SpanId:

    Parameters
    • void:
  • Trace_SpanId_GenerateTestSpanId function
    Trace_SpanId Trace_SpanId_GenerateTestSpanId(void)

    Returns a randomly generated span ID. This should only be used for testing purposes.

    Returns:

  • Trace_SpanId:

    Parameters
    • void:
  • Trace_SpanId_Equal function
    uint8_t Trace_SpanId_Equal(Trace_SpanId a, Trace_SpanId b)

    Returns whether the given span IDs are equal.

    Returns:

  • uint8_t:

    Parameters
    • Trace_SpanId:
    • Trace_SpanId:
  • Trace_SpanId_Hash function
    uint32_t Trace_SpanId_Hash(Trace_SpanId span_id)

    Returns a hash of the the given span ID.

    Returns:

  • uint32_t:

    Parameters
    • Trace_SpanId:
  • Trace_EventData_Create function
    Trace_EventData* Trace_EventData_Create()

    Creates an empty event data object. This should be populated with Trace_EventData_AddStringField before being added to the event-tracer.

    Returns:

  • Trace_EventData*:

  • Trace_EventData_Destroy function
    void Trace_EventData_Destroy(Trace_EventData* data)

    Frees resources for the event data object.

    Returns:

  • void:

    Parameters
    • Trace_EventData*:
  • Trace_EventData_AddStringFields function
    void Trace_EventData_AddStringFields(Trace_EventData* data, uint32_t count, const char* *keys, const char* *values)

    Adds the key value pair as a field to the given event data object. Note that this may invalidate any keys or values retrieved with Trace_EventData_Get*.

    Returns:

  • void:

    Parameters
    • Trace_EventData*:
    • uint32_t:
    • const char* *:
    • const char* *:
  • Trace_EventData_GetFieldCount function
    uint32_t Trace_EventData_GetFieldCount(const Trace_EventData* data)

    Returns the number of fields on the given event data object.

    Returns:

  • uint32_t:

    Parameters
    • const Trace_EventData*:
  • Trace_EventData_GetStringFields function
    void Trace_EventData_GetStringFields(const Trace_EventData* data, const char* *keys, const char* *values)

    Returns all the key value pairs in the event data object. keys and values must have capacity for at least Trace_EventData_GetFieldCount(data) elements. This method is provided to discover key value pairs of unknown event schema data, therefore the ordering of key value pairs is entirely arbitrary.

    Returns:

  • void:

    Parameters
    • const Trace_EventData*:
    • const char* *:
    • const char* *:
  • Trace_EventData_GetFieldValue function
    const char* Trace_EventData_GetFieldValue(const Trace_EventData* data, const char* key)

    Returns the value for the given key.

    Returns:

  • const char*:

    Parameters
    • const Trace_EventData*:
    • const char*:
  • Trace_EventTracer_Create function
    Trace_EventTracer* Trace_EventTracer_Create(const Trace_EventTracer_Parameters* parameters)

    Creates an event-tracer.

    The event-tracer is initially disabled, meaning you won't receive any trace items via the callback until you call Trace_EventTracer_Enable.

    Returns:

  • Trace_EventTracer*:

    Parameters
    • const Trace_EventTracer_Parameters*:
  • Trace_EventTracer_Destroy function
    void Trace_EventTracer_Destroy(Trace_EventTracer* event_tracer)

    Frees resources for an event-tracer.

    Returns:

  • void:

    Parameters
    • Trace_EventTracer*:
  • Trace_EventTracer_Enable function
    void Trace_EventTracer_Enable(Trace_EventTracer* event_tracer)

    Enables the event-tracer. When adding spans to the event-tracer, a non-null span ID will be returned and the provided Trace_Callback will be invoked. Note that the Trace_Callback will NOT be invoked for events added with a null span ID. If a span was added while the event-tracer was disabled, the Trace_Callback will NOT be invoked for any events added to the span (even if the event-tracer is enabled).

    Returns:

  • void:

    Parameters
    • Trace_EventTracer*:
  • Trace_EventTracer_Disable function
    void Trace_EventTracer_Disable(Trace_EventTracer* event_tracer)

    Disables the Trace_EventTracer. When adding spans to the event-tracer, a null span ID will be returned and the provided Trace_Callback will NOT be invoked. Note that the Trace_Callback will be invoked for events added with a non-null span ID. If a span was added while the event-tracer was enabled, the Trace_Callback will be invoked for any events added to the span (even if the event-tracer is disabled).

    Returns:

  • void:

    Parameters
    • Trace_EventTracer*:
  • Trace_EventTracer_SetActiveSpanId function
    void Trace_EventTracer_SetActiveSpanId(Trace_EventTracer* event_tracer, Trace_SpanId span_id)

    Sets the per thread active span ID for the Trace_EventTracer. This ID may be used internally by the Worker API. For example, subsequent calls to Worker_Connection_Send* will attach the set ID to the internal messages. Calling this function when there is already a non-null span ID active is safe and will overwrite the existing active span ID with the given ID. We recommend unsetting the active span ID when no longer needed to avoid creating causal relationships between unrelated spans.

    Returns:

  • void:

    Parameters
    • Trace_EventTracer*:
    • Trace_SpanId:
  • Trace_EventTracer_ClearActiveSpanId function
    void Trace_EventTracer_ClearActiveSpanId(Trace_EventTracer* event_tracer)

    Unsets the active span ID on the event-tracer for the current thread. Trace_EventTracer_GetActiveSpanId will return a null span ID.

    Returns:

  • void:

    Parameters
    • Trace_EventTracer*:
  • Trace_EventTracer_GetActiveSpanId function
    Trace_SpanId Trace_EventTracer_GetActiveSpanId(const Trace_EventTracer* event_tracer)

    Gets the active span ID on the event-tracer.

    Returns:

  • Trace_SpanId:

    Parameters
    • const Trace_EventTracer*:
  • Trace_EventTracer_AddSpan function
    Trace_SpanId Trace_EventTracer_AddSpan(Trace_EventTracer* event_tracer, const Trace_SpanId* causes, uint32_t cause_count)

    Adds a span to the event-tracer.

    Returns:

  • Trace_SpanId:

    Parameters
    • Trace_EventTracer*:
    • const Trace_SpanId*:
    • uint32_t:
  • Trace_EventTracer_AddEvent function
    void Trace_EventTracer_AddEvent(Trace_EventTracer* event_tracer, const Trace_Event* event)

    Adds an event to the event-tracer. Note that the unix_timestamp_millis field in the event will be ignored. Ownership of the event is NOT taken by the event-tracer, it is up to the user to free Trace_Event.

    Returns:

  • void:

    Parameters
    • Trace_EventTracer*:
    • const Trace_Event*:
  • Trace_EventTracer_ShouldSampleEvent function
    uint8_t Trace_EventTracer_ShouldSampleEvent(const Trace_EventTracer* event_tracer, const Trace_Event* event)

    Returns true if the given (partial) event object should be sampled. Currently, only the span_id field of the event is considered. This method is useful if generation of the event's message or data is expensive, e.g. if it involves allocation. Example usage:

    Trace_Event event{span_id, 0u, nullptr, "event_data_type", nullptr};
    if (Trace_EventTracer_ShouldSampleEvent(event_tracer, &event)) {
    event.message = "received component update";
    Trace_EventData event_data = Trace_EventData_Create();
    const char
    key = "update_data";
    const char* value = UpdateToString(update);
    Trace_EventData_AddStringFields(event_data, 1u, &key, &value);
    event.data = event_data;
    Trace_EventTracer_AddEvent(event_tracer, &event);
    Trace_EventData_Destroy(event_data);
    free(value);
    }


    Returns:

  • uint8_t:

    Parameters
    • const Trace_EventTracer*:
    • const Trace_Event*:
  • Trace_Item_Create function
    Trace_Item* Trace_Item_Create(Io_Storage* storage, const Trace_Item* item)

    Create a new trace item from the memory owned by this storage. The item will be valid as long as the storage's memory is valid i.e. until the storage is cleared or destroyed.

    The item is initialized by copying the provided item; pass a NULL item argument to create an item in an uninitialized state.

    Directly creating a Trace_Item object (on the stack or the heap) by other means than calling this method is discouraged as it will lead to undefined behaviour when passing that item to certain trace API methods (e.g. Trace_SerializeItemToStream).

    Returns:

  • Trace_Item*:

    Parameters
    • Io_Storage*:
    • const Trace_Item*:
  • Trace_Item_GetThreadLocal function
    Trace_Item* Trace_Item_GetThreadLocal(void)

    Returns a pointer to a thread-local trace item.

    The item is initially uninitialized, but successive calls to this method on the same thread always returns the same item, which may have been modified by previous usage.

    Returns:

  • Trace_Item*:

    Parameters
    • void:
  • Trace_GetSerializedItemSize function
    uint32_t Trace_GetSerializedItemSize(const Trace_Item* item)

    Get the serialized size of the trace item in bytes.

    Note that each call to Trace_GetSerializedItemSize invalidates the internal state necessary to serialize the previous item. Therefore, you must call Trace_SerializeItemToStream with one item before calling Trace_GetSerializedItemSize with the next item.

    Returns 0 on error. You can call Trace_GetLastError to get the associated error message, but it is safe to pass 0 as the size to a subsequent call to Trace_SerializeItemToStream.

    Returns:

  • uint32_t:

    Parameters
    • const Trace_Item*:
  • Trace_SerializeItemToStream function
    int8_t Trace_SerializeItemToStream(Io_Stream* stream, const Trace_Item* item, uint32_t size)

    Serialize the given trace item to a stream which has been opened for writing.

    The size argument must be the result of a call to Trace_GetSerializedItemSize with the same item. Otherwise, behaviour is undefined. It is not necessary to check that Trace_GetSerializedItemSize returned a non-zero item size. Instead, this can be indirectly checked by passing the size to this method and checking its return value for an error.

    The caller is responsible for ensuring that the provided stream has sufficient remaining capacity to hold the serialized item.

    Returns 1 on success, 0 on error. Call Trace_GetLastError to get the associated error message.

    Returns:

  • int8_t:

    Parameters
    • Io_Stream*:
    • const Trace_Item*:
    • uint32_t:
  • Trace_GetNextSerializedItemSize function
    uint32_t Trace_GetNextSerializedItemSize(Io_Stream* stream)

    Get the serialized size, in bytes, of the next serialized trace item to be read from the stream.

    Returns 0 either if there was an error or the stream did not contain enough data to calculate the next item's serialized size. You can call Trace_GetLastError to get the associated error message, but it is safe to pass 0 as the size to a subsequent call to Trace_DeserializeItemFromStream.

    Returns:

  • uint32_t:

    Parameters
    • Io_Stream*:
  • Trace_DeserializeItemFromStream function
    int8_t Trace_DeserializeItemFromStream(Io_Stream* stream, Trace_Item* item, uint32_t size)

    Deserialize the next trace item from a stream which has been opened for reading.

    If the deserialized item does not need to be used after the next call to Trace_DeserializeItemFromStream, it is recommended to pass the item returned by Trace_Item_GetThreadLocal to deserialize into. Otherwise, pass an item stored in an Io_Storage object.

    The size argument must be the result of a previous call to Trace_GetNextSerializedItemSize. Otherwise, behaviour is undefined. It is not necessary to check that Trace_GetNextSerializedItemSize returned a non-zero item size. Instead, this can be indirectly checked by passing the size to this method and checking its return value for an error.

    Returns 1 if the next serialized item was successfully deserialized into the provided item. Returns 0 if the stream only contained a partial (serialized) trace item. Writing the rest of the data of the next serialized trace item to the stream may result in the next call to Trace_DeserializeItemFromStream being successful. Returns -1 if there was an error during serialization. Call Trace_GetLastError to get the associated error message.

    Returns:

  • int8_t:

    Parameters
    • Io_Stream*:
    • Trace_Item*:
    • uint32_t:
  • Trace_GetLastError function
    const char* Trace_GetLastError(void)

    Returns the last error which occurred during a trace API method call. Returns nullptr if no such error has occurred.

    Returns:

  • const char*:

    Parameters
    • void:
  • Trace_ClearError function
    void Trace_ClearError(void)


    Returns:

  • void:

    Parameters
    • void:
  • c_worker.h


    Macros

    WORKER_API_VERSION_MAJOR macro
    999
    API version information. You can get the version information that was defined when the library was compiled by calling "Worker_ApiVersion()" or "Worker_ApiVersionStr()".

    WORKER_API_VERSION_MINOR macro
    9

    WORKER_API_VERSION_PATCH macro
    9

    WORKER_API_VERSION macro
    ((WORKER_API_VERSION_MAJOR << 16) | (WORKER_API_VERSION_MINOR << 8) | WORKER_API_VERSION_PATCH)

    WORKER_API_VERSION_STR macro
    "999.9.9"

    WORKER_SDK_C_INCLUDE_IMPROBABLE_C_COMMON_TRACE macro


    WORKER_DEFAULTS_SEND_QUEUE_CAPACITY macro
    4096
    Defaults.

    WORKER_DEFAULTS_RECEIVE_QUEUE_CAPACITY macro
    4096

    WORKER_DEFAULTS_LOG_MESSAGE_QUEUE_CAPACITY macro
    256

    WORKER_DEFAULTS_BUILT_IN_METRICS_REPORT_PERIOD_MILLIS macro
    5000

    WORKER_DEFAULTS_NETWORK_CONNECTION_TYPE macro
    WORKER_NETWORK_CONNECTION_TYPE_MODULAR_TCP

    WORKER_DEFAULTS_NETWORK_SECURITY_TYPE macro
    WORKER_NETWORK_SECURITY_TYPE_TLS

    WORKER_DEFAULTS_CONNECTION_TIMEOUT_MILLIS macro
    60000

    WORKER_DEFAULTS_DEFAULT_COMMAND_TIMEOUT_MILLIS macro
    5000

    WORKER_DEFAULTS_ERASURE_CODEC_ORIGINAL_PACKET_COUNT macro
    10

    WORKER_DEFAULTS_ERASURE_CODEC_RECOVERY_PACKET_COUNT macro
    2

    WORKER_DEFAULTS_ERASURE_CODEC_WINDOW_SIZE macro
    16

    WORKER_DEFAULTS_HEARTBEAT_INTERVAL_MILLIS macro
    10000

    WORKER_DEFAULTS_HEARTBEAT_TIMEOUT_MILLIS macro
    60000

    WORKER_DEFAULTS_FLOW_CONTROL_DOWNSTREAM_WINDOW_SIZE_BYTES macro
    262144

    WORKER_DEFAULTS_FLOW_CONTROL_UPSTREAM_WINDOW_SIZE_BYTES macro
    262144

    WORKER_DEFAULTS_MODULAR_TCP_MULTIPLEX_LEVEL macro
    1

    WORKER_DEFAULTS_TCP_MULTIPLEX_LEVEL macro
    32

    WORKER_DEFAULTS_TCP_SEND_BUFFER_SIZE macro
    65536

    WORKER_DEFAULTS_TCP_RECEIVE_BUFFER_SIZE macro
    65536

    WORKER_DEFAULTS_TCP_NO_DELAY macro
    false

    WORKER_DEFAULTS_TCP_FLUSH_DELAY_MILLIS macro
    1

    WORKER_DEFAULTS_RAKNET_HEARTBEAT_TIMEOUT_MILLIS macro
    60000

    WORKER_DEFAULTS_KCP_FAST_RETRANSMISSION macro
    1

    WORKER_DEFAULTS_KCP_EARLY_RETRANSMISSION macro
    1

    WORKER_DEFAULTS_KCP_NON_CONCESSIONAL_FLOW_CONTROL macro
    1

    WORKER_DEFAULTS_KCP_DISABLE_CONGESTION_CONTROL macro
    1

    WORKER_DEFAULTS_KCP_MULTIPLEX_LEVEL macro
    1

    WORKER_DEFAULTS_KCP_UPDATE_INTERVAL_MILLIS macro
    10

    WORKER_DEFAULTS_KCP_FLUSH_INTERVAL_MILLIS macro
    1

    WORKER_DEFAULTS_KCP_MIN_RTO_MILLIS macro
    10

    WORKER_DEFAULTS_KCP_SEND_WINDOW_SIZE macro
    500

    WORKER_DEFAULTS_KCP_RECV_WINDOW_SIZE macro
    1000

    WORKER_DEFAULTS_KCP_ENABLE_ERASURE_CODEC macro
    0

    WORKER_DEFAULTS_KCP_NETWORK_SECURITY_TYPE macro
    WORKER_NETWORK_SECURITY_TYPE_TLS

    WORKER_DEFAULTS_LOG_PREFIX macro
    "protocol-log-"

    WORKER_DEFAULTS_MAX_LOG_FILES macro
    10

    WORKER_DEFAULTS_MAX_LOG_FILE_SIZE_BYTES macro
    1024 * 1024

    WORKER_DEFAULTS_ENABLE_DYNAMIC_COMPONENTS macro
    0


    Type Definitions

    Schema_Bundle typedef
    typedef struct Schema_Bundle Schema_Bundle

    Schema_GenericData typedef
    typedef struct Schema_GenericData Schema_GenericData

    Schema_CommandRequest typedef
    typedef struct Schema_CommandRequest Schema_CommandRequest

    Schema_CommandResponse typedef
    typedef struct Schema_CommandResponse Schema_CommandResponse

    Schema_ComponentData typedef
    typedef struct Schema_ComponentData Schema_ComponentData

    Schema_ComponentUpdate typedef
    typedef struct Schema_ComponentUpdate Schema_ComponentUpdate

    Schema_JsonParameters typedef
    typedef struct Schema_JsonParameters Schema_JsonParameters

    Trace_EventTracer typedef
    typedef struct Trace_EventTracer Trace_EventTracer

    Worker_EntityId typedef
    typedef int64_t Worker_EntityId

    Worker_ComponentId typedef
    typedef uint32_t Worker_ComponentId

    Worker_CommandIndex typedef
    typedef uint32_t Worker_CommandIndex

    Worker_RequestId typedef
    typedef int64_t Worker_RequestId

    Worker_Connection typedef
    typedef struct Worker_Connection Worker_Connection

    Worker_ConnectionFuture typedef
    typedef struct Worker_ConnectionFuture Worker_ConnectionFuture

    Worker_DeploymentListFuture typedef
    typedef struct Worker_DeploymentListFuture Worker_DeploymentListFuture

    Worker_Alpha_PlayerIdentityTokenResponseFuture typedef
    typedef struct Worker_Alpha_PlayerIdentityTokenResponseFuture Worker_Alpha_PlayerIdentityTokenResponseFuture

    Worker_Alpha_LoginTokensResponseFuture typedef
    typedef struct Worker_Alpha_LoginTokensResponseFuture Worker_Alpha_LoginTokensResponseFuture

    Worker_Locator typedef
    typedef struct Worker_Locator Worker_Locator

    Worker_SnapshotInputStream typedef
    typedef struct Worker_SnapshotInputStream Worker_SnapshotInputStream

    Worker_SnapshotOutputStream typedef
    typedef struct Worker_SnapshotOutputStream Worker_SnapshotOutputStream

    Worker_CommandRequestHandle typedef
    typedef void Worker_CommandRequestHandle

    Worker_CommandResponseHandle typedef
    typedef void Worker_CommandResponseHandle

    Worker_ComponentDataHandle typedef
    typedef void Worker_ComponentDataHandle

    Worker_ComponentUpdateHandle typedef
    typedef void Worker_ComponentUpdateHandle

    Worker_CommandRequestFree typedef
    typedef void Worker_CommandRequestFree(Worker_ComponentId component_id, Worker_CommandIndex command_index, void *user_data, Worker_CommandRequestHandle *handle)

    Worker_CommandResponseFree typedef
    typedef void Worker_CommandResponseFree(Worker_ComponentId component_id, Worker_CommandIndex command_index, void *user_data, Worker_CommandResponseHandle *handle)

    Worker_ComponentDataFree typedef
    typedef void Worker_ComponentDataFree(Worker_ComponentId component_id, void *user_data, Worker_ComponentDataHandle *handle)

    Worker_ComponentUpdateFree typedef
    typedef void Worker_ComponentUpdateFree(Worker_ComponentId component_id, void *user_data, Worker_ComponentUpdateHandle *handle)

    Worker_CommandRequestCopy typedef
    typedef Worker_CommandRequestHandle* Worker_CommandRequestCopy(Worker_ComponentId component_id, Worker_CommandIndex command_index, void *user_data, Worker_CommandRequestHandle *handle)

    Worker_CommandResponseCopy typedef
    typedef Worker_CommandResponseHandle* Worker_CommandResponseCopy(Worker_ComponentId component_id, Worker_CommandIndex command_index, void *user_data, Worker_CommandResponseHandle *handle)

    Worker_ComponentDataCopy typedef
    typedef Worker_ComponentDataHandle* Worker_ComponentDataCopy(Worker_ComponentId component_id, void *user_data, Worker_ComponentDataHandle *handle)

    Worker_ComponentUpdateCopy typedef
    typedef Worker_ComponentUpdateHandle* Worker_ComponentUpdateCopy(Worker_ComponentId component_id, void *user_data, Worker_ComponentUpdateHandle *handle)

    Worker_CommandRequestDeserialize typedef
    typedef uint8_t Worker_CommandRequestDeserialize(Worker_ComponentId component_id, Worker_CommandIndex command_index, void *user_data, Schema_CommandRequest *source, Worker_CommandRequestHandle **handle_out)

    Worker_CommandResponseDeserialize typedef
    typedef uint8_t Worker_CommandResponseDeserialize(Worker_ComponentId component_id, Worker_CommandIndex command_index, void *user_data, Schema_CommandResponse *source, Worker_CommandResponseHandle **handle_out)

    Worker_ComponentDataDeserialize typedef
    typedef uint8_t Worker_ComponentDataDeserialize(Worker_ComponentId component_id, void *user_data, Schema_ComponentData *source, Worker_ComponentDataHandle **handle_out)

    Worker_ComponentUpdateDeserialize typedef
    typedef uint8_t Worker_ComponentUpdateDeserialize(Worker_ComponentId component_id, void *user_data, Schema_ComponentUpdate *source, Worker_ComponentUpdateHandle **handle_out)

    Worker_CommandRequestSerialize typedef
    typedef void Worker_CommandRequestSerialize(Worker_ComponentId component_id, Worker_CommandIndex command_index, void *user_data, Worker_CommandRequestHandle *handle, Schema_CommandRequest **target_out)

    Worker_CommandResponseSerialize typedef
    typedef void Worker_CommandResponseSerialize(Worker_ComponentId component_id, Worker_CommandIndex command_index, void *user_data, Worker_CommandResponseHandle *handle, Schema_CommandResponse **target_out)

    Worker_ComponentDataSerialize typedef
    typedef void Worker_ComponentDataSerialize(Worker_ComponentId component_id, void *user_data, Worker_ComponentDataHandle *handle, Schema_ComponentData **target_out)

    Worker_ComponentUpdateSerialize typedef
    typedef void Worker_ComponentUpdateSerialize(Worker_ComponentId component_id, void *user_data, Worker_ComponentUpdateHandle *handle, Schema_ComponentUpdate **target_out)

    Worker_LogFilterCallback typedef
    typedef uint8_t Worker_LogFilterCallback(void *user_data, uint32_t categories, Worker_LogLevel level)
    Custom callback for filtering log messages. Return true if a message with the given categories and level should be logged.

    Worker_LogCallback typedef
    typedef void Worker_LogCallback(void *user_data, const Worker_LogData *message)
    Custom callback for receiving log messages. Will be called for all log messages that pass through the filter.

    Worker_DeploymentListCallback typedef
    typedef void Worker_DeploymentListCallback(void *user_data, const Worker_DeploymentList *deployment_list)
    Locator callback typedef.

    Worker_QueueStatusCallback typedef
    typedef uint8_t Worker_QueueStatusCallback(void *user_data, const Worker_QueueStatus *queue_status)
    Locator callback typedef.

    Worker_Alpha_PlayerIdentityTokenResponseCallback typedef
    typedef void Worker_Alpha_PlayerIdentityTokenResponseCallback(void *user_data, const Worker_Alpha_PlayerIdentityTokenResponse *response)
    PIT-creation callback typedef.

    Worker_Alpha_LoginTokensResponseCallback typedef
    typedef void Worker_Alpha_LoginTokensResponseCallback(void *user_data, const Worker_Alpha_LoginTokensResponse *response)
    login token-creation callback typedef.

    Worker_GetWorkerFlagCallback typedef
    typedef void Worker_GetWorkerFlagCallback(void *user_data, const char *value)
    Worker flags callback typedef.

    Worker_AllocateFunction typedef
    typedef void* Worker_AllocateFunction(size_t size, void *state)

    Worker_DeallocateFunction typedef
    typedef void Worker_DeallocateFunction(void *pointer, size_t size, void *state)


    Enums

    Worker_LogLevel enum
    Enum defining the severities of log messages that can be sent to SpatialOS and received from the SDK.

    Values:
    • WORKER_LOG_LEVEL_DEBUG = 1:
    • WORKER_LOG_LEVEL_INFO = 2:
    • WORKER_LOG_LEVEL_WARN = 3:
    • WORKER_LOG_LEVEL_ERROR = 4:
    • WORKER_LOG_LEVEL_FATAL = 5:
    Worker_LogCategory enum
    Enum defining the available categories for log messages. Each log message has one or more of these categories attached.

    Values:
    • WORKER_LOG_CATEGORY_RECEIVE = 0x01:
    • WORKER_LOG_CATEGORY_SEND = 0x02:
    • WORKER_LOG_CATEGORY_NETWORK_STATUS = 0x04:
    • WORKER_LOG_CATEGORY_NETWORK_TRAFFIC = 0x08:
    • WORKER_LOG_CATEGORY_LOGIN = 0x10:
    • WORKER_LOG_CATEGORY_API = 0x20:
    • WORKER_LOG_CATEGORY_PARAMETERS = 0x40:
    • WORKER_LOG_CATEGORY_ALL = 0x7F:
    Worker_LogsinkType enum
    Enum defining the types of logsinks that can receive log messages from the the SDK.

    Values:
    • WORKER_LOGSINK_TYPE_ROTATING_FILE = 1: Log messages are logged into a set of rotating files with a specific maximum size.
    • WORKER_LOGSINK_TYPE_CALLBACK = 2: For each received log message a user callback is called.
    • WORKER_LOGSINK_TYPE_STDOUT = 3: Log messages are sent to stdout.
    • WORKER_LOGSINK_TYPE_STDOUT_ANSI = 4: Log messages are sent to stdout and are ANSI color coded.
    • WORKER_LOGSINK_TYPE_STDERR = 5: Log messages are sent to stderr.
    • WORKER_LOGSINK_TYPE_STDERR_ANSI = 6: Log messages are sent to stderr and are ANSI color coded.
    Worker_StatusCode enum
    Enum defining possible command status codes.

    Values:
    • WORKER_STATUS_CODE_SUCCESS = 1: The request was successfully executed and returned a response.
    • WORKER_STATUS_CODE_TIMEOUT = 2: The request timed out before a response was received. It can be retried, but carefully - this usually means the deployment is overloaded, so some sort of backoff should be used to avoid making the problem worse. This can also be caused by the target worker's handling code failing to respond to the command at all, perhaps due to a bug in its implementation.
    • WORKER_STATUS_CODE_NOT_FOUND = 3: The target entity did not exist, or did not have the target component. This probably means the entity either hasn't been created yet or has already been deleted. It might make sense to retry the request if there is reason to believe the entity hasn't yet been created but will be soon.
    • WORKER_STATUS_CODE_AUTHORITY_LOST = 4: The request could not be executed by a worker, either because the worker lost authority over the entity while handling the request, the entity was deleted while handling the request, or no worker was authoritative over the entity at all. Assuming the deployment isn't irrecoverably broken (e.g. due to misconfigured loadbalancing or crash-looping workers) this is a transient failure and can be retried immediately.
    • WORKER_STATUS_CODE_PERMISSION_DENIED = 5: The worker did not have the required permissions to make the request. Permissions do not change at runtime, so it doesn't make sense to retry the request.
    • WORKER_STATUS_CODE_APPLICATION_ERROR = 6: The command was delivered successfully, but the handler rejected it. Either the command was delivered to a worker that explicitly rejected it by calling Worker_Connection_SendCommandFailure, or the request data was rejected as invalid by SpatialOS itself. In the latter case, in particular, Worker_Connection_SendCreateEntityRequest will return kApplicationError if an entity ID reservation has expired, and Worker_Connection_SendEntityQueryResult will return kApplicationError if the result set is incomplete.
    • WORKER_STATUS_CODE_INTERNAL_ERROR = 7: Some other error occurred. This likely indicates a bug in SpatialOS and should be reported.
    Worker_ConnectionStatusCode enum
    Possible status codes for a remote call, connection attempt, or connection migration attempt.

    Values:
    • WORKER_CONNECTION_STATUS_CODE_SUCCESS = 1: The remote call was successful, or we are successfully connected.
    • WORKER_CONNECTION_STATUS_CODE_INTERNAL_ERROR = 2: Protocol violation, or some part of the system otherwise behaved in an unexpected way. Not expected to occur in normal operation.
    • WORKER_CONNECTION_STATUS_CODE_INVALID_ARGUMENT = 3: An argument provided by the caller was determined to be invalid. This is a local failure; no actual attempt was made to contact the host. Not retryable.
    • WORKER_CONNECTION_STATUS_CODE_NETWORK_ERROR = 4: Failed due to a networking issue or otherwise unreachable host.
    • WORKER_CONNECTION_STATUS_CODE_TIMEOUT = 5: A timeout provided by the caller or enforced by the system was exceeded. Can be retried.
    • WORKER_CONNECTION_STATUS_CODE_CANCELLED = 6: Attempt was cancelled by the caller. Currently shouldn't happen; reserved for future use.
    • WORKER_CONNECTION_STATUS_CODE_REJECTED = 7: Made contact with the host, but the request was explicitly rejected. Unlikely to be retryable. Possible causes include: the request was made to the wrong host; the host considered the request invalid for some other reason.
    • WORKER_CONNECTION_STATUS_CODE_PLAYER_IDENTITY_TOKEN_EXPIRED = 8: The player identity token provided by the caller has expired. Generate a new one and retry.
    • WORKER_CONNECTION_STATUS_CODE_LOGIN_TOKEN_EXPIRED = 9: The login token provided by the caller has expired. Generate a new one and retry.
    • WORKER_CONNECTION_STATUS_CODE_CAPACITY_EXCEEDED = 10: Failed because the deployment associated with the provided login token was at capacity. Retryable.
    • WORKER_CONNECTION_STATUS_CODE_RATE_EXCEEDED = 11: Failed due to rate-limiting of new connections to the deployment associated with the provided login token. Retryable.
    • WORKER_CONNECTION_STATUS_CODE_SERVER_SHUTDOWN = 12: After a successful connection attempt, the server later explicitly terminated the connection. Possible causes include: the deployment was stopped; the worker was killed due to unresponsiveness.
    Worker_Result enum
    Enum defining possible result codes for API methods. WORKER_RESULT_FAILURE is consistent with invalid Worker_RequestId -1.

    Values:
    • WORKER_RESULT_FAILURE = -1:
    • WORKER_RESULT_SUCCESS = 0:
    Worker_Authority enum
    Enum defining the possible authority states for an entity component.

    Values:
    • WORKER_AUTHORITY_NOT_AUTHORITATIVE = 0:
    • WORKER_AUTHORITY_AUTHORITATIVE = 1:
    • WORKER_AUTHORITY_AUTHORITY_LOSS_IMMINENT = 2: (deprecated)
    Worker_ComponentUpdateLoopback enum
    Enum defining the possible modes of loopback when updating a component.

    Values:
    • WORKER_COMPONENT_UPDATE_LOOPBACK_NONE = 0: The component update will not be returned in a subsequent call to Worker_GetOpList.
    • WORKER_COMPONENT_UPDATE_LOOPBACK_SHORT_CIRCUITED = 1: The component update will also be returned in a subsequent call to Worker_GetOpList.
    Worker_ConstraintType enum

    Values:
    • WORKER_CONSTRAINT_TYPE_ENTITY_ID = 1:
    • WORKER_CONSTRAINT_TYPE_COMPONENT = 2:
    • WORKER_CONSTRAINT_TYPE_SPHERE = 3:
    • WORKER_CONSTRAINT_TYPE_AND = 4:
    • WORKER_CONSTRAINT_TYPE_OR = 5:
    • WORKER_CONSTRAINT_TYPE_NOT = 6:
    Worker_ResultType enum

    Values:
    • WORKER_RESULT_TYPE_COUNT = 1:
    • WORKER_RESULT_TYPE_SNAPSHOT = 2:
    Worker_OpType enum
    Enum defining different possible op types.

    Values:
    • WORKER_OP_TYPE_DISCONNECT = 1:
    • WORKER_OP_TYPE_FLAG_UPDATE = 2:
    • WORKER_OP_TYPE_LOG_MESSAGE = 3:
    • WORKER_OP_TYPE_METRICS = 4:
    • WORKER_OP_TYPE_CRITICAL_SECTION = 5:
    • WORKER_OP_TYPE_ADD_ENTITY = 6:
    • WORKER_OP_TYPE_REMOVE_ENTITY = 7:
    • WORKER_OP_TYPE_RESERVE_ENTITY_IDS_RESPONSE = 8:
    • WORKER_OP_TYPE_CREATE_ENTITY_RESPONSE = 9:
    • WORKER_OP_TYPE_DELETE_ENTITY_RESPONSE = 10:
    • WORKER_OP_TYPE_ENTITY_QUERY_RESPONSE = 11:
    • WORKER_OP_TYPE_ADD_COMPONENT = 12:
    • WORKER_OP_TYPE_REMOVE_COMPONENT = 13:
    • WORKER_OP_TYPE_AUTHORITY_CHANGE = 14:
    • WORKER_OP_TYPE_COMPONENT_UPDATE = 15:
    • WORKER_OP_TYPE_COMMAND_REQUEST = 16:
    • WORKER_OP_TYPE_COMMAND_RESPONSE = 17:
    Worker_NetworkSecurityType enum
    Enum defining the possible network security types.

    Values:
    • WORKER_NETWORK_SECURITY_TYPE_INSECURE = 0: No encryption or security. Only safe for use in trusted environments.
    • WORKER_NETWORK_SECURITY_TYPE_TLS = 1: Uses DTLS or TLS as approriate for UDP-based and TCP-based connections respectively.
    • WORKER_NETWORK_SECURITY_TYPE_DTLS = WORKER_NETWORK_SECURITY_TYPE_TLS: An alias for WORKER_NETWORK_SECURITY_TYPE_TLS.
    Worker_NetworkConnectionType enum
    Network connection type used by Worker_NetworkParameters.

    Values:
    • WORKER_NETWORK_CONNECTION_TYPE_TCP = 0: (deprecated) Use this flag to connect over TCP.
    • WORKER_NETWORK_CONNECTION_TYPE_RAKNET = 1: (deprecated) Use this flag to connect over RakNet.
    • WORKER_NETWORK_CONNECTION_TYPE_KCP = 2: (deprecated) Use this flag to connect over KCP.
    • WORKER_NETWORK_CONNECTION_TYPE_MODULAR_KCP = 3: Use this flag to connect over the modular KCP stack. Modular KCP connections run on a new network stack with additional optional features such as compression.
    • WORKER_NETWORK_CONNECTION_TYPE_MODULAR_TCP = 4: Use this flag to connect over the modular TCP stack. Modular TCP connections run on a new network stack with additional optional features such as compression.
    Worker_LocatorCredentialsTypes enum
    Locator credentials type used by the Worker_LocatorParameters struct.

    Values:
    • WORKER_LOCATOR_LOGIN_TOKEN_CREDENTIALS = 1:
    • WORKER_LOCATOR_STEAM_CREDENTIALS = 2:
    • WORKER_LOCATOR_PLAYER_IDENTITY_CREDENTIALS = 3:
    Worker_SnapshotType enum
    Snapshot type, used by the Worker_SnapshotParameters struct.

    Values:
    • WORKER_SNAPSHOT_TYPE_BINARY = 0:
    • WORKER_SNAPSHOT_TYPE_JSON = 1:
    Worker_StreamState enum
    Enum to keep track of the state of streams.

    Values:
    • WORKER_STREAM_STATE_GOOD = 0: The last operation succeeded and the stream is in a good state.
    • WORKER_STREAM_STATE_BAD = 1: An internal stream error occurred and the stream is not in a usble state.
    • WORKER_STREAM_STATE_INVALID_DATA = 2: The data processed in the last operation was not valid and the operation failed. The stream is still in a usable state.
    • WORKER_STREAM_STATE_EOF = 3: The end of file has been reached.


    Structs

    Trace_SpanId struct
    An identifier for a span which can reasonably be expected to be unique across an entire deployment.


    Fields:
    • unsigned char data:
    Worker_LogMessage struct
    Parameters for sending a log message to SpatialOS.


    Fields:
    • uint8_t level: The severity of the log message; defined in the Worker_LogLevel enumeration.
    • const char* logger_name: The name of the logger.
    • const char* message: The full log message.
    • const Worker_EntityId* entity_id: The ID of the entity this message relates to, or NULL for none.
    Worker_GaugeMetric struct
    Parameters for a gauge metric.


    Fields:
    • const char* key:
    • double value:
    Worker_HistogramMetricBucket struct


    Fields:
    • double upper_bound:
    • uint32_t samples:
    Worker_HistogramMetric struct


    Fields:
    • const char* key:
    • double sum:
    • uint32_t bucket_count:
    • const Worker_HistogramMetricBucket* buckets:
    Worker_Metrics struct
    Parameters for sending metrics to SpatialOS.


    Fields:
    • const double* load: The load value of this worker. If NULL, do not report load.
    • uint32_t gauge_metric_count: The number of gauge metrics.
    • const Worker_GaugeMetric* gauge_metrics: Array of gauge metrics.
    • uint32_t histogram_metric_count: The number of histogram metrics.
    • const Worker_HistogramMetric* histogram_metrics: Array of histogram metrics.
    Worker_ComponentVtable struct


    Fields:
    • Worker_ComponentId component_id: Component ID that this vtable is for. If this is the default vtable, this field is ignored.
    • void* user_data: User data which will be passed directly to the callbacks supplied below.
    • Worker_CommandRequestFree* command_request_free: The function pointers below are only necessary in order to use the user_handle fields present in each of the Worker_CommandRequest, Worker_CommandResponse, Worker_ComponentData and Worker_ComponentUpdate types, for the given component ID (or for all components without an explicit vtable, if this is the default vtable), in order to offload serialization and deserialization work to internal SDK threads.

      For simplest usage of the SDK, all function pointers can be set to NULL, and only the schema_type field should be used in each type.

      In order to support usage of the user_handle field on instances of the corresponding type when used as input data to the SDK, X_serialize() must be provided.

      In order to support usage of the user_handle field on instances of the corresponding type when received as output data to the SDK, X_deserialize() must be provided.

      X_free() should free resources associated with the result of calling X_deserialize() or X_copy() (if provided).

      This decision can be made on a per-component, per-handle-type, and per-direction (input or output) basis. In the case of providing data to the SDK, the asynchronous serialization flow can be disabled even on a per-call basis by providing a non-NULL schema_type pointer instead of a user_handle pointer. The concrete types pointed to by the user_handle fields may differ between components or between handle types.

      All of the functions below, if provided, will be called from arbitrary internal SDK threads, and therefore must be thread-safe. A single user_handle pointer will not be passed to multiple callbacks concurrently, but a user_handle may be copied twice and the results of those copies may be used concurrently.

      For a concrete example, consider calling Worker_Connection_SendComponentUpdate() with short-circuiting enabled. The SDK will call component_update_copy() twice on the provided user_handle. One copy will be used for the outgoing flow, and will be serialized with component_update_serialize() and subsequently freed with component_update_free(). Concurrently, the other copy will be passed back to the user as part of a Worker_OpList and freed with component_update_free() when the OpList is deallocated (or, if its lifetime is extended with Worker_AcquireComponentUpdate(), when the last reference is released by the user with Worker_ReleaseComponentUpdate()).

      In general, the two most obvious strategies are: 1) reference-counting. Have X_copy() (atomically) increase a reference count and return the same pointer it was given, have X_free() (atomically) decrease the reference count and deallocate if zero. X_deserialize() should allocate a new object with reference count of 1, set the reference count of any new handle passed into the SDK to 1 initially and call X_free() manually afterwards. In this case, data owned by the user_handle should never be mutated after its first use. (This is the approach used internally for the schema_type.) 2) deep-copying. Have X_copy() allocate an entirely new deep copy of the object, and X_free() deallocate directly. In this case, user_handles can be mutated freely.
    • Worker_CommandRequestCopy* command_request_copy:
    • Worker_CommandRequestDeserialize* command_request_deserialize:
    • Worker_CommandRequestSerialize* command_request_serialize:
    • Worker_CommandResponseFree* command_response_free:
    • Worker_CommandResponseCopy* command_response_copy:
    • Worker_CommandResponseDeserialize* command_response_deserialize:
    • Worker_CommandResponseSerialize* command_response_serialize:
    • Worker_ComponentDataFree* component_data_free:
    • Worker_ComponentDataCopy* component_data_copy:
    • Worker_ComponentDataDeserialize* component_data_deserialize:
    • Worker_ComponentDataSerialize* component_data_serialize:
    • Worker_ComponentUpdateFree* component_update_free:
    • Worker_ComponentUpdateCopy* component_update_copy:
    • Worker_ComponentUpdateDeserialize* component_update_deserialize:
    • Worker_ComponentUpdateSerialize* component_update_serialize:
    Worker_CommandRequest struct
    An object used to represent a command request by either raw schema data or some user-defined handle type.


    Fields:
    • void* reserved:
    • Worker_ComponentId component_id:
    • Worker_CommandIndex command_index:
    • Schema_CommandRequest* schema_type:
    • Worker_CommandRequestHandle* user_handle:
    Worker_CommandResponse struct
    An object used to represent a command response by either raw schema data or some user-defined handle type.


    Fields:
    • void* reserved:
    • Worker_ComponentId component_id:
    • Worker_CommandIndex command_index:
    • Schema_CommandResponse* schema_type:
    • Worker_CommandResponseHandle* user_handle:
    Worker_ComponentData struct
    An object used to represent a component data snapshot by either raw schema data or some user-defined handle type.


    Fields:
    • void* reserved:
    • Worker_ComponentId component_id:
    • Schema_ComponentData* schema_type:
    • Worker_ComponentDataHandle* user_handle:
    Worker_ComponentUpdate struct
    An object used to represent a component update by either raw schema data or some user-defined handle type.


    Fields:
    • void* reserved:
    • Worker_ComponentId component_id:
    • Schema_ComponentUpdate* schema_type:
    • Worker_ComponentUpdateHandle* user_handle:
    Worker_Entity struct
    Represents an entity with an ID and a component data snapshot.


    Fields:
    • Worker_EntityId entity_id: The ID of the entity.
    • uint32_t component_count: Number of components for the entity.
    • const Worker_ComponentData* components: Array of initial component data for the entity.
    Worker_EntityIdConstraint struct


    Fields:
    • Worker_EntityId entity_id:
    Worker_ComponentConstraint struct


    Fields:
    • Worker_ComponentId component_id:
    Worker_SphereConstraint struct


    Fields:
    • double x:
    • double y:
    • double z:
    • double radius:
    Worker_AndConstraint struct


    Fields:
    • uint32_t constraint_count:
    • Worker_Constraint* constraints:
    Worker_OrConstraint struct


    Fields:
    • uint32_t constraint_count:
    • Worker_Constraint* constraints:
    Worker_NotConstraint struct


    Fields:
    • Worker_Constraint* constraint:
    Worker_Constraint_Union struct


    Fields:
    • Worker_EntityIdConstraint entity_id_constraint:
    • Worker_ComponentConstraint component_constraint:
    • Worker_SphereConstraint sphere_constraint:
    • Worker_AndConstraint and_constraint:
    • Worker_OrConstraint or_constraint:
    • Worker_NotConstraint not_constraint:
    Worker_Constraint struct
    A single query constraint.


    Fields:
    • uint8_t constraint_type: The type of constraint, defined using Worker_ConstraintType.
    • Worker_Constraint_Union constraint: Union with fields corresponding to each constraint type.
    Worker_EntityQuery struct
    An entity query.


    Fields:
    • Worker_Constraint constraint: The constraint for this query.
    • uint8_t result_type: Result type for this query, using Worker_ResultType.
    • uint32_t snapshot_result_type_component_id_count: Number of component IDs in the array for a snapshot result type.
    • const Worker_ComponentId* snapshot_result_type_component_ids: Pointer to component ID data for a snapshot result type. NULL means all component IDs.
    Worker_InterestOverride struct
    (Deprecated) An interest override for a particular (entity ID, component ID) pair.


    Fields:
    • uint32_t component_id: The ID of the component for which interest is being overridden.
    • uint8_t is_interested: Whether the worker is interested in this component.
    Worker_WorkerAttributes struct
    Worker attributes that are part of a worker's runtime configuration.


    Fields:
    • uint32_t attribute_count: Number of worker attributes.
    • const char** attributes: Will be NULL if there are no attributes associated with the worker.
    Worker_DisconnectOp struct
    Data for a disconnect message from the SDK.


    Fields:
    • uint8_t connection_status_code: A value from the Worker_ConnectionStatusCode enumeration.
    • const char* reason: A string giving detailed information on the reason for disconnecting.
    Worker_FlagUpdateOp struct
    Data for a FlagUpdate operation.


    Fields:
    • const char* name: The name of the updated worker flag.
    • const char* value: The new value of the updated worker flag. A null value indicates that the flag has been deleted.
    Worker_LogMessageOp struct
    Data for a log message from the SDK. Note: Worker_LogMessageOp has been deprecated and will be removed in a future version of SpatialOS.


    Fields:
    • uint8_t level: The severity of the log message; defined in the Worker_LogLevel enumeration.
    • const char* message: The message.
    Worker_MetricsOp struct
    Data for a set of built-in metrics reported by the SDK.


    Fields:
    • Worker_Metrics metrics:
    Worker_CriticalSectionOp struct
    Data for a critical section boundary (enter or leave) operation.


    Fields:
    • uint8_t in_critical_section: Whether the protocol is entering a critical section (true) or leaving it (false).
    Worker_AddEntityOp struct
    Data for an AddEntity operation.


    Fields:
    • Worker_EntityId entity_id: The ID of the entity that was added to the worker's view of the simulation.
    Worker_RemoveEntityOp struct
    Data for a RemoveEntity operation.


    Fields:
    • Worker_EntityId entity_id: The ID of the entity that was removed from the worker's view of the simulation.
    Worker_ReserveEntityIdsResponseOp struct
    Data for a ReserveEntityIdsResponse operation.


    Fields:
    • Worker_RequestId request_id: The ID of the reserve entity ID request for which there was a response.
    • uint8_t status_code: Status code of the response, using Worker_StatusCode.
    • const char* message: The error message.
    • Worker_EntityId first_entity_id: If successful, an ID which is the first in a contiguous range of newly allocated entity IDs which are guaranteed to be unused in the current deployment.
    • uint32_t number_of_entity_ids: If successful, the number of IDs reserved in the contiguous range, otherwise 0.
    Worker_CreateEntityResponseOp struct
    Data for a CreateEntity operation.


    Fields:
    • Worker_RequestId request_id: The ID of the request for which there was a response.
    • uint8_t status_code: Status code of the response, using Worker_StatusCode.
    • const char* message: The error message.
    • Worker_EntityId entity_id: If successful, the entity ID of the newly created entity.
    Worker_DeleteEntityResponseOp struct
    Data for a DeleteEntity operation.


    Fields:
    • Worker_RequestId request_id: The ID of the delete entity request for which there was a command response.
    • Worker_EntityId entity_id: The ID of the target entity of this request.
    • uint8_t status_code: Status code of the response, using Worker_StatusCode.
    • const char* message: The error message.
    Worker_EntityQueryResponseOp struct
    A response indicating the result of an entity query request.


    Fields:
    • Worker_RequestId request_id: The ID of the entity query request for which there was a response.
    • uint8_t status_code: Status code of the response, using Worker_StatusCode.
    • const char* message: The error message.
    • uint32_t result_count: Number of entities in the result set. Reused to indicate the result itself for CountResultType queries.
    • const Worker_Entity* results: Array of entities in the result set. Will be NULL if the query was a count query. Snapshot data in the result is deserialized with the corresponding vtable deserialize function and freed with the vtable free function when the OpList is destroyed.
    Worker_AddComponentOp struct
    Data for an AddComponent operation.


    Fields:
    • Worker_EntityId entity_id: The ID of the entity for which a component was added.
    • Worker_ComponentData data: The initial data for the new component. Deserialized with the corresponding vtable deserialize function and freed with the vtable free function when the OpList is destroyed.
    Worker_RemoveComponentOp struct
    Data for a RemoveComponent operation.


    Fields:
    • Worker_EntityId entity_id: The ID of the entity for which a component was removed.
    • Worker_ComponentId component_id: The ID of the component that was removed.
    Worker_AuthorityChangeOp struct
    Data for an AuthorityChange operation.


    Fields:
    • Worker_EntityId entity_id: The ID of the entity for which there was an authority change.
    • Worker_ComponentId component_id: The ID of the component over which the worker's authority has changed.
    • uint8_t authority: The authority state of the component, using the Worker_Authority enumeration.
    Worker_ComponentUpdateOp struct
    Data for a ComponentUpdate operation.


    Fields:
    • Worker_EntityId entity_id: The ID of the entity for which there was a component update.
    • Worker_ComponentUpdate update: The new component data for the updated entity. Deserialized with the corresponding vtable deserialize function and freed with the vtable free function when the OpList is destroyed.
    Worker_CommandRequestOp struct
    Data for a CommandRequest operation.


    Fields:
    • Worker_RequestId request_id: The incoming command request ID.
    • Worker_EntityId entity_id: The ID of the entity for which there was a command request.
    • uint32_t timeout_millis: Upper bound on request timeout provided by the platform.
    • const char* caller_worker_id: The ID of the worker that sent the request.
    • Worker_WorkerAttributes caller_attribute_set: The attributes of the worker that sent the request.
    • Worker_CommandRequest request: The command request data. Deserialized with the corresponding vtable deserialize function and freed with the vtable free function when the OpList is destroyed.
    Worker_CommandResponseOp struct
    Data for a CommandResponse operation.


    Fields:
    • Worker_RequestId request_id: The ID of the command request for which there was a command response.
    • Worker_EntityId entity_id: The ID of the entity originally targeted by the command request.
    • uint8_t status_code: Status code of the response, using Worker_StatusCode.
    • const char* message: The error message.
    • Worker_CommandResponse response: The command response data. Deserialized with the corresponding vtable deserialize function and freed with the vtable free function when the OpList is destroyed.
    Worker_Op_Union struct


    Fields:
    • Worker_DisconnectOp disconnect:
    • Worker_FlagUpdateOp flag_update:
    • Worker_LogMessageOp log_message:
    • Worker_MetricsOp metrics:
    • Worker_CriticalSectionOp critical_section:
    • Worker_AddEntityOp add_entity:
    • Worker_RemoveEntityOp remove_entity:
    • Worker_ReserveEntityIdsResponseOp reserve_entity_ids_response:
    • Worker_CreateEntityResponseOp create_entity_response:
    • Worker_DeleteEntityResponseOp delete_entity_response:
    • Worker_EntityQueryResponseOp entity_query_response:
    • Worker_AddComponentOp add_component:
    • Worker_RemoveComponentOp remove_component:
    • Worker_AuthorityChangeOp authority_change:
    • Worker_ComponentUpdateOp component_update:
    • Worker_CommandRequestOp command_request:
    • Worker_CommandResponseOp command_response:
    Worker_Op struct
    Data for a single op contained within an op list.


    Fields:
    • uint8_t op_type: The type of this op, defined in Worker_OpType.
    • Worker_Op_Union op:
    • Trace_SpanId span_id: The span ID of the op. You can use this, along with a Trace_EventTracer, to continue the op's trace.
    Worker_OpList struct
    An op list, usually returned by Worker_Connection_GetOpList.


    Fields:
    • Worker_Op* ops:
    • uint32_t op_count:
    Worker_RakNetNetworkParameters struct
    Parameters for configuring a RakNet connection. Used by Worker_NetworkParameters. DEPRECATED: The RakNet stack has been deprecated and will be removed in a future version of SpatialOS.


    Fields:
    • uint32_t heartbeat_timeout_millis: Time (in milliseconds) that RakNet should use for its heartbeat protocol.
    Worker_TcpNetworkParameters struct


    Fields:
    • uint8_t multiplex_level: The number of multiplexed TCP connections to use. Updates for entities are sharded across connections: the higher the multiplex level, the fewer entities might be impacted by a delayed update. Messages across connections cannot be packed into the same TCP packet, which may result in higher bandwidth usage. Increasing the number of multiplexed streams may also increase CPU usage.
    • uint32_t send_buffer_size: Size in bytes of the TCP send buffer.
    • uint32_t receive_buffer_size: Size in bytes of the TCP receive buffer.
    • uint8_t no_delay: Whether to enable TCP_NODELAY.
    Worker_ErasureCodecParameters struct
    Parameters to configure erasure coding, a forward error correction technique which increases bandwidth usage but may improve latency on unreliable networks.


    Fields:
    • uint8_t original_packet_count: Number of consecutive packets to send before sending redundant recovery packets.
    • uint8_t recovery_packet_count: Number of redundant recovery packets to send for each group of consecutive original packets. These packets are used to recover up to the same number of lost original packets.
    • uint8_t window_size: Number of batches that can be stored in memory, where a batch contains packets belonging to the same group of consecutive original packets and the corresponding recovery packets. Each batch contains up to OriginalPacketCount plus RecoveryPacketCount packets.
    Worker_FlowControlParameters struct
    Parameters to configure flow control. Used by Worker_ModularKcpNetworkParameters and Worker_ModularTcpNetworkParameters.


    Fields:
    • uint32_t downstream_window_size_bytes: The maximum number of bytes of serialized messages sent by SpatialOS which can be held in memory on the worker at any one time.
    • uint32_t upstream_window_size_bytes: The maximum number of bytes of serialized messages sent by the worker which can be held in memory on the bridge at any one time.
    Worker_HeartbeatParameters struct
    Parameters to configure internal heartbeating which can detect unresponsive peers. If an unresponsive peer is detected, a Worker_DisconnectOp will be enqueued in the op list.


    Fields:
    • uint64_t interval_millis: Minimum interval, in milliseconds, between which heartbeat messages are sent to the peer. A new heartbeat won't be sent before a response for the original heartbeat is received.
    • uint64_t timeout_millis: Time, in milliseconds, after which the peer will be deemed unresponsive.
    Worker_KcpNetworkParameters struct
    Parameters for configuring a KCP connection. Used by Worker_NetworkParameters. DEPRECATED: This KCP stack has been deprecated and will be removed in a future version of SpatialOS. To use KCP, use Worker_ModularKcpNetworkParameters instead.


    Fields:
    • uint8_t fast_retransmission: Whether to enable fast retransmission, which causes retransmission delays to increase more slowly when retransmitting timed-out packets multiple times.
    • uint8_t early_retransmission: Whether to enable early retransmission, which causes optimistic retransmission of earlier packets when acknowledgements are received for packets which were sent later, rather than waiting until the retransmission timeout has expired.
    • uint8_t non_concessional_flow_control: Whether to enable non-concessional flow control, which disables the usage of congestion windows (which are used to reduce packet loss across congested networks). Enabling non-concessional flow control can help optimize for low-latency delivery of small messages.
    • uint32_t multiplex_level: Number of multiplexed KCP streams. Updates for entities are sharded across streams: the higher the multiplex level, the fewer entities might be impacted by a delayed update. Messages across streams cannot be packed into the same UDP packet which may result in higher bandwidth usage. Increasing the number of multiplexed streams may also increase CPU usage.
    • uint32_t update_interval_millis: Interval, in milliseconds, between which the KCP transport layer sends and receives packets waiting in its send and receive buffers respectively.
    • uint32_t min_rto_millis: Hard limit on the minimum retransmission timeout. A packet will be resent if an acknowledgment has not been received from the peer within a time period known as the retransmission timeout. The retransmission timeout is calculated based on estimated round trip times to the remote peer, but it will never be set to a value lower than the minimum retransmission timeout. If you set this parameter to a value which is much higher than the average round trip time to a peer, it will likely result in packets not being resent as early as they could be, increasing latency for retransmitted packets. However, if you set this parameter to a value which is lower than the average round trip time (or ping), packets will be retransmitted even if they are not lost, which will cause unnecessary bandwidth overhead until round trip times are calculated. For more information on retransmission timeouts and their calculation, see https://tools.ietf.org/html/rfc6298. Note, however, that the RFC pertains to TCP, and therefore it focuses on avoiding unnecessary retransmissions rather than optimizing for latency. Set to zero to use default, which is lower when Worker_KcpNetworkParameters::fast_retransmission is enabled.
    • uint32_t send_window_size: KCP flow control window size for sending, in number of KCP packets. This window is applied to sending across all streams i.e. sending a message will block if it would cause the total number of un-acked outgoing packets to exceed the send window size.
    • uint32_t recv_window_size: KCP flow control window for receiving, in number of KCP packets. The upper bound on the memory used by receive buffers is proportional to the multiplex level multiplied by the receive window size.
    • uint8_t enable_erasure_codec: Whether to enable the erasure codec.
    • Worker_ErasureCodecParameters erasure_codec: Erasure codec parameters.
    • Worker_HeartbeatParameters heartbeat: Heartbeat parameters.
    • uint8_t security_type: Type of encryption layer security to use, defined in Worker_NetworkSecurityType.
    Worker_KcpTransportParameters struct
    Parameters for configuring the KCP transport layer within the modular KCP network stack. Used by Worker_ModularKcpNetworkParameters.


    Fields:
    • uint32_t flush_interval_millis: The maximum interval, in milliseconds, between which the KCP transport layer flushes packets waiting in its cross-stream send buffer to the network. The transport layer may send earlier if there are enough packets to fill the MTU or if there has been a call to flush the network.
    • uint8_t fast_retransmission: Whether to enable fast retransmission, which causes retransmission delays to increase more slowly when retransmitting timed-out packets multiple times.
    • uint8_t early_retransmission: Whether to enable early retransmission, which causes optimistic retransmission of earlier packets when acknowledgements are received for packets which were sent later, rather than waiting until the retransmission timeout has expired.
    • uint8_t disable_congestion_control: Whether to disable congestion control which disables the usage of congestion windows (which are used to reduce packet loss across congested networks). Disabling congestion control can optimize for low-latency delivery of small messages.
    • uint32_t min_rto_millis: Hard limit on the minimum retransmission timeout. A packet will be resent if an acknowledgment has not been received from the peer within a time period known as the retransmission timeout. The retransmission timeout is calculated based on estimated round trip times to the remote peer, but it will never be set to a value lower than the minimum retransmission timeout. If you set this parameter to a value which is much higher than the average round trip time to a peer, it will likely result in packets not being resent as early as they could be, increasing latency for retransmitted packets. However, if you set this parameter to a value which is lower than the average round trip time (or ping), packets will be retransmitted even if they are not lost, which will cause unnecessary bandwidth overhead until round trip times are calculated. For more information on retransmission timeouts and their calculation, see https://tools.ietf.org/html/rfc6298. Note, however, that the RFC pertains to TCP, and therefore it focuses on avoiding unnecessary retransmissions rather than optimizing for latency. Set to zero to use default, which is lower when Worker_KcpTransportParameters::fast_retransmission is enabled.
    Worker_TcpTransportParameters struct
    Parameters for configuring the TCP transport layer within the modular TCP network stack. Used by Worker_ModularTcpNetworkParameters.


    Fields:
    • uint32_t flush_delay_millis: Maximum delay after which to flush data to the network. If non-zero, data may be delayed for up to this many milliseconds in order to pack more data into network packets and save bandwidth. If set to zero, data will always be sent immediately without delay. This will prevent manual flushes from having any effect, and may render compression ineffective.
    Worker_CompressionParameters struct
    Parameters for configuring compression. Used by Worker_ModularKcpNetworkParameters and Worker_ModularTcpNetworkParameters. Currently, there are no configurable settings; if this struct is not NULL compression is enabled.


    Fields:
    • char place_holder: A placeholder field. This is ignored.
    Worker_ModularKcpNetworkParameters struct
    Parameters for configuring the stack for a modular KCP connection. Used by Worker_NetworkParameters.


    Fields:
    • uint8_t security_type: Type of encryption layer security to use, defined in Worker_NetworkSecurityType.
    • uint8_t multiplex_level: Number of multiplexed KCP streams. Updates for entities are sharded across streams: the higher the multiplex level, the fewer entities might be impacted by a delayed update. Increasing the number of multiplexed streams may increase CPU usage.
    • Worker_KcpTransportParameters downstream_kcp: KCP parameters for messages sent from the bridge to the worker.
    • Worker_KcpTransportParameters upstream_kcp: KCP parameters for messages sent from the worker to the bridge.
    • const Worker_ErasureCodecParameters* downstream_erasure_codec: Erasure codec parameters for messages sent from the bridge to the worker.
    • const Worker_ErasureCodecParameters* upstream_erasure_codec: Erasure codec parameters for messages sent from the worker to the bridge.
    • const Worker_HeartbeatParameters* downstream_heartbeat: Heartbeat parameters for heartbeats from the bridge to the worker.
    • const Worker_HeartbeatParameters* upstream_heartbeat: Heartbeat parameters for heartbeats from the worker to the bridge.
    • const Worker_CompressionParameters* downstream_compression: Compression parameters for messages sent from the bridge to the worker.
    • const Worker_CompressionParameters* upstream_compression: Compression parameters for messages sent from the worker to the bridge.
    • const Worker_FlowControlParameters* flow_control: Flow control parameters.
    Worker_ModularTcpNetworkParameters struct
    Parameters for configuring the stack for a modular TCP connection. Used by Worker_NetworkParameters.


    Fields:
    • uint8_t security_type: Type of encryption layer security to use, defined in Worker_NetworkSecurityType.
    • uint8_t multiplex_level: The number of multiplexed TCP connections to use. Updates for entities are sharded across connections: the higher the multiplex level, the fewer entities might be impacted by a delayed update. Messages across connections cannot be packed into the same TCP packet, which may result in higher bandwidth usage. Increasing the number of multiplexed streams may also increase CPU usage.
    • Worker_TcpTransportParameters downstream_tcp: TCP parameters for messages sent from the bridge to the worker.
    • Worker_TcpTransportParameters upstream_tcp: TCP parameters for messages sent from the worker to the bridge.
    • const Worker_HeartbeatParameters* downstream_heartbeat: Heartbeat parameters for heartbeats from the bridge to the worker.
    • const Worker_HeartbeatParameters* upstream_heartbeat: Heartbeat parameters for heartbeats from the worker to the bridge.
    • const Worker_CompressionParameters* downstream_compression: Compression parameters for messages sent from the bridge to the worker.
    • const Worker_CompressionParameters* upstream_compression: Compression parameters for messages sent from the worker to the bridge.
    • const Worker_FlowControlParameters* flow_control: Flow control parameters.
    Worker_NetworkParameters struct
    Parameters for configuring the network connection.


    Fields:
    • uint8_t use_external_ip: Set this flag to non-zero to connect to SpatialOS using the externally-visible IP address. This flag must be set when connecting externally (i.e. from outside the cloud) to a cloud deployment.
    • uint8_t connection_type: Type of network connection to use when connecting to SpatialOS, defined in Worker_NetworkConnectionType.
    • Worker_RakNetNetworkParameters raknet: (deprecated) Parameters used if the WORKER_NETWORK_CONNECTION_TYPE_RAKNET flag is set.
    • Worker_TcpNetworkParameters tcp: (deprecated) Parameters used if the WORKER_NETWORK_CONNECTION_TYPE_TCP flag is set.
    • Worker_KcpNetworkParameters kcp: (deprecated) Parameters used if the WORKER_NETWORK_CONNECTION_TYPE_KCP flag is set.
    • Worker_ModularKcpNetworkParameters modular_kcp: Parameters used if the WORKER_NETWORK_CONNECTION_TYPE_MODULAR_KCP flag is set.
    • Worker_ModularTcpNetworkParameters modular_tcp: Parameters used if the WORKER_NETWORK_CONNECTION_TYPE_MODULAR_TCP flag is set.
    • uint64_t connection_timeout_millis: Timeout for the connection to SpatialOS to be established.
    • uint32_t default_command_timeout_millis: Default timeout for worker commands if one is not specified when command is sent.
    Worker_ProtocolLoggingParameters struct
    (Deprecated) Tuning parameters for configuring protocol logging in the SDK. Used by Worker_ConnectionParameters.


    Fields:
    • const char* log_prefix: Log file names are prefixed with this prefix, are numbered, and have the extension .log.
    • uint32_t max_log_files: Maximum number of log files to keep. Note that logs from any previous protocol logging sessions will be overwritten. Forced to 1 if max_log_file_size_bytes == 0.
    • uint32_t max_log_file_size_bytes: When a log file reaches this size, a new log file is created. If set to 0, only one file will be created without size restrictions.
    Worker_RotatingLogFileParameters struct
    Parameters for configuring the rotating log files used for a logsink.


    Fields:
    • const char* log_prefix: Log file names are prefixed with this prefix, are numbered, and have the extension .log.
    • uint32_t max_log_files: Maximum number of log files to keep. Note that logs from any previous protocol logging sessions are overwritten. Forced to 1 if max_log_file_size_bytes == 0.
    • uint32_t max_log_file_size_bytes: When a log file reaches this size, a new log file is created. If set to 0, only one file will be created without size restrictions.
    Worker_LogFilterParameters struct
    Parameters for configuring a custom filter predicate


    Fields:
    • uint32_t categories: Combination of Worker_LogCategory flags defining the messages that should be received. If a message has at least one of these flags, it is logged to the sink.
    • uint8_t level: All messages of log level >= level are received; defined in Worker_LogLevel enumeration
    • Worker_LogFilterCallback* callback: If set, all log messages are sent through this filter function and ignore the categories and level members above. Note that this callback will be called concurrently from different threads. You need to synchronize access to data that is shared with the thread this callback was set on.
    • void* user_data: Pointer to user-defined data that is passed to each callback invocation
    Worker_LogData struct
    Represents a log message to be consumed by a user-defined callback.


    Fields:
    • const char* timestamp: Date & time when this message was generated.
    • uint32_t categories: The log categories that this message was generated with.
    • uint8_t log_level: The log level of this message.
    • const char* content: The message content.
    Worker_LogCallbackParameters struct
    Parameters for configuring a log callback


    Fields:
    • Worker_LogCallback* log_callback: Pointer to callback function that receives new log messages
    • void* user_data: Pointer to user-defined data that will be passed to each callback invocation
    Worker_LogsinkParameters struct
    Parameters for configuring a logsink in the SDK.


    Fields:
    • uint8_t logsink_type: The type of logsink to use. Depending on this value, a subset of other members is used. Defined in Worker_LogsinkType enumeration.
    • Worker_LogFilterParameters filter_parameters: Parameters for controlling filtering of log messages.
    • Worker_RotatingLogFileParameters rotating_logfile_parameters: Parameters for a rotating log file sink. Only used if logsink_type == WORKER_LOGSINK_TYPE_ROTATING_FILE.
    • Worker_LogCallbackParameters log_callback_parameters: Parameters for custom log callback. Only used if logsink_type == WORKER_LOGSINK_TYPE_CALLBACK. Note that this callback will be called from different threads. You need to synchronize access to data that is shared with the thread this callback was set on. However, the logger guarantees that only a single log callback is run at a time per connection which can sometimes eliminate the need for synchronization.
    Worker_ThreadAffinityParameters struct
    Parameters for configuring thread affinity. Affinity masks are bit masks where having 1 in the nth least significant position means the thread will be permitted to run on the nth core. If an affinity mask is set to zero, the group of threads using that mask will have no thread affinity. Used by Worker_ConnectionParameters.


    Fields:
    • uint64_t receive_threads_affinity_mask: Affinity mask for threads related to receiving network ops.
    • uint64_t send_threads_affinity_mask: Affinity mask for threads related to sending network ops.
    • uint64_t temporary_threads_affinity_mask: Affinity mask for short-lived threads.
    Worker_ConnectionParameters struct
    Parameters for creating a Worker_Connection and connecting to SpatialOS.


    Fields:
    • const char* worker_type: Worker type (platform).
    • Worker_NetworkParameters network: Network parameters.
    • uint32_t send_queue_capacity: Number of messages that can be stored on the send queue. When the send queue is full, calls to Worker_Connection_Send functions can block.
    • uint32_t receive_queue_capacity: Number of messages that can be stored on the receive queue. When the receive queue is full, SpatialOS can apply QoS and drop messages to the worker.
    • uint32_t log_message_queue_capacity: Number of messages logged by the SDK that can be stored in the log message queue. When the log message queue is full, messages logged by the SDK can be dropped.
    • uint32_t built_in_metrics_report_period_millis: The Connection tracks several internal metrics, such as send and receive queue statistics. This parameter controls how frequently the Connection will return a MetricsOp reporting its built-in metrics. If set to zero, this functionality is disabled.
    • Worker_ProtocolLoggingParameters protocol_logging: (Deprecated) Parameters for configuring legacy protocol logging parameters.
    • uint8_t enable_protocol_logging_at_startup: (Deprecated) Whether to enable legacy protocol logging at startup.
    • uint32_t logsink_count: Number of logsinks configured.
    • const Worker_LogsinkParameters* logsinks: Array of logsinks that receive filtered log messages from the SDK.
    • uint8_t enable_logging_at_startup: Whether to enable all logsinks at startup. Note that this is automatically true if enable_protocol_logging_at_startup is set to true.
    • const Trace_EventTracer* event_tracer: The event tracer to use for the Worker_Connection. The Trace_EventTracer must outlive the Worker_Connection. Only used if not NULL.
    • uint8_t enable_dynamic_components: Whether to enable dynamic components. If this field is true, add and remove component ops are emitted on authority change. These ops, like all add and remove component ops, must be treated in an idempotent way (i.e. they replace any existing value on the worker for the component).
    • Worker_ThreadAffinityParameters thread_affinity: Parameters for configuring thread affinity.
    • uint32_t component_vtable_count: Number of component vtables.
    • const Worker_ComponentVtable* component_vtables: Component vtable for each component that the connection will deal with.
    • const Worker_ComponentVtable* default_component_vtable: Default vtable used when a component is not registered. Only used if not NULL.
    Worker_LoginTokenCredentials struct
    Parameters for authenticating using a SpatialOS login token.


    Fields:
    • const char* token: The token would typically be provided on the command-line by the SpatialOS launcher.
    Worker_SteamCredentials struct
    Parameters for authenticating using Steam credentials.


    Fields:
    • const char* ticket: Steam ticket for the steam app ID and publisher key corresponding to the project name specified in the Worker_LocatorParameters. Typically obtained from the steam APIs.
    • const char* deploymenttag: Deployment tag to request access for. If non-empty, must match the following regex: [A-Za-z0-9][A-Za-z0-9]*
    Worker_PlayerIdentityCredentials struct
    Parameters for authenticating using a Player Identity Token and Login Token.


    Fields:
    • const char* login_token: Authenticates a user to a single deployment. Obtained from a game authentication server using a PIT.
    • const char* player_identity_token: Uniquely identifies a user across deployments, and is provided by a game authentication server.
    Worker_LocatorParameters struct
    Parameters for authenticating and logging in to a SpatialOS deployment.


    Fields:
    • const char* project_name: The name of the SpatialOS project.
    • uint8_t credentials_type: Type of credentials to use when authenticating via the Locator, defined in Worker_LocatorCredentialsTypes
    • Worker_LoginTokenCredentials login_token: Parameters used if the WORKER_LOGIN_TOKEN_CREDENTIALS flag is set.
    • Worker_SteamCredentials steam: Parameters used if the WORKER_STEAM_CREDENTIALS flag is set.
    • Worker_PlayerIdentityCredentials player_identity: The player identity token/login token pair used for authentication.
    • uint8_t use_insecure_connection: Whether to use an insecure (non-TLS) connection for local development.
    • Worker_ProtocolLoggingParameters logging: (Deprecated) Parameters for configuring legacy protocol logging.
    • uint8_t enable_logging: (Deprecated) Whether to enable legacy protocol logging for the Locator flow.
    • uint32_t logsink_count: Number of logsinks configured.
    • const Worker_LogsinkParameters* logsinks: Array of logsinks that receive filtered log messages from the SDK. These are enabled by default.
    Worker_Deployment struct
    Details of a specific deployment obtained via Worker_Locator_GetDeploymentListAsync.


    Fields:
    • const char* deployment_name: Name of the deployment.
    • const char* assembly_name: The name of the assembly used by this deployment.
    • const char* description: Description of the deployment.
    • uint32_t users_connected: Number of users currently connected to the deployment.
    • uint32_t users_capacity: Total user capacity of the deployment.
    Worker_DeploymentList struct
    A deployment list obtained via Worker_Locator_GetDeploymentListAsync.


    Fields:
    • uint32_t deployment_count: Number of deployments.
    • Worker_Deployment* deployments: Array of deployments.
    • const char* error: Will be non-NULL if an error occurred.
    Worker_QueueStatus struct
    A queue status update when connecting to a deployment via Worker_Locator_ConnectAsync.


    Fields:
    • uint32_t position_in_queue: Position in the queue. Decreases as we advance to the front of the queue.
    • const char* error: Will be non-NULL if an error occurred.
    Worker_UpdateParameters struct
    Component update parameters. Used to modify the behaviour of a component update request.


    Fields:
    • uint8_t loopback: Controls how the update is sent back to the worker from which it was sent. Defined in the Worker_ComponentUpdateLoopback enumeration.
    Worker_CommandParameters struct
    Command parameters. Used to modify the behaviour of a command request.


    Fields:
    • uint8_t allow_short_circuit: Allow command requests to bypass the bridge when this worker is authoritative over the target entity-component.
    Worker_ConnectionStatus struct
    Information about status of a network request.


    Fields:
    • uint8_t code: The status of the request. This value is a member of the enum Worker_ConnectionStatusCode.
    • const char* detail: Detailed, human readable description of the connection status. Will be "OK" if no error occurred.
    Worker_Alpha_PlayerIdentityTokenRequest struct
    The parameters used when creating a player identity token.


    Fields:
    • const char* development_authentication_token: The development authentication token used for exchanging the player identity token.
    • const char* player_id: The ID of the player we are generating a PIT for.
    • const uint32_t* duration_seconds: The lifetime duration of the requested PIT. This is an optional field. If the pointer is null, a default value of 24 hours will be used.
    • const char* display_name: The player's display name. This is an optional field.
    • const char* metadata: Additional metadata that can be stored in the PIT. This is an optional field. You can use this to securely attach extra attributes in a format you choose (e.g. JSON payload).
    • uint8_t use_insecure_connection: Whether to use an insecure (non-TLS) connection for local development. An insecure connection must be used when connecting to a local development authentication service. A secure connection must be used when connecting to a cloud development authentication service.
    Worker_Alpha_PlayerIdentityTokenResponse struct
    The result of creating a player identity token.


    Fields:
    • const char* player_identity_token: The returned player identity token.
    • Worker_ConnectionStatus status: The status code and a human readable description of the status of the request.
    Worker_Alpha_LoginTokensRequest struct
    The parameters used when creating a login token.


    Fields:
    • const char* player_identity_token: The player identity token of the player
    • const char* worker_type: The worker type for which the requested LTs are scoped for.
    • const uint32_t* duration_seconds: The lifetime duration of the requested LTs. This is an optional field. If the pointer is null, a default value of 15 minutes will be used.
    • uint8_t use_insecure_connection: Whether to use an insecure (non-TLS) connection for local development. An insecure connection must be used when connecting to a local development login service. A secure connection must be used when connecting to a cloud development login service.
    Worker_Alpha_LoginTokenDetails struct
    A single login token with additional details.


    Fields:
    • const char* deployment_id: The UUID of the deployment.
    • const char* deployment_name: The name of the deployment
    • uint32_t tag_count: The number of tags that the deployment contains.
    • const char** tags: The tags that the deployment contains.
    • const char* login_token: The generated login token for this deployment.
    Worker_Alpha_LoginTokensResponse struct
    A login token list obtained via Worker_Alpha_CreateDevelopmentLoginTokens


    Fields:
    • uint32_t login_token_count: Number of login tokens.
    • Worker_Alpha_LoginTokenDetails* login_tokens: Array of login tokens.
    • Worker_ConnectionStatus status: The status code and a human readable description of the status of the request.
    Worker_SnapshotParameters struct
    Parameters for interacting with a snapshot.


    Fields:
    • uint8_t snapshot_type: Snapshot type, defined in Worker_SnapshotType
    • uint32_t component_vtable_count: Number of component vtables.
    • const Worker_ComponentVtable* component_vtables: Component vtable for each component that the connection will deal with.
    • const Worker_ComponentVtable* default_component_vtable: Default vtable used when a component is not registered. Only used if not NULL.
    • const Schema_Bundle* schema_bundle: Schema bundle. Used only if the snapshot type is a JSON snapshot.
    • const Schema_JsonParameters* json_parameters: JSON parameters. By default, if json_parameters is not specified, then SnapshotOutputStream will default to writing JSON in compact form. Used only if the snapshot type is a JSON snapshot.
    Worker_SnapshotState struct
    Struct to keep track of the state of snapshot streams.


    Fields:
    • uint8_t stream_state: Stream state.
    • const char* error_message: Error message. NULL if not set.


    Functions

    Worker_AcquireCommandRequest function
    Worker_CommandRequest* Worker_AcquireCommandRequest(const Worker_CommandRequest* request)

    Acquire a reference to extend the lifetime of a command request managed by the SDK, by returning a new command request container object not managed by the SDK. The data contained within the object will be identical to the original data, but it is not safe to mutate the contained data without explicitly copying it first. The lifetime of the original container object is unchanged.

    Returns:

  • Worker_CommandRequest*:

    Parameters
    • const Worker_CommandRequest*:
  • Worker_AcquireCommandResponse function
    Worker_CommandResponse* Worker_AcquireCommandResponse(const Worker_CommandResponse* response)

    Acquire a reference to extend the lifetime of a command response managed by the SDK, by returning a new command response container object not managed by the SDK. The data contained within the object will be identical to the original data, but it is not safe to mutate the contained data without explicitly copying it first. The lifetime of the original container object is unchanged.

    Returns:

  • Worker_CommandResponse*:

    Parameters
    • const Worker_CommandResponse*:
  • Worker_AcquireComponentData function
    Worker_ComponentData* Worker_AcquireComponentData(const Worker_ComponentData* data)

    Acquire a reference to extend the lifetime of some component data managed by the SDK, by returning a new component data container object not managed by the SDK. The data contained within the object will be identical to the original data, but it is not safe to mutate the contained data without explicitly copying it first. The lifetime of the original container object is unchanged.

    Returns:

  • Worker_ComponentData*:

    Parameters
    • const Worker_ComponentData*:
  • Worker_AcquireComponentUpdate function
    Worker_ComponentUpdate* Worker_AcquireComponentUpdate(const Worker_ComponentUpdate* update)

    Acquire a reference to extend the lifetime of a component update managed by the SDK, by returning a new component update container object not managed by the SDK. The data contained within the object will be identical to the original data, but it is not safe to mutate the contained data without explicitly copying it first. The lifetime of the original container object is unchanged.

    Returns:

  • Worker_ComponentUpdate*:

    Parameters
    • const Worker_ComponentUpdate*:
  • Worker_ReleaseCommandRequest function
    void Worker_ReleaseCommandRequest(Worker_CommandRequest* request)

    Release a reference obtained by Worker_AcquireCommandRequest.

    Returns:

  • void:

    Parameters
    • Worker_CommandRequest*:
  • Worker_ReleaseCommandResponse function
    void Worker_ReleaseCommandResponse(Worker_CommandResponse* response)

    Release a reference obtained by Worker_AcquireCommandResponse.

    Returns:

  • void:

    Parameters
    • Worker_CommandResponse*:
  • Worker_ReleaseComponentData function
    void Worker_ReleaseComponentData(Worker_ComponentData* data)

    Release a reference obtained by Worker_AcquireComponentData.

    Returns:

  • void:

    Parameters
    • Worker_ComponentData*:
  • Worker_ReleaseComponentUpdate function
    void Worker_ReleaseComponentUpdate(Worker_ComponentUpdate* update)

    Release a reference obtained by Worker_AcquireComponentUpdate.

    Returns:

  • void:

    Parameters
    • Worker_ComponentUpdate*:
  • Worker_ApiVersion function
    uint32_t Worker_ApiVersion(void)

    Returns the WORKER_API_VERSION number that was defined when the library was compiled.

    Returns:

  • uint32_t:

    Parameters
    • void:
  • Worker_ApiVersionStr function
    const char* Worker_ApiVersionStr(void)

    Returns the WORKER_API_VERSION string that was defined when the library was compiled.

    Returns:

  • const char*:

    Parameters
    • void:
  • Worker_Alpha_SetAllocator function
    void Worker_Alpha_SetAllocator(Worker_AllocateFunction* allocate, Worker_DeallocateFunction* deallocate, void* state)

    Set custom allocation functions and state for managing memory within the API. The allocation function should allocate a block of memory of the size that is given by the argument and return a pointer to the first byte. The pointer must be suitably aligned to hold an object of any fundamental alignment and will be released by a matching call to the deallocation function with the same size. If either allocation or deallocation function throws, the application will terminate. Both allocation and deallocation functions must be thread-safe.

    You must call Worker_SetAllocator once before any other API calls. Calling it multiple times or after another API call has been made is undefined behaviour.

    Returns:

  • void:

    Parameters
    • Worker_AllocateFunction*:
    • Worker_DeallocateFunction*:
    • void*:
  • Worker_DefaultConnectionParameters function
    Worker_ConnectionParameters Worker_DefaultConnectionParameters(void)

    Returns a new Worker_ConnectionParameters with default values set.

    Returns:

  • Worker_ConnectionParameters:

    Parameters
    • void:
  • Worker_Locator_Create function
    Worker_Locator* Worker_Locator_Create(const char* hostname, uint16_t port, const Worker_LocatorParameters* params)

    Creates a client which can be used to connect to a SpatialOS deployment via a locator service. This is the standard flow used to connect a local worker to a cloud deployment.

    The hostname would typically be "locator.improbable.io".

    The port number is used to connect to the locator service. This should be set to zero if connecting to a locator service running on the cloud.

    Returns:

  • Worker_Locator*:

    Parameters
    • const char*:
    • uint16_t:
    • const Worker_LocatorParameters*:
  • Worker_Locator_Destroy function
    void Worker_Locator_Destroy(Worker_Locator* locator)

    Frees resources for a Worker_Locator created with Worker_Locator_Create.

    Returns:

  • void:

    Parameters
    • Worker_Locator*:
  • Worker_Locator_GetDeploymentListAsync function
    Worker_DeploymentListFuture* Worker_Locator_GetDeploymentListAsync(const Worker_Locator* locator)

    (Deprecated) Queries the current list of deployments for the project given in the Worker_LocatorParameters.

    Returns:

  • Worker_DeploymentListFuture*:

    Parameters
    • const Worker_Locator*:
  • Worker_Locator_ConnectAndQueueAsync function
    Worker_ConnectionFuture* Worker_Locator_ConnectAndQueueAsync(const Worker_Locator* locator, const char* deployment_name, const Worker_ConnectionParameters* params, void* data, Worker_QueueStatusCallback* callback)

    (Deprecated) Connects to a specific deployment. The deployment name should be obtained by calling Worker_Locator_GetDeploymentListAsync. The callback should return zero to cancel queuing, or non-zero to continue queueing.

    Returns a Worker_ConnectionFuture that can be used to obtain a Worker_Connection by using Worker_ConnectionFuture_Get. Caller is responsible for destroying it when no longer needed by using Worker_ConnectionFuture_Destroy.

    Returns:

  • Worker_ConnectionFuture*:

    Parameters
    • const Worker_Locator*:
    • const char*:
    • const Worker_ConnectionParameters*:
    • void*:
    • Worker_QueueStatusCallback*:
  • Worker_Locator_ConnectAsync function
    Worker_ConnectionFuture* Worker_Locator_ConnectAsync(const Worker_Locator* locator, const Worker_ConnectionParameters* params)

    Connects to a specific deployment. The deployment is defined by the login token, which is obtained from a game authentication server, along with a player identity token.

    Returns a Worker_ConnectionFuture that can be used to obtain a Worker_Connection by using Worker_ConnectionFuture_Get. Caller is responsible for destroying it when no longer needed by using Worker_ConnectionFuture_Destroy.

    Returns:

  • Worker_ConnectionFuture*:

    Parameters
    • const Worker_Locator*:
    • const Worker_ConnectionParameters*:
  • Worker_ConnectAsync function
    Worker_ConnectionFuture* Worker_ConnectAsync(const char* hostname, uint16_t port, const char* worker_id, const Worker_ConnectionParameters* params)

    Connect to a SpatialOS deployment via a receptionist. This is the flow used to connect a managed worker running in the cloud alongside the deployment, and also to connect any local worker to a (local or remote) deployment via a locally-running receptionist.

    The hostname and port would typically be provided by SpatialOS on the command-line, if this is a managed worker on the cloud, or otherwise be predetermined (e.g. localhost:7777 for the default receptionist of a locally-running deployment).

    Returns a Worker_ConnectionFuture that can be used to obtain a Worker_Connection by using Worker_ConnectionFuture_Get. Caller is responsible for destroying it when no longer needed by using Worker_ConnectionFuture_Destroy.

    Returns:

  • Worker_ConnectionFuture*:

    Parameters
    • const char*:
    • uint16_t:
    • const char*:
    • const Worker_ConnectionParameters*:
  • Worker_DeploymentListFuture_Destroy function
    void Worker_DeploymentListFuture_Destroy(Worker_DeploymentListFuture* future)

    Destroys a Worker_DeploymentListFuture. Blocks until the future has completed.

    Returns:

  • void:

    Parameters
    • Worker_DeploymentListFuture*:
  • Worker_DeploymentListFuture_Get function
    void Worker_DeploymentListFuture_Get(Worker_DeploymentListFuture* future, const uint32_t* timeout_millis, void* data, Worker_DeploymentListCallback* callback)

    Gets the result of a Worker_DeploymentListFuture, waiting for up to *timeout_millis to become available (or forever if timeout_millis is NULL).

    It is an error to call this method again once it has succeeded (e.g. not timed out) once.

    Returns:

  • void:

    Parameters
    • Worker_DeploymentListFuture*:
    • const uint32_t*:
    • void*:
    • Worker_DeploymentListCallback*:
  • Worker_Alpha_CreateDevelopmentPlayerIdentityTokenAsync function
    Worker_Alpha_PlayerIdentityTokenResponseFuture* Worker_Alpha_CreateDevelopmentPlayerIdentityTokenAsync(const char* hostname, uint16_t port, Worker_Alpha_PlayerIdentityTokenRequest* params)

    Calls the Development Authentication Service to generate a PIT.

    Returns:

  • Worker_Alpha_PlayerIdentityTokenResponseFuture*:

    Parameters
    • const char*:
    • uint16_t:
    • Worker_Alpha_PlayerIdentityTokenRequest*:
  • Worker_Alpha_PlayerIdentityTokenResponseFuture_Destroy function
    void Worker_Alpha_PlayerIdentityTokenResponseFuture_Destroy(Worker_Alpha_PlayerIdentityTokenResponseFuture* future)

    Destroys a Worker_Alpha_PlayerIdentityTokenResponseFuture. Blocks until the future has completed.

    Returns:

  • void:

    Parameters
    • Worker_Alpha_PlayerIdentityTokenResponseFuture*:
  • Worker_Alpha_PlayerIdentityTokenResponseFuture_Get function
    void Worker_Alpha_PlayerIdentityTokenResponseFuture_Get(Worker_Alpha_PlayerIdentityTokenResponseFuture* future, const uint32_t* timeout_millis, void* data, Worker_Alpha_PlayerIdentityTokenResponseCallback* callback)

    Gets the result of a Worker_Alpha_PlayerIdentityTokenResponseFuture, waiting for up to *timeout_millis to become available (or forever if timeout_millis is NULL).

    It is an error to call this method again once it has succeeded (e.g. not timed out) once.

    Returns:

  • void:

    Parameters
    • Worker_Alpha_PlayerIdentityTokenResponseFuture*:
    • const uint32_t*:
    • void*:
    • Worker_Alpha_PlayerIdentityTokenResponseCallback*:
  • Worker_Alpha_CreateDevelopmentLoginTokensAsync function
    Worker_Alpha_LoginTokensResponseFuture* Worker_Alpha_CreateDevelopmentLoginTokensAsync(const char* hostname, uint16_t port, Worker_Alpha_LoginTokensRequest* params)

    Calls the Development Login Service to generate a login token list.

    Returns:

  • Worker_Alpha_LoginTokensResponseFuture*:

    Parameters
    • const char*:
    • uint16_t:
    • Worker_Alpha_LoginTokensRequest*:
  • Worker_Alpha_LoginTokensResponseFuture_Destroy function
    void Worker_Alpha_LoginTokensResponseFuture_Destroy(Worker_Alpha_LoginTokensResponseFuture* future)

    Destroys a Worker_Alpha_LoginTokensResponseFuture. Blocks until the future has completed.

    Returns:

  • void:

    Parameters
    • Worker_Alpha_LoginTokensResponseFuture*:
  • Worker_Alpha_LoginTokensResponseFuture_Get function
    void Worker_Alpha_LoginTokensResponseFuture_Get(Worker_Alpha_LoginTokensResponseFuture* future, const uint32_t* timeout_millis, void* data, Worker_Alpha_LoginTokensResponseCallback* callback)

    Gets the result of a Worker_Alpha_LoginTokensResponseFuture, waiting for up to *timeout_millis to become available (or forever if timeout_millis is NULL).

    It is an error to call this method again once it has succeeded (e.g. not timeout out) once.

    Returns:

  • void:

    Parameters
    • Worker_Alpha_LoginTokensResponseFuture*:
    • const uint32_t*:
    • void*:
    • Worker_Alpha_LoginTokensResponseCallback*:
  • Worker_ConnectionFuture_Destroy function
    void Worker_ConnectionFuture_Destroy(Worker_ConnectionFuture* future)

    Destroys a Worker_ConnectionFuture. Blocks until the future has completed.

    Returns:

  • void:

    Parameters
    • Worker_ConnectionFuture*:
  • Worker_ConnectionFuture_Get function
    Worker_Connection* Worker_ConnectionFuture_Get(Worker_ConnectionFuture* future, const uint32_t* timeout_millis)

    Gets the result of a Worker_ConnectionFuture, waiting for up to *timeout_millis to become available (or forever if timeout_millis is NULL). It returns NULL in case of a timeout.

    It is an error to call this method again once it has succeeded (e.g. not timed out) once.

    Returns:

  • Worker_Connection*:

    Parameters
    • Worker_ConnectionFuture*:
    • const uint32_t*:
  • Worker_Connection_Destroy function
    void Worker_Connection_Destroy(Worker_Connection* connection)

    Frees resources for a Worker_Connection created with Worker_ConnectAsync or Worker_Locator_ConnectAsync.

    Returns:

  • void:

    Parameters
    • Worker_Connection*:
  • Worker_Connection_Alpha_Flush function
    void Worker_Connection_Alpha_Flush(Worker_Connection* connection)

    Indicates to the network layer that all previous invocations of the Worker_Connection_Send* methods should be flushed to the network as soon as possible. A common usage pattern is to call this function after all state changes have been applied at the end of a frame.

    This method is asynchronous. In particular, calling is an indication that a flush is wanted, and can return before messages are fully serialized and put on the network. This currently only has an effect if using the Worker_ModularKcpNetworkParameters or Worker_ModularTcpNetworkParameters.

    Returns:

  • void:

    Parameters
    • Worker_Connection*:
  • Worker_Connection_SendLogMessage function
    void Worker_Connection_SendLogMessage(Worker_Connection* connection, const Worker_LogMessage* log_message)

    Sends a log message from the worker to SpatialOS.

    Returns:

  • void:

    Parameters
    • Worker_Connection*:
    • const Worker_LogMessage*:
  • Worker_Connection_SendMetrics function
    void Worker_Connection_SendMetrics(Worker_Connection* connection, const Worker_Metrics* metrics)

    Sends metrics data for the worker to SpatialOS.

    Returns:

  • void:

    Parameters
    • Worker_Connection*:
    • const Worker_Metrics*:
  • Worker_Connection_SendReserveEntityIdsRequest function
    Worker_RequestId Worker_Connection_SendReserveEntityIdsRequest(Worker_Connection* connection, const uint32_t number_of_entity_ids, const uint32_t* timeout_millis)

    Requests SpatialOS to reserve multiple entity IDs.

    Note: We do not recommend reserving entity IDs. Instead, we recommend using Worker_SendCreateEntityRequest without specifying an entity ID. You can then use the automatically assigned entity ID provided in Worker_CreateEntityResponseOp.

    Returns:

  • Worker_RequestId:

    Parameters
    • Worker_Connection*:
    • const uint32_t:
    • const uint32_t*:
  • Worker_Connection_SendCreateEntityRequest function
    Worker_RequestId Worker_Connection_SendCreateEntityRequest(Worker_Connection* connection, uint32_t component_count, Worker_ComponentData* components, const Worker_EntityId* entity_id, const uint32_t* timeout_millis)

    Requests SpatialOS to create an entity. If components[i].schema_type is set, ownership is transferred to the SDK, and components[i].schema_type is set to NULL. If components[i].schema_type is NULL and components[i].user_handle is set, the entity data is serialized immediately using the corresponding vtable serialize function.

    Returns Worker_RequestId -1 if the component is not registered and the default vtable is not found.

    Returns:

  • Worker_RequestId:

    Parameters
    • Worker_Connection*:
    • uint32_t:
    • Worker_ComponentData*:
    • const Worker_EntityId*:
    • const uint32_t*:
  • Worker_Connection_SendDeleteEntityRequest function
    Worker_RequestId Worker_Connection_SendDeleteEntityRequest(Worker_Connection* connection, Worker_EntityId entity_id, const uint32_t* timeout_millis)

    Requests SpatialOS to delete an entity.

    Returns:

  • Worker_RequestId:

    Parameters
    • Worker_Connection*:
    • Worker_EntityId:
    • const uint32_t*:
  • Worker_Connection_SendEntityQueryRequest function
    Worker_RequestId Worker_Connection_SendEntityQueryRequest(Worker_Connection* connection, const Worker_EntityQuery* entity_query, const uint32_t* timeout_millis)

    Queries SpatialOS for entity data.

    Returns Worker_RequestId -1 if the query constraint or result type are not valid.

    Returns:

  • Worker_RequestId:

    Parameters
    • Worker_Connection*:
    • const Worker_EntityQuery*:
    • const uint32_t*:
  • Worker_Connection_SendComponentUpdate function
    int8_t Worker_Connection_SendComponentUpdate(Worker_Connection* connection, Worker_EntityId entity_id, Worker_ComponentUpdate* component_update, const Worker_UpdateParameters* update_parameters)

    Sends a component update for the given entity to SpatialOS.

    If component_update->schema_type is set, ownership is transferred to the SDK, and component_update->schema_type is set to NULL. If component_update->user_handle is set, then it will be copied with the corresponding vtable copy function, then the copy is later freed with the vtable free function.

    Note that if update_parameters.loopback = 1 or update_parameters = NULL, the component update operation is added to the operation list and will be returned by a subsequent call to Worker_Connection_GetOpList.

    Returns WORKER_RESULT_FAILURE if the component is not registered and the default vtable is not found.

    Returns:

  • int8_t:

    Parameters
    • Worker_Connection*:
    • Worker_EntityId:
    • Worker_ComponentUpdate*:
    • const Worker_UpdateParameters*:
  • Worker_Connection_SendAddComponent function
    int8_t Worker_Connection_SendAddComponent(Worker_Connection* connection, Worker_EntityId entity_id, Worker_ComponentData* component_data, const Worker_UpdateParameters* update_parameters)

    Adds a new component to the given entity in SpatialOS.

    If component_data->schema_type is set, ownership is transferred to the SDK, and component_data->schema_type is set to NULL. If component_data->user_handle is set, then it will be copied with the corresponding vtable copy function, then the copy is later freed with the vtable free function.

    Note that if update_parameters.loopback = 1 or update_parameters = NULL, the add component operation is added to the operation list and will be returned by a subsequent call to Worker_Connection_GetOpList.

    Returns WORKER_RESULT_FAILURE if the component is not registered and the default vtable is not found.

    Returns:

  • int8_t:

    Parameters
    • Worker_Connection*:
    • Worker_EntityId:
    • Worker_ComponentData*:
    • const Worker_UpdateParameters*:
  • Worker_Connection_SendRemoveComponent function
    void Worker_Connection_SendRemoveComponent(Worker_Connection* connection, Worker_EntityId entity_id, Worker_ComponentId component_id, const Worker_UpdateParameters* update_parameters)

    Removes a component from a given entity in SpatialOS.

    If update_parameters.loopback = 1 or update_parameters = NULL, the remove component operation is added to the operation list and will be returned by a subsequent call to Worker_Connection_GetOpList.

    In order to use this function, Worker_ConnectionParameters::enable_dynamic_components must be set to 1 (true).

    This function does not check whether the worker currently has authority over the component, you must make sure the worker has authority in order to remove the component.

    Returns:

  • void:

    Parameters
    • Worker_Connection*:
    • Worker_EntityId:
    • Worker_ComponentId:
    • const Worker_UpdateParameters*:
  • Worker_Connection_SendCommandRequest function
    Worker_RequestId Worker_Connection_SendCommandRequest(Worker_Connection* connection, Worker_EntityId entity_id, Worker_CommandRequest* request, const uint32_t* timeout_millis, const Worker_CommandParameters* command_parameters)

    Sends a command request targeting the given entity and component to SpatialOS. If timeout_millis is null, the default will be used.

    If request->schema_type is set, ownership is transferred to the SDK, and request->schema_type is set to NULL. If request->user_handle is set, then it will be copied with the corresponding vtable copy function, then the copy is later freed with the vtable free function.

    If command parameters argument is NULL, then command short circuiting will be disabled.

    Returns Worker_RequestId -1 if the component is not registered and the default vtable is not found.

    Returns:

  • Worker_RequestId:

    Parameters
    • Worker_Connection*:
    • Worker_EntityId:
    • Worker_CommandRequest*:
    • const uint32_t*:
    • const Worker_CommandParameters*:
  • Worker_Connection_SendCommandResponse function
    int8_t Worker_Connection_SendCommandResponse(Worker_Connection* connection, Worker_RequestId request_id, Worker_CommandResponse* response)

    Sends a command response for the given request ID to SpatialOS.

    If response->schema_type is set, ownership is transferred to the SDK, and response->schema_type is set to NULL. If response->user_handle is set, then it will be copied with the corresponding vtable copy function, then the copy is later freed with the vtable free function.

    Returns WORKER_RESULT_FAILURE if the component is not registered and the default vtable is not found.

    Returns:

  • int8_t:

    Parameters
    • Worker_Connection*:
    • Worker_RequestId:
    • Worker_CommandResponse*:
  • Worker_Connection_SendCommandFailure function
    void Worker_Connection_SendCommandFailure(Worker_Connection* connection, Worker_RequestId request_id, const char* message)

    Sends an explicit failure for the given command request ID to SpatialOS.

    Returns:

  • void:

    Parameters
    • Worker_Connection*:
    • Worker_RequestId:
    • const char*:
  • Worker_Connection_SendComponentInterest function
    void Worker_Connection_SendComponentInterest(Worker_Connection* connection, Worker_EntityId entity_id, const Worker_InterestOverride* interest_override, uint32_t interest_override_count)

    (Deprecated) Sends a diff-based component interest update for the given entity to SpatialOS. By default, the worker receives data for all entities according to the default component interest specified in its bridge settings. This function allows interest override by (entity ID, component ID) pair to force the data to either always be sent or never be sent. Note that this does not apply if the worker is authoritative over a particular (entity ID, component ID) pair, in which case the data is always sent.

    Returns:

  • void:

    Parameters
    • Worker_Connection*:
    • Worker_EntityId:
    • const Worker_InterestOverride*:
    • uint32_t:
  • Worker_Connection_SendAuthorityLossImminentAcknowledgement function
    void Worker_Connection_SendAuthorityLossImminentAcknowledgement(Worker_Connection* connection, Worker_EntityId entity_id, Worker_ComponentId component_id)

    (deprecated) Sends an acknowledgement of the receipt of an AuthorityLossImminent authority change for a component. Sending the acknowledgement signifies that this worker is ready to lose authority over the component.

    Returns:

  • void:

    Parameters
    • Worker_Connection*:
    • Worker_EntityId:
    • Worker_ComponentId:
  • Worker_Connection_SetProtocolLoggingEnabled function
    void Worker_Connection_SetProtocolLoggingEnabled(Worker_Connection* connection, uint8_t enabled)

    (Deprecated) Enables or disables legacy protocol logging. Logging uses the parameters specified when the connection was created. Enabling it when already enabled, or disabling it when already disabled, does nothing.

    Note that logs from any previous protocol logging sessions will be overwritten.

    Either use this or the array of logsinks in Worker_ConnectionParameters. If you call this to disable protocol logging while other logsinks are enabled, those will be disabled as well.

    Returns:

  • void:

    Parameters
    • Worker_Connection*:
    • uint8_t:
  • Worker_Connection_EnableLogging function
    void Worker_Connection_EnableLogging(Worker_Connection* connection)

    Reenables all logging. If logging was already enabled or no logsinks had been configured during connecting, does nothing. This also re-enables the deprecated protocol logging, if it was enabled at least once using Worker_Connection_SetProtocolLoggingEnabled before.

    Returns:

  • void:

    Parameters
    • Worker_Connection*:
  • Worker_Connection_DisableLogging function
    void Worker_Connection_DisableLogging(Worker_Connection* connection)

    Disables all logging. If logging was already disabled or no logsinks had been configured during connecting, does nothing. This also disables the deprecated protocol logging, if it was enabled at least once using Worker_Connection_SetProtocolLoggingEnabled before.

    Returns:

  • void:

    Parameters
    • Worker_Connection*:
  • Worker_Connection_IsConnected function
    uint8_t Worker_Connection_IsConnected(const Worker_Connection* connection)

    Returns true if the connection has been successfully created and communication is ongoing. DEPRECATED: Equivalent to Worker_Connection_GetConnectionStatusCode(connection) == WORKER_CONNECTION_STATUS_CODE_SUCCESS.

    Returns:

  • uint8_t:

    Parameters
    • const Worker_Connection*:
  • Worker_Connection_GetConnectionStatusCode function
    uint8_t Worker_Connection_GetConnectionStatusCode(const Worker_Connection* connection)

    Returns a value from the Worker_ConnectionStatusCode enum. Returns WORKER_CONNECTION_STATUS_SUCCESS if the connection is connected and usable, otherwise a value indicating the type of error that occurred.

    Returns:

  • uint8_t:

    Parameters
    • const Worker_Connection*:
  • Worker_Connection_GetConnectionStatusDetailString function
    const char* Worker_Connection_GetConnectionStatusDetailString(const Worker_Connection* connection)

    Returns a null terminated string containing more detailed information about the connection status. The returned pointer points to data that is owned by the SDK and will remain valid for the lifetime of the connection.

    Returns:

  • const char*:

    Parameters
    • const Worker_Connection*:
  • Worker_Connection_GetWorkerId function
    const char* Worker_Connection_GetWorkerId(const Worker_Connection* connection)

    Retrieves the ID of the worker as assigned by the runtime as a null terminated string. The returned pointer points to data that is owned by the SDK and will remain valid for the lifetime of the connection. If the connection has failed, then the returned string will be a valid but empty string.

    Returns:

  • const char*:

    Parameters
    • const Worker_Connection*:
  • Worker_Connection_GetWorkerAttributes function
    const Worker_WorkerAttributes* Worker_Connection_GetWorkerAttributes(const Worker_Connection* connection)

    Retrieves the attributes associated with the worker at runtime. The result to data that is owned by the SDK and will remain valid for the lifetime of the connection. If the connection has failed, then the returned array of strings will be NULL.

    Returns:

  • const Worker_WorkerAttributes*:

    Parameters
    • const Worker_Connection*:
  • Worker_Connection_GetWorkerFlag function
    void Worker_Connection_GetWorkerFlag(const Worker_Connection* connection, const char* name, void* user_data, Worker_GetWorkerFlagCallback* callback)

    Queries the worker flag with the given name. If the worker flag does not exist, the value will be NULL.

    Worker flags are remotely configurable and may change during the runtime of the worker, including addition and deletion.

    Returns:

  • void:

    Parameters
    • const Worker_Connection*:
    • const char*:
    • void*:
    • Worker_GetWorkerFlagCallback*:
  • Worker_Connection_GetOpList function
    Worker_OpList* Worker_Connection_GetOpList(Worker_Connection* connection, uint32_t timeout_millis)

    Retrieves the list of operations that have occurred since the last call to this function.

    If timeout_millis is non-zero, the function will block until there is at least one operation to return, or the timeout has been exceeded. If the timeout is exceeded, an empty list will be returned.

    If timeout_millis is zero the function is non-blocking.

    It is the caller's responsibility to destroy the returned Worker_OpList with the Worker_OpList_Destroy function.

    Note: All data contained within the op-list (such as component data or updates) is owned by Worker_OpList, and must not be passed directly to another function in the SDK, such as Worker_Connection_SendComponentUpdate, without copying the data first. Otherwise, a double free could occur.

    Returns:

  • Worker_OpList*:

    Parameters
    • Worker_Connection*:
    • uint32_t:
  • Worker_OpList_Destroy function
    void Worker_OpList_Destroy(Worker_OpList* op_list)

    Frees resources for Worker_OpList returned by Worker_Connection_GetOpList.

    Returns:

  • void:

    Parameters
    • Worker_OpList*:
  • Worker_SnapshotInputStream_Create function
    Worker_SnapshotInputStream* Worker_SnapshotInputStream_Create(const char* filename, const Worker_SnapshotParameters* params)

    Opens a Worker_SnapshotInputStream. The caller must manage the memory of the returned Worker_SnapshotInputStream* by calling Worker_SnapshotInputStream_Destroy to write the EOF and release resources.

    If an error occurs, a pointer to a Worker_SnapshotInputStream is still returned. Calling Worker_SnapshotInputStream_GetState with this pointer will return an error message describing any error that occured. In the event of an error, the caller still must release the memory of the Worker_SnapshotInputStream by calling Worker_SnapshotInputStream_Destroy.

    Returns:

  • Worker_SnapshotInputStream*:

    Parameters
    • const char*:
    • const Worker_SnapshotParameters*:
  • Worker_SnapshotInputStream_Destroy function
    void Worker_SnapshotInputStream_Destroy(Worker_SnapshotInputStream* input_stream)

    Closes the SnapshotInputStream and releases its resources.

    Returns:

  • void:

    Parameters
    • Worker_SnapshotInputStream*:
  • Worker_SnapshotInputStream_HasNext function
    uint8_t Worker_SnapshotInputStream_HasNext(Worker_SnapshotInputStream* input_stream)

    Returns zero (false) if the Worker_SnapshotInputStream has reached the EOF of the Snapshot.

    Returns:

  • uint8_t:

    Parameters
    • Worker_SnapshotInputStream*:
  • Worker_SnapshotInputStream_ReadEntity function
    const Worker_Entity* Worker_SnapshotInputStream_ReadEntity(Worker_SnapshotInputStream* input_stream)

    Reads next Worker_Entity* entity from input_stream.

    Worker_SnapshotInputStream_ReadEntity manages the memory for the returned entity internally. The next call to Worker_SnapshotInputStream_ReadEntity or Worker_SnapshotInputStream_Destroy invalidates this value; use Worker_AcquireComponentData as usual to preserve component data.

    If an error occurs, or the stream has reached the end of the file, then this function will return a null pointer.

    In the case that a null pointer is returned, you must call Worker_SnapshotInputStream_GetState to get the details of what error occurred during the operation.

    Returns:

  • const Worker_Entity*:

    Parameters
    • Worker_SnapshotInputStream*:
  • Worker_SnapshotInputStream_GetState function
    Worker_SnapshotState Worker_SnapshotInputStream_GetState(Worker_SnapshotInputStream* input_stream)

    Must be called after every Worker_SnapshotInputStream operation to get the state code of the stream after the previous operation.

    Returns a Worker_SnapshotState which contains the stream state code and an error message: if the code is WORKER_STREAM_STATE_GOOD no error occurred.

    Returns:

  • Worker_SnapshotState:

    Parameters
    • Worker_SnapshotInputStream*:
  • Worker_SnapshotOutputStream_Create function
    Worker_SnapshotOutputStream* Worker_SnapshotOutputStream_Create(const char* filename, const Worker_SnapshotParameters* params)

    Opens Worker_SnapshotOutputStream stream. The caller must manage the memory of the returned Worker_SnapshotOutputStream* by calling Worker_SnapshotOutputStream_Destroy to write the EOF and release resources.

    If an error occurs, a pointer to a Worker_SnapshotOutputStream is still returned. Calling Worker_SnapshotOutputStream_GetState with this pointer will return an error message describing any error that occured. In the event of an error, the caller still must release the memory of the Worker_SnapshotOutputStream by calling Worker_SnapshotOutputStream_Destroy.

    Returns:

  • Worker_SnapshotOutputStream*:

    Parameters
    • const char*:
    • const Worker_SnapshotParameters*:
  • Worker_SnapshotOutputStream_Destroy function
    void Worker_SnapshotOutputStream_Destroy(Worker_SnapshotOutputStream* output_stream)

    Closes the snapshot output stream and releases its resources.

    Returns:

  • void:

    Parameters
    • Worker_SnapshotOutputStream*:
  • Worker_SnapshotOutputStream_WriteEntity function
    void Worker_SnapshotOutputStream_WriteEntity(Worker_SnapshotOutputStream* output_stream, const Worker_Entity* entity)

    Writes next entity_id, entity pair from input. Must call Worker_SnapshotOutputStream_GetState after this function to check whether any error occurred during operation.

    Returns:

  • void:

    Parameters
    • Worker_SnapshotOutputStream*:
    • const Worker_Entity*:
  • Worker_SnapshotOutputStream_GetState function
    Worker_SnapshotState Worker_SnapshotOutputStream_GetState(Worker_SnapshotOutputStream* output_stream)

    Must be called after every Worker_SnapshotOutputStream operation to get the state code of the stream after the previous operation.

    Returns a Worker_SnapshotState which contains the stream state code and an error message: if the code is WORKER_STREAM_STATE_GOOD no error occurred.

    Returns:

  • Worker_SnapshotState:

    Parameters
    • Worker_SnapshotOutputStream*:
  • Worker_SnapshotOutputStream_GetLastWarning function
    const char* Worker_SnapshotOutputStream_GetLastWarning(Worker_SnapshotOutputStream* output_stream)

    Returns the last warning message generated by a call to Worker_SnapshotOutputStream_WriteEntity. Will return NULL if no warning was generated.

    Returns:

  • const char*:

    Parameters
    • Worker_SnapshotOutputStream*:
  • ngrpc.h

    This file defines a low-level gRPC (https://grpc.io/) client. It currently only supports unary (non-streaming) gRPC calls.

    Example usage (non-secure):

    #include <stdint.h>
    #include <stdio.h>
    #include <stdlib.h>
    Ngrpc_Parameters grpc_params = {0};
    grpc_params.connect_timeout_ms = 5000;
    Ngrpc_Client grpc = Ngrpc_Create("localhost", 50051, &grpc_params);
    Ngrpc_Status create_status = Ngrpc_GetStatus(grpc);
    if (create_status.code != NGRPC_STATUS_CODE_OK) {
    fprintf(stderr, "Failed to create gRPC client:\n %s\n", create_status.message);
    Ngrpc_Destroy(grpc);
    exit(EXIT_FAILURE);
    }
    Ngrpc_CallParameters call_params = {0};
    call_params.timeout_ms = 5000;
    Ngrpc_Call
    call = Ngrpc_MakeCall(grpc, "/test.Service/Method", &call_params);
    const uint8_t payload[] = {0x08, 0x2a}; // Message in binary protobuf format.
    if (Ngrpc_Send(call, payload, sizeof payload)) {
    Ngrpc_Buffer response = Ngrpc_Receive(call);
    if (response.buffer) {
    // Process response here...
    } else {
    printf("Receive failed.\n");
    }
    } else {
    printf("Send failed.\n");
    }
    Ngrpc_Status result = Ngrpc_FinishCall(call);
    printf("Status code: %s (%d)\n", Ngrpc_StatusCodeToString(result.code), result.code);
    printf("Status message: %s\n", result.message);
    Ngrpc_DestroyCall(call);
    Ngrpc_Destroy(grpc);


    Type Definitions

    Ngrpc_Client typedef
    typedef struct Ngrpc_Client Ngrpc_Client
    The gRPC client root object. Can be used for multiple calls to a single a server.

    Ngrpc_Call typedef
    typedef struct Ngrpc_Call Ngrpc_Call
    A single gRPC call.


    Enums

    Ngrpc_StatusCode enum
    gRPC status code. Mirrors https://github.com/grpc/grpc/blob/master/doc/statuscodes.md.

    Values:
    • NGRPC_STATUS_CODE_OK = 0:
    • NGRPC_STATUS_CODE_CANCELLED = 1:
    • NGRPC_STATUS_CODE_UNKNOWN = 2:
    • NGRPC_STATUS_CODE_INVALID_ARGUMENT = 3:
    • NGRPC_STATUS_CODE_DEADLINE_EXCEEDED = 4:
    • NGRPC_STATUS_CODE_NOT_FOUND = 5:
    • NGRPC_STATUS_CODE_ALREADY_EXISTS = 6:
    • NGRPC_STATUS_CODE_PERMISSION_DENIED = 7:
    • NGRPC_STATUS_CODE_RESOURCE_EXHAUSTED = 8:
    • NGRPC_STATUS_CODE_FAILED_PRECONDITION = 9:
    • NGRPC_STATUS_CODE_ABORTED = 10:
    • NGRPC_STATUS_CODE_OUT_OF_RANGE = 11:
    • NGRPC_STATUS_CODE_UNIMPLEMENTED = 12:
    • NGRPC_STATUS_CODE_INTERNAL = 13:
    • NGRPC_STATUS_CODE_UNAVAILABLE = 14:
    • NGRPC_STATUS_CODE_DATA_LOSS = 15:
    • NGRPC_STATUS_CODE_UNAUTHENTICATED = 16:
    • NGRPC_STATUS_CODE_NGRPC_CLIENT_ERROR = 100: An internal error of this gRPC client implementation.


    Structs

    Ngrpc_Parameters struct
    Parameters to create an Ngrpc_Client.


    Fields:
    • uint64_t connect_timeout_ms: The connection timeout in milliseconds. Use 0 for no timeout.
    • uint8_t use_tls: Whether to use a secure connection (TLS).
    • Ngrpc_TlsParameters* tls_params: Parameters for TLS. Ignored if use_tls is not set.
    Ngrpc_TlsParameters struct
    Transport Layer Security (TLS) parameters. Ngrpc_Client does not attempt to use the platform- specific root certificate store of the current machine. Instead, one or more root certificates must be provided as part of the connection parameters.


    Fields:
    • uint32_t root_certificate_count: Number of root certificates.
    • const char* const* root_certificates: Pointer to root certificates in PEM format.
    Ngrpc_Status struct
    A gRPC status code and message. Used as the result of initial connection and individual calls.


    Fields:
    • Ngrpc_StatusCode code: The gRPC status code.
    • const char* message: The status message. Always non-NULL, but can be empty.
    Ngrpc_CallParameters struct
    Parameters to create an Ngrpc_Call.


    Fields:
    • uint64_t timeout_ms: Timeout for the entire call in milliseconds. Use 0 for no timeout.
    • uint32_t metadata_count: Number of metadata key-value pairs to attach to the call.
    • const Ngrpc_CallMetadata* metadata: Pointer to metadata key-value pairs.
    Ngrpc_CallMetadata struct
    Metadata key-value pairs to attach to a gRPC call.


    Fields:
    • const char* key: Key string. Must be unique, lower case, and not clash with a standard HTTP/2 header name.
    • const char* value: Value string.
    Ngrpc_Buffer struct
    A pointer to a block of binary data and its length.


    Fields:
    • const uint8_t* buffer: Pointer to the data. Can be NULL to indicate an end-of-stream or error condition.
    • uint32_t length: Length of the data.


    Functions

    Ngrpc_Create function
    Ngrpc_Client* Ngrpc_Create(const char* hostname, uint16_t port, const Ngrpc_Parameters* params)

    Creates an Ngrpc_Client which can be used to make calls to the specified gRPC server. Always returns a valid (non-NULL) pointer - use Ngrpc_GetStatus to check if creation was actually successful. All operations on an Ngrpc_Client and any of its associated Ngrpc_Calls are not thread-safe, so must not be performed concurrently. Use Ngrpc_Destroy to free resources when finished.

    Returns:

  • Ngrpc_Client*:

    Parameters
    • const char*:
    • uint16_t:
    • const Ngrpc_Parameters*:
  • Ngrpc_GetStatus function
    Ngrpc_Status Ngrpc_GetStatus(Ngrpc_Client* client)

    Returns the status of the Ngrpc_Client object. This will have code NGRPC_STATUS_CODE_OK if initial creation was successful, otherwise it will describe the error that occurred. The return value is the same throughout the lifetime of the Ngrpc_Client object. The returned status message string is only valid up until Ngrpc_Destroy is called on the Ngrpc_Client object.

    Returns:

  • Ngrpc_Status:

    Parameters
    • Ngrpc_Client*:
  • Ngrpc_Destroy function
    void Ngrpc_Destroy(Ngrpc_Client* client)

    Destroys (frees the resources associated with) the given Ngrpc_Client. Any active Ngrpc_Call objects associated with the Ngrpc_Client are also destroyed.

    Returns:

  • void:

    Parameters
    • Ngrpc_Client*:
  • Ngrpc_MakeCall function
    Ngrpc_Call* Ngrpc_MakeCall(Ngrpc_Client* client, const char* method_path, const Ngrpc_CallParameters* params)

    Creates a gRPC call object for making a single call. Always returns a valid (non-NULL) pointer. Use Ngrpc_DestroyCall (or Ngrpc_Destroy) to free resources when finished.

    Returns:

  • Ngrpc_Call*:

    Parameters
    • Ngrpc_Client*:
    • const char*:
    • const Ngrpc_CallParameters*:
  • Ngrpc_Send function
    uint8_t Ngrpc_Send(Ngrpc_Call* call, const uint8_t* buffer, uint32_t length)

    Sends the request portion of a gRPC call. Currently only supported once per Ngrpc_Call (no streaming). This function blocks until the send has completed (or an error or timeout occurs). Return value is 0 for failure, 1 for success. Retrieve error information using Ngrpc_FinishCall.

    Returns:

  • uint8_t:

    Parameters
    • Ngrpc_Call*:
    • const uint8_t*:
    • uint32_t:
  • Ngrpc_Receive function
    Ngrpc_Buffer Ngrpc_Receive(Ngrpc_Call* call)

    Receives the response portion of a gRPC call. This function blocks until a response is received (or an error or timeout occurs). The pointer in the returned Ngrpc_Buffer will be NULL if end-of-stream was reached or an error occurred. After such a NULL value, all future calls to Ngrpc_Receive with the same Ngrpc_Call object will also return NULL. As streaming responses are not currently supported, the second call will always return NULL. Retrieve error information using Ngrpc_FinishCall (NGRPC_STATUS_CODE_OK indicating that end-of-stream occurred rather than an actual error). The returned buffer is only valid until the next Ngrpc_Receive or Ngrpc_FinishCall operation on the Ngrpc_Call object.

    Returns:

  • Ngrpc_Buffer:

    Parameters
    • Ngrpc_Call*:
  • Ngrpc_FinishCall function
    Ngrpc_Status Ngrpc_FinishCall(Ngrpc_Call* call)

    Finishes a gRPC call, returning the call status information. Can only be called once per Ngrpc_Call object, and no operation other than Ngrpc_DestroyCall can be performed on the Ngrpc_Call object subsequently. The returned status message string is only valid up until Ngrpc_DestroyCall is called on the Ngrpc_Call object.

    Returns:

  • Ngrpc_Status:

    Parameters
    • Ngrpc_Call*:
  • Ngrpc_DestroyCall function
    void Ngrpc_DestroyCall(Ngrpc_Call* call)

    Destroys (frees the resources associated with) the given Ngrpc_Call.

    Returns:

  • void:

    Parameters
    • Ngrpc_Call*:
  • Ngrpc_StatusCodeToString function
    const char* Ngrpc_StatusCodeToString(Ngrpc_StatusCode status)

    Converts a gRPC status code into string form, for example, for inclusion in log messages. The returned string is always non-NULL, but can be empty in case of an unknown status code. The returned string is valid indefinitely.

    Returns:

  • const char*:

    Parameters
    • Ngrpc_StatusCode:
  • Ngrpc_GetImprobableRootCertificate function
    const char* Ngrpc_GetImprobableRootCertificate(void)

    Returns Improbable's TLS root certificate in PEM format. Populate Ngrpc_TlsParameters with this value to use Platform SDK services. The returned string is valid indefinitely.

    Returns:

  • const char*:

    Parameters
    • void:
  • Updated 8 months ago


    C API Reference


    Suggested Edits are limited on API Reference Pages

    You can only suggest edits to Markdown body content, but not to the API spec.