Defines generic classes and macros to support user data types. More...

Data Structures
struct	FooTypeSupport
	<<interface>> <<generic>> User data type specific interface. More...

Macros
#define	DDS_TYPESUPPORT_C(TTypeSupport, TData)
	Declares the interface required to support a user data type.

Typedefs
typedef DDS_HANDLE_TYPE_NATIVE	DDS_InstanceHandle_t
	Type definition for an instance handle.

Functions
Foo *	FooTypeSupport_create_data (void)
	<<cert>> <<eXtension>> Create a data type and initialize it.
void	FooTypeSupport_delete_data (Foo *sample)
	<<eXtension>> Destroy a user data type instance.
DDS_ReturnCode_t	FooTypeSupport_register_type (DDS_DomainParticipant participant, const char type_name)
	<<cert>> Allows an application to communicate to RTI Connext Micro 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 Micro. After calling unregister_type, no further communication using that type is possible.
DDS_Boolean	DDS_InstanceHandle_equals (const DDS_InstanceHandle_t self, const DDS_InstanceHandle_t other)
	<<cert>> Compares this instance handle with another handle for equality.
DDS_Boolean	DDS_InstanceHandle_is_nil (const DDS_InstanceHandle_t *self)
	<<cert>> Compare this handle to DDS_HANDLE_NIL

Variables
const DDS_InstanceHandle_t	DDS_HANDLE_NIL
	<<cert>> The NIL instance handle.

Detailed Description

Defines generic classes and macros to support user data types.

Defines the DDS user data type support.

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 Micro.

RTI Connext Micro provides an automatic means to generate all these type-specific classes with the RTI IDL Compiler User Manual utility. The complete set of automatic classes created for a hypothetical user data type named Foo are shown below.

"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.

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

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

Function Documentation

Foo* FooTypeSupport_create_data ( void )

<<cert>> <<eXtension>> Create a data type and initialize it.

Memory for a data type is allocated from memory using internal RTI Connext Micro memory allocation and deallocation APIs. The implementation of these APIs are specific to a particular platform. For this reason it is of the utmost importance that FooTypeSupport_create_data is not called until DDS_DomainParticipantFactory_get_instance has been called successfully. The DDS_DomainParticipantFactory initializes the RTI Connext Micro system, including any memory management initialization.

The generated implementation of the operation knows how to instantiate a data type and initialize it properly.

All memory for the type is deeply allocated.

Returns:: newly created data type

MT Safety:: This operation is thread safe.

API Restriction:: This function must only be called after DDS_DomainParticipantFactory_get_instance.

See also:: FooTypeSupport_delete_data

void FooTypeSupport_delete_data ( Foo * sample )

<<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:

sample <<in>> Cannot be NULL.

Returns:: One of the Standard Return Codes

See also:: FooTypeSupport_create_data

DDS_ReturnCode_t FooTypeSupport_register_type	(	DDS_DomainParticipant *	participant,
		const char *	type_name
	)

<<cert>> Allows an application to communicate to RTI Connext Micro 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 Micro to distinguish different instances of the same type.

The same DDS_TYPESUPPORT_C 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_C 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_C 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:: This operation is thread safe. However, note that the arguments are not protected from being modified by other threads and must not be modified until the call returns.

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 Micro. 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 Micro. 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 Micro. 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:: DDS_DomainParticipant_register_type

DDS_Boolean DDS_InstanceHandle_equals	(	const DDS_InstanceHandle_t *	self,
		const DDS_InstanceHandle_t *	other
	)

<<cert>> 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.

MT Safety:: UNSAFE. This operation does not protect against the left or right side from being modified by another thread while the comparison is made.