RTI Connext C API  Version 5.1.0
User Data Type Support

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

FooFooTypeSupport_create_data ()
 <<eXtension>> Create a data type and initialize it.
 
FooFooTypeSupport_create_data_ex (DDS_Boolean allocatePointers)
 <<eXtension>> Create a data type and initialize it.
 
FooFooTypeSupport_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)
 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_Boolean DDS_InstanceHandle_equals (const DDS_InstanceHandle_t *self, const DDS_InstanceHandle_t *other)
 Compares this instance handle with another handle for equality.
 
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.
 

Detailed Description

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.

DDSUserDataSupport.png
Classes auto-created for an application data type named Foo

The macros defined here declare the strongly typed APIs needed to support an arbitrary user defined data of type Foo.

See Also
rtiddsgen

Macro Definition Documentation

#define DDS_TYPESUPPORT_C (   TTypeSupport,
  TData 
)

Declares the interface required to support a user data type.

Defines:
FooTypeSupport TypeSupport of type Foo, i.e. FooTypeSupport
#define DDS_DATAWRITER_C (   TDataWriter,
  TData 
)

Declares the interface required to support a user data type specific data writer.

Uses:
FooTypeSupport user data type, Foo
Defines:
FooDataWriter DDS_DataWriter of type Foo, i.e. FooDataWriter
#define DDS_DATAREADER_C (   TDataReader,
  TDataSeq,
  TData 
)

Declares the interface required to support a user data type-specific data reader.

Uses:
FooTypeSupport user data type, Foo FooSeq sequence of user data type, sequence<::Foo>
Defines:
FooDataReader DDS_DataReader of type Foo, i.e. FooDataReader
See Also
FooSeq

Typedef Documentation

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.

See Also
FooDataWriter_register_instance
DDS_SampleInfo::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.

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.

See Also
FooTypeSupport
rtiddsgen

Function Documentation

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.

Returns
Newly created data type, or NULL on failure.
See Also
FooTypeSupport_delete_data
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.

Parameters
allocatePointers<<in>> Whether or not to recursively allocate pointers.
Returns
Newly created data type, or NULL on failure.
See Also
FooTypeSupport_delete_data_ex
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.

Parameters
alloc_params<<in>> Whether or not to recursively allocate pointers and/or optional members
Returns
Newly created data type, or NULL on failure.
See Also
FooTypeSupport_delete_data_ex
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.

Parameters
dst_data<<inout>> Data type to copy value to. Cannot be NULL.
src_data<<in>> Data type to copy value from. Cannot be NULL.
Returns
One of the Standard Return Codes
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.

Parameters
a_data<<in>> Cannot be NULL.
Returns
One of the Standard Return Codes
See Also
FooTypeSupport_create_data
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.

Parameters
a_data<<in>> Cannot be NULL.
deletePointers<<in>> Whether or not to destroy pointers.
Returns
One of the Standard Return Codes
See Also
FooTypeSupport_create_data_ex
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.

Parameters
a_data<<in>> Cannot be NULL.
dealloc_params<<in>> Whether or not to destroy pointers and/or optional members.
Returns
One of the Standard Return Codes
See Also
FooTypeSupport_create_data_ex
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.

Parameters
a_data<<inout>> Cannot be NULL.
Returns
One of the Standard Return Codes
See Also
FooTypeSupport_finalize_data
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.

When allocatePointers is DDS_BOOLEAN_TRUE, all the references (pointers) in the type are recursively allocated.

Parameters
a_data<<inout>> Cannot be NULL.
allocatePointers<<in>> Whether or not to recursively allocate pointers.
Returns
One of the Standard Return Codes
See Also
FooTypeSupport_finalize_data_ex
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.

Parameters
a_data<<in>> Cannot be NULL.
Returns
One of the Standard Return Codes
See Also
FooTypeSupport_initialize_data
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.

Parameters
a_data<<in>> Cannot be NULL.
deletePointers<<in>> Whether or not to free memory allocated by the pointers.
Returns
One of the Standard Return Codes
See Also
FooTypeSupport_initialize_data_ex
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

Returns
default name for this type
See Also
FooTypeSupport_register_type
DDS_DomainParticipant_create_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 by the operation fails with DDS_RETCODE_OK.

Precondition
Cannot use the same 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.
Parameters
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.
Returns
One of the Standard Return Codes, DDS_RETCODE_PRECONDITION_NOT_MET or DDS_RETCODE_OUT_OF_RESOURCES.
MT Safety:
UNSAFE on the FIRST call. It is not safe for two threads to simultaneously make the first call to register a type. Subsequent calls are thread safe.
See Also
DDS_DomainParticipant_create_topic
DDS_ReturnCode_t FooTypeSupport_unregister_type ( DDS_DomainParticipant participant,
const char *  type_name 
)

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.

Precondition
A type with type_name is registered with the participant and all DDS_Topic objects referencing the type have been destroyed. If the type is not registered with the participant, or if any DDS_Topic is associated with the type, the operation will fail with DDS_RETCODE_ERROR.
Postcondition
All information about the type is removed from RTI Connext. No further communication using this type is possible.
Parameters
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.
Returns
One of the Standard Return Codes, DDS_RETCODE_BAD_PARAMETER or DDS_RETCODE_ERROR
MT Safety:
SAFE.
See Also
FooTypeSupport_register_type
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.

Parameters
a_data<<in>> Data type to be printed.
DDS_Boolean DDS_InstanceHandle_equals ( const DDS_InstanceHandle_t self,
const DDS_InstanceHandle_t other 
)

Compares this instance handle with another handle for equality.

Parameters
self<<in>> This handle. Cannot be NULL.
other<<in>> The other handle to be compared with this handle. Cannot be NULL.
Returns
DDS_BOOLEAN_TRUE if the two handles have equal values, or DDS_BOOLEAN_FALSE otherwise.
See Also
DDS_InstanceHandle_is_nil
DDS_Boolean DDS_InstanceHandle_is_nil ( const DDS_InstanceHandle_t self)

Compare this handle to DDS_HANDLE_NIL.

Returns
DDS_BOOLEAN_TRUE if the given instance handle is equal to DDS_HANDLE_NIL or DDS_BOOLEAN_FALSE otherwise.
See Also
DDS_InstanceHandle_equals

Variable Documentation

const DDS_InstanceHandle_t DDS_HANDLE_NIL

The NIL instance handle.

Special DDS_InstanceHandle_t value

See Also
DDS_InstanceHandle_is_nil
Examples:
HelloWorld_publisher.c.

RTI Connext C API Version 5.1.0 Copyright © Mon Feb 3 2014 Real-Time Innovations, Inc