RTI Connext C API
Version 5.3.0
|
Defines generic classes and macros to support user data types. More...
Data Structures | |
struct | DDS_TypeAllocationParams_t |
Configures whether or not to allocate pointer and optional members. More... | |
struct | DDS_TypeDeallocationParams_t |
Configures whether to release or not pointer and optional members. More... | |
struct | Foo |
A representative user-defined data type. More... | |
struct | FooTypeSupport |
<<interface>> <<generic>> User data type specific interface. More... | |
struct | DDS_InstanceHandleSeq |
Instantiates FooSeq < DDS_InstanceHandle_t > . More... | |
Macros | |
#define | DDS_TYPESUPPORT_C(TTypeSupport, TData) |
Declares the interface required to support a user data type. | |
#define | DDS_DATAWRITER_C(TDataWriter, TData) |
Declares the interface required to support a user data type specific data writer. | |
#define | DDS_DATAREADER_C(TDataReader, TDataSeq, TData) |
Declares the interface required to support a user data type-specific data reader. | |
Typedefs | |
typedef DDS_HANDLE_TYPE_NATIVE | DDS_InstanceHandle_t |
Type definition for an instance handle. | |
typedef struct DDS_TypeSupportImpl | DDS_TypeSupport |
<<interface>> An abstract marker interface that has to be specialized for each concrete user data type that will be used by the application. | |
Functions | |
Foo * | FooTypeSupport_create_data () |
<<extension>> Create a data type and initialize it. | |
Foo * | FooTypeSupport_create_data_ex (DDS_Boolean allocatePointers) |
<<extension>> Create a data type and initialize it. | |
Foo * | FooTypeSupport_create_data_w_params (const struct DDS_TypeAllocationParams_t *alloc_params) |
<<extension>> Create a data type and initialize it. | |
DDS_ReturnCode_t | FooTypeSupport_copy_data (Foo *dst_data, const Foo *src_data) |
<<extension>> Copy data type. | |
DDS_ReturnCode_t | FooTypeSupport_delete_data (Foo *a_data) |
<<extension>> Destroy a user data type instance. | |
DDS_ReturnCode_t | FooTypeSupport_delete_data_ex (Foo *a_data, DDS_Boolean deletePointers) |
<<extension>> Destroy a user data type instance. | |
DDS_ReturnCode_t | FooTypeSupport_delete_data_w_params (Foo *a_data, const struct DDS_TypeDeallocationParams_t *dealloc_params) |
<<extension>> Destroy a user data type instance. | |
DDS_ReturnCode_t | FooTypeSupport_initialize_data (Foo *a_data) |
<<extension>> Initialize data type. | |
DDS_ReturnCode_t | FooTypeSupport_initialize_data_ex (Foo *a_data, DDS_Boolean allocatePointers) |
<<extension>> Initialize data type. | |
DDS_ReturnCode_t | FooTypeSupport_finalize_data (Foo *a_data) |
<<extension>> Finalize data type. | |
DDS_ReturnCode_t | FooTypeSupport_finalize_data_ex (Foo *a_data, DDS_Boolean deletePointers) |
<<extension>> Finalize data type. | |
const char * | FooTypeSupport_get_type_name () |
Get the default name for this type. | |
DDS_ReturnCode_t | FooTypeSupport_register_type (DDS_DomainParticipant *participant, const char *type_name) |
Allows an application to communicate to RTI Connext the existence of a data type. | |
DDS_ReturnCode_t | FooTypeSupport_unregister_type (DDS_DomainParticipant *participant, const char *type_name) |
<<extension>> Allows an application to unregister a data type from RTI Connext. After calling unregister_type, no further communication using that type is possible. | |
void | FooTypeSupport_print_data (Foo *a_data) |
<<extension>> Print value of data type to standard out. | |
DDS_ReturnCode_t | FooTypeSupport_serialize_data_to_cdr_buffer (char *buffer, unsigned int *length, const Foo *a_data) |
<<extension>> Serializes the input sample into a buffer of octets. | |
DDS_ReturnCode_t | FooTypeSupport_deserialize_data_from_cdr_buffer (Foo *sample, const char *buffer, unsigned int length) |
<<extension>> Deserializes a sample from a buffer of octets. | |
DDS_ReturnCode_t | FooTypeSupport_data_to_string (Foo *sample, char *str, DDS_UnsignedLong *str_size, const DDS_PrintFormatProperty *property) |
<<extension>> Transforms a data sample into a human-readable string representation. | |
DDS_TypeCode * | FooTypeSupport_get_typecode () |
<<extension>> Retrieves the TypeCode for the Type. | |
DDS_Boolean | DDS_InstanceHandle_equals (const DDS_InstanceHandle_t *self, const DDS_InstanceHandle_t *other) |
Compares this instance handle with another handle for equality. | |
int | DDS_InstanceHandle_compare (const DDS_InstanceHandle_t *self, const DDS_InstanceHandle_t *other) |
Compares this instance handle with another handle. | |
DDS_Boolean | DDS_InstanceHandle_is_nil (const DDS_InstanceHandle_t *self) |
Compare this handle to DDS_HANDLE_NIL. | |
Variables | |
const DDS_InstanceHandle_t | DDS_HANDLE_NIL |
The NIL instance handle. | |
Defines generic classes and macros to support user data types.
DDS specifies strongly typed interfaces to read and write user data. For each data class defined by the application, there is a number of specialised classes that are required to facilitate the type-safe interaction of the application with RTI Connext.
RTI Connext provides an automatic means to generate all these type-specific classes with the rtiddsgen utility. The complete set of automatic classes created for a hypothetical user data type named Foo
are shown below.
Foo
The macros defined here declare the strongly typed APIs needed to support an arbitrary user defined data of type Foo
.
#define DDS_TYPESUPPORT_C | ( | TTypeSupport, | |
TData | |||
) |
Declares the interface required to support a user data type.
Foo
, i.e. FooTypeSupport
#define DDS_DATAWRITER_C | ( | TDataWriter, | |
TData | |||
) |
Declares the interface required to support a user data type specific data writer.
Foo
Foo
, i.e. FooDataWriter
#define DDS_DATAREADER_C | ( | TDataReader, | |
TDataSeq, | |||
TData | |||
) |
Declares the interface required to support a user data type-specific data reader.
Foo
FooSeq sequence of user data type, sequence<::Foo>
Foo
, i.e. FooDataReader
typedef DDS_HANDLE_TYPE_NATIVE DDS_InstanceHandle_t |
Type definition for an instance handle.
Handle to identiy different instances of the same DDS_Topic of a certain type.
typedef struct DDS_TypeSupportImpl DDS_TypeSupport |
<<interface>> An abstract marker interface that has to be specialized for each concrete user data type that will be used by the application.
The implementation provides an automatic means to generate a type-specific class, FooTypeSupport, from a description of the type in IDL.
A DDS_TypeSupport must be registered using the FooTypeSupport_register_type operation on this type-specific class before it can be used to create DDS_Topic objects.
Foo* FooTypeSupport_create_data | ( | ) |
<<extension>> Create a data type and initialize it.
The generated implementation of the operation knows how to instantiate a data type and initialize it properly.
By default all memory for the type is deeply allocated, except for optional members.
Foo* FooTypeSupport_create_data_ex | ( | DDS_Boolean | allocatePointers | ) |
<<extension>> Create a data type and initialize it.
The generated implementation of the operation knows how to instantiate a data type and initialize it properly.
When allocatePointers
is DDS_BOOLEAN_TRUE, all the references (pointers) in the type are recursively allocated.
allocatePointers | <<in>> Whether or not to recursively allocate pointers. |
Foo* FooTypeSupport_create_data_w_params | ( | const struct DDS_TypeAllocationParams_t * | alloc_params | ) |
<<extension>> Create a data type and initialize it.
The generated implementation of the operation knows how to instantiate a data type and initialize it properly.
By default all memory for the type is deeply allocated, except for optional members.
alloc_params | <<in>> Whether or not to recursively allocate pointers and/or optional members |
DDS_ReturnCode_t FooTypeSupport_copy_data | ( | Foo * | dst_data, |
const Foo * | src_data | ||
) |
<<extension>> Copy data type.
The generated implementation of the operation knows how to copy value of a data type.
dst_data | <<inout>> Data type to copy value to. Cannot be NULL. |
src_data | <<in>> Data type to copy value from. Cannot be NULL. |
DDS_ReturnCode_t FooTypeSupport_delete_data | ( | Foo * | a_data | ) |
<<extension>> Destroy a user data type instance.
The generated implementation of the operation knows how to destroy a data type and return all resources.
a_data | <<in>> Cannot be NULL. |
DDS_ReturnCode_t FooTypeSupport_delete_data_ex | ( | Foo * | a_data, |
DDS_Boolean | deletePointers | ||
) |
<<extension>> Destroy a user data type instance.
The generated implementation of the operation knows how to destroy a data type and return all resources.
When deletePointers
is DDS_BOOLEAN_TRUE, all the references (pointers) are destroyed as well.
DDS_ReturnCode_t FooTypeSupport_delete_data_w_params | ( | Foo * | a_data, |
const struct DDS_TypeDeallocationParams_t * | dealloc_params | ||
) |
<<extension>> Destroy a user data type instance.
The generated implementation of the operation knows how to destroy a data type and return all resources.
By default, all non-NULL pointers and optional members are deleted.
a_data | <<in>> Cannot be NULL. |
dealloc_params | <<in>> Whether or not to destroy pointers and/or optional members. |
DDS_ReturnCode_t FooTypeSupport_initialize_data | ( | Foo * | a_data | ) |
<<extension>> Initialize data type.
The generated implementation of the operation knows how to initialize a data type. This function is typically called to initialize a data type that is allocated on the stack. Calling this function more than once will cause a memory leak.
a_data | <<inout>> Cannot be NULL. |
DDS_ReturnCode_t FooTypeSupport_initialize_data_ex | ( | Foo * | a_data, |
DDS_Boolean | allocatePointers | ||
) |
<<extension>> Initialize data type.
The generated implementation of the operation knows how to initialize a data type. This function is typically called to initialize a data type that is allocated on the stack. Calling this function more than once will cause a memory leak.
When allocatePointers
is DDS_BOOLEAN_TRUE, all the references (pointers) in the type are recursively allocated.
a_data | <<inout>> Cannot be NULL. |
allocatePointers | <<in>> Whether or not to recursively allocate pointers. |
DDS_ReturnCode_t FooTypeSupport_finalize_data | ( | Foo * | a_data | ) |
<<extension>> Finalize data type.
The generated implementation of the operation knows how to finalize a data type. This function is typically called to finalize a data type that has previouslly been initialized.
a_data | <<in>> Cannot be NULL. |
DDS_ReturnCode_t FooTypeSupport_finalize_data_ex | ( | Foo * | a_data, |
DDS_Boolean | deletePointers | ||
) |
<<extension>> Finalize data type.
The generated implementation of the operation knows how to finalize a data type. This function is typically called to finalize a data type that has previouslly been initialized.
When deletePointers
is DDS_BOOLEAN_TRUE, the memory required by the references (pointers) associated to the type is freed.
a_data | <<in>> Cannot be NULL. |
deletePointers | <<in>> Whether or not to free memory allocated by the pointers. |
const char* FooTypeSupport_get_type_name | ( | ) |
Get the default name for this type.
Can be used for calling FooTypeSupport_register_type or creating DDS_Topic
DDS_ReturnCode_t FooTypeSupport_register_type | ( | DDS_DomainParticipant * | participant, |
const char * | type_name | ||
) |
Allows an application to communicate to RTI Connext the existence of a data type.
The generated implementation of the operation embeds all the knowledge that has to be communicated to the middleware in order to make it able to manage the contents of data of that type. This includes in particular the key definition that will allow RTI Connext to distinguish different instances of the same type.
The same DDS_TypeSupport can be registered multiple times with a DDS_DomainParticipant using the same or different values for the type_name
. If register_type
is called multiple times on the same DDS_TypeSupport with the same DDS_DomainParticipant and type_name
, the second (and subsequent) registrations are ignored but the operation returns DDS_RETCODE_OK.
type_name
to register two different DDS_TypeSupport with the same DDS_DomainParticipant, or else the operation will fail and DDS_RETCODE_PRECONDITION_NOT_MET will be returned. participant | <<in>> the DDS_DomainParticipant to register the data type Foo with. Cannot be NULL. |
type_name | <<in>> the type name under with the data type Foo is registered with the participant; this type name is used when creating a new DDS_Topic. (See DDS_DomainParticipant_create_topic.) The name may not be NULL or longer than 255 characters. |
DDS_ReturnCode_t FooTypeSupport_unregister_type | ( | DDS_DomainParticipant * | participant, |
const char * | type_name | ||
) |
<<extension>> Allows an application to unregister a data type from RTI Connext. After calling unregister_type, no further communication using that type is possible.
The generated implementation of the operation removes all the information about a type from RTI Connext. No further communication using that type is possible.
type_name
is registered with the participant and all DDS_Topic objects referencing the type have been destroyed. If any DDS_Topic is associated with the type, the operation will fail with DDS_RETCODE_ERROR. participant | <<in>> the DDS_DomainParticipant to unregister the data type Foo from. Cannot be NULL. |
type_name | <<in>> the type name under with the data type Foo is registered with the participant. The name should match a name that has been previously used to register a type with the participant. Cannot be NULL. |
void FooTypeSupport_print_data | ( | Foo * | a_data | ) |
<<extension>> Print value of data type to standard out.
The generated implementation of the operation knows how to print value of a data type.
a_data | <<in>> Data type to be printed. |
DDS_ReturnCode_t FooTypeSupport_serialize_data_to_cdr_buffer | ( | char * | buffer, |
unsigned int * | length, | ||
const Foo * | a_data | ||
) |
<<extension>> Serializes the input sample into a buffer of octets.
This function serializes a sample into a buffer of octets and it uses CDR as the data representation.
The input buffer must be big enough to store the serialized representation of the sample. Otherwise, the function will return an error.
To determine the minimum size of the input buffer, the user must call this method with the buffer set to NULL.
a_data | <<in>>. Input sample. Cannot be NULL. |
buffer | <<out>>. Serialization buffer. |
length | <<inout>>. When buffer is set to NULL, after the function executes, length will contain a buffer size big enough to hold the serialized data. When buffer is not NULL, length must contain the size of the input buffer when the function is invoked. After the function executes, length will be updated to contain the actual size of the serialized content, which may be smaller than the size obtained when buffer is set to NULL. |
DDS_ReturnCode_t FooTypeSupport_deserialize_data_from_cdr_buffer | ( | Foo * | sample, |
const char * | buffer, | ||
unsigned int | length | ||
) |
<<extension>> Deserializes a sample from a buffer of octets.
This function deserializes a sample from a CDR buffer of octets.
The content of the buffer generated by the function FooTypeSupport_serialize_data_to_cdr_buffer can be provided to this function to get the sample back.
sample | <<in>>. Output sample. Cannot be NULL. |
buffer | <<in>>. Deserialization buffer. Cannot be NULL. |
length | <<in>>. Length of the serialized representation of the sample in the buffer. |
DDS_ReturnCode_t FooTypeSupport_data_to_string | ( | Foo * | sample, |
char * | str, | ||
DDS_UnsignedLong * | str_size, | ||
const DDS_PrintFormatProperty * | property | ||
) |
<<extension>> Transforms a data sample into a human-readable string representation.
This function takes a data sample and creates a string representation of the data.
The input character buffer must be big enough to store the string representation of the sample. Otherwise, the function will return an error.
To determine the minimum size of the input character buffer, the user must call this method with the buffer set to NULL.
If the size of the output string is longer than the size of an unsigned 32-bit integer, this operation will fail with DDS_RETCODE_OUT_OF_RESOURCES.
This method is only provided for types that were generated with typecodes.
sample | <<in>>. The sample to get the string representation for. Cannot be NULL. |
str | <<out>>. Output string representing the data sample. |
str_size | <<inout>>. When str is set to NULL, after the function executes, str_size will contain a buffer size big enough to hold the string representation of the data. When str is not NULL, str_size must contain the size of the input buffer when the function is invoked. If the size of the input buffer is too small, after the function executes, str_size will be updated to contain the required size of the string content and the function will return DDS_RETCODE_OUT_OF_RESOURCES. |
property | <<in>>. Properties describing what the format of the output string should be. |
DDS_TypeCode* FooTypeSupport_get_typecode | ( | ) |
<<extension>> Retrieves the TypeCode for the Type.
This function retrieves the DDS_TypeCode for the Type. A DDS_TypeCode is a mechanism for representing a type at runtime. RTI Connext can use type codes to send type definitions on the network. A DDS_TypeCode value consists of a type code kind (represented by the DDS_TCKind enumeration) and a list of members (that is, fields). These members are recursive: each one has its own DDS_TypeCode, and in the case of complex types (structures, arrays, and so on), these contained type codes contain their own members.
DDS_Boolean DDS_InstanceHandle_equals | ( | const DDS_InstanceHandle_t * | self, |
const DDS_InstanceHandle_t * | other | ||
) |
Compares this instance handle with another handle for equality.
self | <<in>> This handle. Cannot be NULL. |
other | <<in>> The other handle to be compared with this handle. Cannot be NULL. |
int DDS_InstanceHandle_compare | ( | const DDS_InstanceHandle_t * | self, |
const DDS_InstanceHandle_t * | other | ||
) |
Compares this instance handle with another handle.
self | <<in>> This handle. Cannot be NULL. |
other | <<in>> The other handle to be compared with this handle. Cannot be NULL. |
DDS_Boolean DDS_InstanceHandle_is_nil | ( | const DDS_InstanceHandle_t * | self | ) |
Compare this handle to DDS_HANDLE_NIL.
const DDS_InstanceHandle_t DDS_HANDLE_NIL |
The NIL instance handle.
Special DDS_InstanceHandle_t value