Dynamic Type API¶

group dynamic_type

The Dynamic Type API to construct and manipulate data types.

Defines

DDS_DYNAMIC_MEMBER_ID_INVALID 0xf000000u¶: Invalid member ID: used when adding a member, to indicate that the member should get the id (m+1) where m is the highest member id in the current set of members. A valid member id has the 4 most significant bits set to 0 (because of usage in the EMHEADER), so also when hashed-id are used, the hash member id will never be set to the invalid member id.

DDS_DYNAMIC_MEMBER_INDEX_START 0u¶: When adding members, index 0 is used to indicate that a member should be inserted as the first member. A value higher than the current maximum index can be used to indicate that the member should be added after the other members

DDS_DYNAMIC_TYPE_SPEC(t) ((dds_dynamic_type_spec_t) { .kind = DDS_DYNAMIC_TYPE_KIND_DEFINITION, .type = { .type = (t) } })¶: Short notation for initializer of a dynamic type spec for non-primitive and primitive types.

DDS_DYNAMIC_MEMBER_(member_type_spec, member_name, member_id, member_index) ((dds_dynamic_member_descriptor_t ) { \ .name = (member_name), \ .id = (member_id), \ .type = (member_type_spec), \ .index = (member_index) \ }) ¶: Short notation for struct member descriptor with different sets of commonly used properties

DDS_DYNAMIC_UNION_MEMBER_(member_type_spec, member_name, member_id, member_index, member_num_labels, member_labels, member_is_default) ((dds_dynamic_member_descriptor_t ) { \ .name = (member_name), \ .id = (member_id), \ .type = (member_type_spec), \ .index = (member_index), \ .num_labels = (member_num_labels), \ .labels = (member_labels), \ .default_label = (member_is_default) \ }) ¶: Short notation for union member descriptor with different sets of commonly used properties

DDS_DYNAMIC_ENUM_LITERAL_VALUE_AUTO ((dds_dynamic_enum_literal_value_t) { DDS_DYNAMIC_ENUM_LITERAL_VALUE_NEXT_AVAIL, 0 })¶: Short notation for initializing a Dynamic Enum value struct.

DDS_DYNAMIC_BITMASK_POSITION_AUTO (UINT16_MAX)¶: Used to indicate that the bitmask field should get the next available position (current maximum + 1)

Typedefs

typedef struct dds_dynamic_type dds_dynamic_type_t¶

Dynamic Type.

Representation of a dynamically created type. This struct has an opaque pointer to the type in the type system. During construction of the type (setting properties and adding members), the internal type has the state ‘CONSTRUCTION’. Once the type is registered, the state is updated to ‘RESOLVED’ and the type cannot be modified.

The ‘ret’ member of this struct holds the return code of operations performed on this type. In case this value is not DDS_RETCODE_OK, the type cannot be used for further processing (e.g. adding members, registering the type, etc.).

typedef enum dds_dynamic_type_kind dds_dynamic_type_kind_t¶

Dynamic Type Kind.

Enumeration with the type kind values that can be used to create a dynamic type.

typedef enum dds_dynamic_type_spec_kind dds_dynamic_type_spec_kind_t¶: Dynamic Type specification kind

typedef struct dds_dynamic_type_spec dds_dynamic_type_spec_t¶: Dynamic Type specification: a reference to dynamic type, which can be a primitive type kind (just the type kind enumeration value), or a (primitive or non-primitive) dynamic type reference.

typedef struct dds_dynamic_type_descriptor dds_dynamic_type_descriptor_t¶

Dynamic Type descriptor.

Structure that holds the properties for creating a Dynamic Type. For each type kind, specific member fields are applicable and/or required.

typedef struct dds_dynamic_member_descriptor dds_dynamic_member_descriptor_t¶

Dynamic Type Member descriptor.

Structure that holds the properities for adding a member to a dynamic type. Depending on the member type, different fields apply and are required.

typedef struct dds_dynamic_enum_literal_value dds_dynamic_enum_literal_value_t¶: Dynamic Enumeration type literal value kind and value. Can be set to NEXT_AVAIL to indicate that the current max value + 1 should be used for this member, or an explicit value can be provided.

Enums

enum dds_dynamic_type_kind¶

Dynamic Type Kind.

Enumeration with the type kind values that can be used to create a dynamic type.

Values:

enumerator DDS_DYNAMIC_NONE¶

enumerator DDS_DYNAMIC_BOOLEAN¶

