C API Layer Functions

Layers

Create Layer

When client wants to create new layer, then following function has to be called:

 int32_t vrs_send_layer_create(const uint8_t session_id,
      const uint8_t prio,
      const uint32_t node_id,
      const uint16_t parent_layer_id,
      const uint8_t data_type,
      const uint8_t count,
      const uint16_t custom_type)

The argument parent_layer_id is the id of layer that can drive values in new layer. When client wants to create layer that doesn't have any parent layer, then it has to set parent_layer_id to -1. When some value in parent layer is destroyed, then value in child layer is automatically destroyed too. E.g. when position of vertex is destroyed, then color of vertex is considered as destroyed too. The name has to be unique in the node. One item of layer could contain following number of values: 1, 2, 3, 4 (argument count). So, it could be used for scalar, 2D vector, 3D vector and quaternion. More number of values is not supported.

Layer could be following data_type:

• uint8_t
• uint16_t
• uint32_t
• uint64_t
• float
• double

Layers are unnamed too and the custom_type has same meaning as custom_type of nodes, tag groups and tags. The custom_type has to be unique inside one node and developer can define several types of layer (e.g. #define VERTEX_COORDS_LAYER 1)

Previous function has corresponding registration of callback function:

 void vrs_register_receive_layer_create(
      void (*func)(const uint8_t session_id,
      const uint32_t node_id,
      const uint16_t parent_layer_id,
      const uint16_t layer_id,
      const uint8_t data_type,
      const uint8_t count,
      const uint16_t custom_type))

Destroy Layer

When client wants to destroy layer and all its data, then following function has to be called:

 int32_t vrs_send_layer_destroy(
      const uint8_t session_id,
      const uint8_t prio,
      const uint32_t node_id,
      const uint16_t layer_id)

Previous function has corresponding registration of callback function:

 void vrs_register_receive_layer_destroy(
      void (*func)(const uint8_t session_id,
      const uint32_t node_id,
      const uint16_t layer_id))

Subscribe and Unsubscribe from Layer

When client wants to subscribe to changes of data in layer, then it has to call fallowing function:

 int32_t vrs_send_layer_subscribe(
      const uint8_t session_id,
      const uint8_t prio,
      const uint32_t node_id,
      const uint16_t layer_id,
      const uint32_t version)

Previous function has corresponding registration of callback function:

 void vrs_register_receive_layer_subscribe(
      void (*func)(const uint8_t session_id,
      const uint32_t node_id,
      const uint16_t layer_id,
      const uint32_t version,
      const uint32_t crc32))

When client doesn't want to receive changes from layer anymore, then it has to call following function:

 int32_t vrs_send_layer_unsubscribe(
      const uint8_t session_id,
      const uint8_t prio,
      const uint32_t node_id,
      const uint16_t layer_id,
      const uint32_t version)

Previous function has corresponding registration of callback function:

 void vrs_register_receive_layer_unsubscribe(
      void (*func)(const uint8_t session_id,
      const uint32_t node_id,
      const uint16_t layer_id,
      const uint32_t version,
      const uint32_t crc32))

Set Data in Layer

When Verse client wants to set (create or change existing) value, then it has to call following function.

 int32_t vrs_send_layer_set_value(
      const uint8_t session_id,
      const uint8_t prio,
      const uint32_t node_id,
      const uint16_t layer_id,
      const uint32_t item_id,
      const uint8_t type,
      const uint8_t count,
      const void *value)

Previous function has corresponding registration of callback function:

 void vrs_register_receive_layer_set_value(
      void (*func)(const uint8_t session_id,
      const uint32_t node_id,
      const uint16_t layer_id,
      const uint32_t item_id,
      const uint8_t type,
      const uint8_t count,
      const void *value));

Unset Data in Layer

When client wants to unset (destroy) one value in layer, then it has to call following function. Keep in mind, that values in child layers will be considered as unset (destroyed) too.

 int32_t vrs_send_layer_unset_value(
      const uint8_t session_id,
      const uint8_t prio,
      const uint32_t node_id,
      const uint16_t layer_id,
      const uint32_t item_id);

Previous function has corresponding registration of callback function:

 void vrs_register_receive_layer_unset_value(
      void (*func)(const uint8_t session_id,
      const uint32_t node_id,
      const uint16_t layer_id,
      const uint32_t item_id));

Note: Previous functions (set_value and unset_value) will be considered as obsolete in the future, because these functions are not effective. Real applications sends lot of commands layer set value with same node_id, layer_id, type and count. Thus it is necessary to call previous functions several times with same values, when one UDP packet or TCP message is received. It would be better to modify previous functions and pass many values with item IDs into one function call.

Proposed variants of functions intended for setting and unsetting values:

 void vrs_register_receive_layer_set_values(
      void (*func)(const uint8_t session_id,
      const uint32_t node_id,
      const uint16_t layer_id,
      const uint8_t item_type,
      const void **values));

The argument **values would contain array of pointers at item_id and value(s) of item.

 void vrs_register_receive_layer_unset_values(
      void (*func)(const uint8_t session_id,
      const uint32_t node_id,
      const uint16_t layer_id,
      const uint32_t *item_ids));