enumerator DDS_DYNAMIC_BYTE¶

enumerator DDS_DYNAMIC_INT16¶

enumerator DDS_DYNAMIC_INT32¶

enumerator DDS_DYNAMIC_INT64¶

enumerator DDS_DYNAMIC_UINT16¶

enumerator DDS_DYNAMIC_UINT32¶

enumerator DDS_DYNAMIC_UINT64¶

enumerator DDS_DYNAMIC_FLOAT32¶

enumerator DDS_DYNAMIC_FLOAT64¶

enumerator DDS_DYNAMIC_FLOAT128¶

enumerator DDS_DYNAMIC_INT8¶

enumerator DDS_DYNAMIC_UINT8¶

enumerator DDS_DYNAMIC_CHAR8¶

enumerator DDS_DYNAMIC_CHAR16¶

enumerator DDS_DYNAMIC_STRING8¶

enumerator DDS_DYNAMIC_STRING16¶

enumerator DDS_DYNAMIC_ENUMERATION¶

enumerator DDS_DYNAMIC_BITMASK¶

enumerator DDS_DYNAMIC_ALIAS¶

enumerator DDS_DYNAMIC_ARRAY¶

enumerator DDS_DYNAMIC_SEQUENCE¶

enumerator DDS_DYNAMIC_MAP¶

enumerator DDS_DYNAMIC_STRUCTURE¶

enumerator DDS_DYNAMIC_UNION¶

enumerator DDS_DYNAMIC_BITSET¶

enum dds_dynamic_type_spec_kind¶

Dynamic Type specification kind

Values:

enumerator DDS_DYNAMIC_TYPE_KIND_UNSET¶

enumerator DDS_DYNAMIC_TYPE_KIND_DEFINITION¶

enumerator DDS_DYNAMIC_TYPE_KIND_PRIMITIVE¶

enum dds_dynamic_type_extensibility¶

Dynamic Type extensibility

Values:

enumerator DDS_DYNAMIC_TYPE_EXT_FINAL¶

enumerator DDS_DYNAMIC_TYPE_EXT_APPENDABLE¶

enumerator DDS_DYNAMIC_TYPE_EXT_MUTABLE¶

enum dds_dynamic_type_autoid¶

Dynamic Type automatic member ID kind

Values:

enumerator DDS_DYNAMIC_TYPE_AUTOID_SEQUENTIAL¶: The member ID are assigned sequential

enumerator DDS_DYNAMIC_TYPE_AUTOID_HASH¶: The member ID is the hash of the member’s name

Functions

dds_dynamic_type_t dds_dynamic_type_create(dds_entity_t entity, dds_dynamic_type_descriptor_t descriptor)¶

Create a new Dynamic Type

Creates a new Dynamic Type, using the properties that are set in the type descriptor. In case these properties include a base-type, element-type or discriminator type, the ownership of these types is transferred to the newly created type.

Parameters

entity – [in] A DDS entity (any entity, except the pseudo root entity identified by DDS_CYCLONEDDS_HANDLE). This entity is used to get the type library of the entity’s domain, to add the type to.
descriptor – [in] The Dynamic Type descriptor.

Return values

DDS_RETCODE_OK – The type is created successfully.
DDS_RETCODE_BAD_PARAMETER – One or more of the provided parameters are invalid.
DDS_RETCODE_UNSUPPORTED – The provided type kind is not supported.
DDS_RETCODE_OUT_OF_RESOURCES – Not enough resources to create the type.

Returns

dds_dynamic_type_t A Dynamic Type reference for the created type.

dds_return_t dds_dynamic_type_set_extensibility(dds_dynamic_type_t *type, enum dds_dynamic_type_extensibility extensibility)¶

Set the extensibility of a Dynamic Type.

Parameters

type – [inout] Dynamic Type to set the extensibility for. This can be a structure, union, bitmask or enum type. This type must be in the CONSTRUCTING state and have no members added.
extensibility – [in] The extensibility to set (dds_dynamic_type_extensibility).

Return values

DDS_RETCODE_OK – The extensibility is set successfully.
DDS_RETCODE_BAD_PARAMETER – One or more of the provided parameters are invalid.
DDS_RETCODE_PRECONDITION_NOT_MET – The provided type is not in the CONSTRUCTING state.

Returns

dds_return_t Return code. In case of an error, the return code field in the provided type is also set to this value.

dds_return_t dds_dynamic_type_set_bit_bound(dds_dynamic_type_t *type, uint16_t bit_bound)¶

Set the bit-bound of a Dynamic Type.

Parameters

type – [inout] Dynamic Type to set the bit-bound for. This can be a bitmask or enum type.
bit_bound – [in] The bit-bound value to set, in the (including) range 1..32 for enum and 1..64 for bitmask.

Return values

DDS_RETCODE_OK – The bit-bound is set successfully.
DDS_RETCODE_BAD_PARAMETER – One or more of the provided parameters are invalid.
DDS_RETCODE_PRECONDITION_NOT_MET – The provided type is not in the CONSTRUCTING state.

Returns

dds_return_t Return code. In case of an error, the return code field in the provided type is also set to this value.

dds_return_t dds_dynamic_type_set_nested(dds_dynamic_type_t *type, bool is_nested)¶

Set the nested flag of a Dynamic Type.

Parameters

type – [inout] Dynamic Type to set the nested flag for. This can be a structure or union type.
is_nested – [in] Whether the nested flag is set.

Return values

DDS_RETCODE_OK – The flag is set successfully.
DDS_RETCODE_BAD_PARAMETER – One or more of the provided parameters are invalid.
DDS_RETCODE_PRECONDITION_NOT_MET – The provided type is not in the CONSTRUCTING state.

Returns

dds_return_t Return code. In case of an error, the return code field in the provided type is also set to this value.

dds_return_t dds_dynamic_type_set_autoid(dds_dynamic_type_t *type, enum dds_dynamic_type_autoid value)¶

Set the auto-id kind of a Dynamic Type.

Parameters

type – [inout] Dynamic Type to set the auto-id kind for. This can be a structure or union type.
value – [in] The auto-id kind, see dds_dynamic_type_autoid.

Return values

DDS_RETCODE_OK – The value is set successfully.
DDS_RETCODE_BAD_PARAMETER – One or more of the provided parameters are invalid.
DDS_RETCODE_PRECONDITION_NOT_MET – The provided type is not in the CONSTRUCTING state.

Returns

dds_return_t Return code. In case of an error, the return code field in the provided type is also set to this value.

dds_return_t dds_dynamic_type_add_member(dds_dynamic_type_t *type, dds_dynamic_member_descriptor_t member_descriptor)¶

Add a member to a Dynamic Type

This function is used to add a member to a Dynamic Type. The parent type can be a structure, union, enumeration or bitmask type. The parent type the member is added to takes over the ownership of the member type and dereferences the member type when it is deleted. (.

See also

dds_dynamic_type_ref for re-using a type)

See also

dds_dynamic_member_descriptor.

Parameters

type – [inout] The Dynamic type to add the member to.
member_descriptor – [in] The member descriptor that has the properties of the member to add,

Return values

DDS_RETCODE_OK – The member is added successfully.
DDS_RETCODE_BAD_PARAMETER – One or more of the provided parameters are invalid.
DDS_RETCODE_PRECONDITION_NOT_MET – The provided type (non the member type) is not in the CONSTRUCTING state.

Returns

dds_return_t Return code. In case of an error, the return code field in the provided type is also set to this value.

dds_return_t dds_dynamic_type_add_enum_literal(dds_dynamic_type_t *type, const char *name, dds_dynamic_enum_literal_value_t value, bool is_default)¶

Add a literal to a Dynamic Enum Type

This function is used to add a literal to a Dynamic Enum Type.

See also

dds_dynamic_enum_literal_value).

Parameters

type – [inout] The Dynamic enum type to add the member to.
name – [in] The name of the literal to add.
value – [in] The value for the literal (
is_default – [in] Indicates if the literal if default for the enum.

Return values

DDS_RETCODE_OK – The member is added successfully
DDS_RETCODE_BAD_PARAMETER – One or more of the provided parameters are invalid.
DDS_RETCODE_PRECONDITION_NOT_MET – The provided type is not in the CONSTRUCTING state.

Returns

dds_return_t Return code. In case of an error, the return code field in the provided type is also set to this value.

dds_return_t dds_dynamic_type_add_bitmask_field(dds_dynamic_type_t *type, const char *name, uint16_t position)¶

Add a field to a Dynamic bitmask Type

This function is used to add a field to a Dynamic bitmask Type.

See also

DDS_DYNAMIC_BITMASK_POSITION_AUTO).

Parameters

type – [inout] The Dynamic bitmask type to add the field to.
name – [in] The name of the field to add.
position – [in] The position for the field (

Return values

DDS_RETCODE_OK – The member is added successfully
DDS_RETCODE_BAD_PARAMETER – One or more of the provided parameters are invalid.
DDS_RETCODE_PRECONDITION_NOT_MET – The provided type is not in the CONSTRUCTING state.

Returns

dds_return_t Return code. In case of an error, the return code field in the provided type is also set to this value.

dds_return_t dds_dynamic_member_set_key(dds_dynamic_type_t *type, uint32_t member_id, bool is_key)¶

Set the key flag for a Dynamic Type member.

Parameters

type – [inout] Dynamic Type that contains the member to set the key flag for (must be a structure type).
member_id – [in] The ID of the member to set the flag for.
is_key – [in] Indicates whether the key flag should be set or cleared.

Return values

DDS_RETCODE_OK – The flag is updated successfully.
DDS_RETCODE_BAD_PARAMETER – One or more of the provided parameters are invalid.
DDS_RETCODE_PRECONDITION_NOT_MET – The provided type is not in the CONSTRUCTING state.

Returns

dds_return_t Return code. In case of an error, the return code field in the provided type is also set to this value.

dds_return_t dds_dynamic_member_set_optional(dds_dynamic_type_t *type, uint32_t member_id, bool is_optional)¶

Set the optional flag for a Dynamic Type member.

Parameters

type – [inout] Dynamic Type that contains the member to set the optional flag for (must be a structure type).
member_id – [in] The ID of the member to set the flag for.
is_optional – [in] Indicates whether the optional flag should be set or cleared.

Return values

DDS_RETCODE_OK – The flag is updated successfully.
DDS_RETCODE_BAD_PARAMETER – One or more of the provided parameters are invalid.
DDS_RETCODE_PRECONDITION_NOT_MET – The provided type is not in the CONSTRUCTING state.

Returns

dds_return_t Return code. In case of an error, the return code field in the provided type is also set to this value.

dds_return_t dds_dynamic_member_set_external(dds_dynamic_type_t *type, uint32_t member_id, bool is_external)¶

Set the external flag for a Dynamic Type member.

Parameters

type – [inout] Dynamic Type that contains the member to set the external flag for (must be a structure or union type).
member_id – [in] The ID of the member to set the flag for.
is_external – [in] Indicates whether the external flag should be set or cleared.

Return values

DDS_RETCODE_OK – The flag is updated successfully.
DDS_RETCODE_BAD_PARAMETER – One or more of the provided parameters are invalid.
DDS_RETCODE_PRECONDITION_NOT_MET – The provided type is not in the CONSTRUCTING state.

Returns

dds_return_t Return code. In case of an error, the return code field in the provided type is also set to this value.

dds_return_t dds_dynamic_member_set_hashid(dds_dynamic_type_t *type, uint32_t member_id, const char *hash_member_name)¶

Set the hash ID flag and hash field name for a Dynamic Type member.

Parameters

type – [inout] Dynamic Type that contains the member to set the flag and hash-name for (must be a structure or union type).
member_id – [in] The ID of the member to set the flag and hash-name for.
hash_member_name – [in] The hash-name that should be used for calculating the member ID.

Return values

DDS_RETCODE_OK – The flag is updated successfully.
DDS_RETCODE_BAD_PARAMETER – One or more of the provided parameters are invalid.
DDS_RETCODE_PRECONDITION_NOT_MET – The provided type is not in the CONSTRUCTING state.

Returns

dds_return_t Return code. In case of an error, the return code field in the provided type is also set to this value.

dds_return_t dds_dynamic_member_set_must_understand(dds_dynamic_type_t *type, uint32_t member_id, bool is_must_understand)¶

Set the must-understand flag for a Dynamic Type member.

Parameters

type – [inout] Dynamic Type that contains the member to set the must-understand flag for (must be a structure type).
member_id – [in] The ID of the member to set the flag for.
is_must_understand – [in] Indicates whether the must-understand flag should be set or cleared.

Return values

DDS_RETCODE_OK – The flag is updated successfully.
DDS_RETCODE_BAD_PARAMETER – One or more of the provided parameters are invalid.
DDS_RETCODE_PRECONDITION_NOT_MET – The provided type is not in the CONSTRUCTING state.

Returns

dds_return_t Return code. In case of an error, the return code field in the provided type is also set to this value.

dds_return_t dds_dynamic_type_register(dds_dynamic_type_t *type, struct ddsi_typeinfo **type_info)¶

Registers a Dynamic Type

This function registers a dynamic type, making it immutable and finalizing its definition. A type that is registered, get the state ‘RESOLVED’ and is stored in the type library.

Parameters

type – [in] A pointer to the dynamic type to be registered.
type_info – [out] A pointer to a pointer to a ddsi_typeinfo structure that holds information about the registered type.

Return values

DDS_RETCODE_OK – The type was successfully registered.
DDS_RETCODE_BAD_PARAMETER – One or more of the provided parameters are invalid.
DDS_RETCODE_PRECONDITION_NOT_MET – The provided type is not in the CONSTRUCTING state.
DDS_RETCODE_OUT_OF_RESOURCES – Not enough resources to create the type.

Returns

dds_return_t Return code.

dds_dynamic_type_t dds_dynamic_type_ref(dds_dynamic_type_t *type)¶

Reference a Dynamic Type

References a Dynamic Type and increases the ref-count of the type. This can e.g. be used to re-use a subtype when constructing a type.

Parameters

type – Dynamic Type to reference

Returns

dds_dynamic_type_t Dynamic Type with increased ref-count

dds_dynamic_type_t dds_dynamic_type_dup(const dds_dynamic_type_t *src)¶

Duplicate a Dynamic Type

Duplicates a Dynamic Type. Dependencies of the type are not duplicated, but their ref-count is increased.

Parameters

src – The type to duplicate.

Returns

dds_dynamic_type_t A duplicate of the source type.

struct dds_dynamic_type¶

#include <dds_public_dynamic_type.h>

Dynamic Type.

Representation of a dynamically created type. This struct has an opaque pointer to the type in the type system. During construction of the type (setting properties and adding members), the internal type has the state ‘CONSTRUCTION’. Once the type is registered, the state is updated to ‘RESOLVED’ and the type cannot be modified.

The ‘ret’ member of this struct holds the return code of operations performed on this type. In case this value is not DDS_RETCODE_OK, the type cannot be used for further processing (e.g. adding members, registering the type, etc.).

struct dds_dynamic_type_spec¶: #include <dds_public_dynamic_type.h>

Dynamic Type specification: a reference to dynamic type, which can be a primitive type kind (just the type kind enumeration value), or a (primitive or non-primitive) dynamic type reference.

struct dds_dynamic_type_descriptor¶

#include <dds_public_dynamic_type.h>

Dynamic Type descriptor.

Structure that holds the properties for creating a Dynamic Type. For each type kind, specific member fields are applicable and/or required.

Public Members

dds_dynamic_type_kind_t kind¶: Type kind. Required for all types.

const char *name¶: Type name. Required for struct, union, alias, enum, bitmask, array, sequence.

dds_dynamic_type_spec_t base_type¶: Option base type for a struct, or (required) aliased type in case of an alias type.

dds_dynamic_type_spec_t discriminator_type¶: Discriminator type for a union (required).

uint32_t num_bounds¶: Number of bounds for array and sequence types. In case of sequence, this can be 0 (unbounded) or 1.

const uint32_t *bounds¶: Bounds for array (0..num_bounds) and sequence (single value)

dds_dynamic_type_spec_t element_type¶: Element type for array and sequence, required.

dds_dynamic_type_spec_t key_element_type¶: Key element type for map type

struct dds_dynamic_member_descriptor¶

#include <dds_public_dynamic_type.h>

Dynamic Type Member descriptor.

Structure that holds the properities for adding a member to a dynamic type. Depending on the member type, different fields apply and are required.

Public Members

const char *name¶: Name of the member, required

uint32_t id¶: Identifier of the member, applicable for struct and union members. DDS_DYNAMIC_MEMBER_ID_AUTO can be used to indicate the next available id (current max + 1) should be used.

dds_dynamic_type_spec_t type¶: Member type, required for struct and union members.

char *default_value¶: Default value for the member

uint32_t index¶: Member index, applicable for struct and union members. DDS_DYNAMIC_MEMBER_INDEX_START and DDS_DYNAMIC_MEMBER_INDEX_END can be used to add a member as first or last member in the parent type.

uint32_t num_labels¶: Number of labels, required for union members in case not default_label

int32_t *labels¶: Labels for a union member, 1..n required for union members in case not default_label

bool default_label¶: Is default union member

struct dds_dynamic_enum_literal_value¶: #include <dds_public_dynamic_type.h>

Dynamic Enumeration type literal value kind and value. Can be set to NEXT_AVAIL to indicate that the current max value + 1 should be used for this member, or an explicit value can be provided.