User Data Type Support

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

Data Structures
struct	FooTypeSupport
	<<interface>> <<generic>> User data type specific interface. More...
struct	DDS_InstanceHandleSeq
	Instantiates FooSeq < DDS_InstanceHandle_t > . More...

Macros
#define	DDS_DATAWRITER_C(TDataWriter, TData)
	Declares the interface required to support a user data type specific data writer.
#define	DDS_TYPESUPPORT_C(TTypeSupport, TData)
	Declares the interface required to support a user data type.
#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.

Functions
Foo *	FooTypeSupport_create_data (void)
	<<eXtension>> Create a data type and initialize it.
DDS_ReturnCode_t	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)
	Allows an application to communicate to RTI Connext DDS 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 DDS Micro. After calling unregister_type, no further communication using that type is possible.
DDS_ReturnCode_t	FooTypeSupport_serialize_data_to_cdr_buffer_ex (char *buffer, unsigned int *length, const TData *a_data, DDS_DataRepresentationId_t representation)
	<<eXtension>> Serializes the input sample into a buffer of octets.
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 CDR buffer of octets.
DDS_ReturnCode_t	FooTypeSupport_deserialize_data_from_cdr_buffer (Foo *a_data, const char *buffer, unsigned int length)
	<<eXtension>> Deserializes a sample from a buffer of octets.
DDSCDllExport 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
DDSCDllVariable const DDS_InstanceHandle_t	DDS_HANDLE_NIL
	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 DDS Micro.

RTI Connext DDS 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

DDS_DATAWRITER_C

#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

DDS_TYPESUPPORT_C

#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

DDS_DATAREADER_C

#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

DDS_InstanceHandle_t

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

FooTypeSupport_create_data()

Foo * FooTypeSupport_create_data

(

void

)

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

All memory for the type is deeply allocated.

Returns

newly created data type

See also

FooTypeSupport_delete_data

FooTypeSupport_delete_data()

DDS_ReturnCode_t 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

FooTypeSupport_register_type()

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

Allows an application to communicate to RTI Connext DDS 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 DDS 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 return DDS_RETCODE_OK. A type must be registered and unregistered an equal number of times.

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

FooTypeSupport_unregister_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 DDS 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 DDS 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 DDS 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

FooTypeSupport_serialize_data_to_cdr_buffer_ex()

DDS_ReturnCode_t FooTypeSupport_serialize_data_to_cdr_buffer_ex	(	char *	buffer,
		unsigned int *	length,
		const TData *	a_data,
		DDS_DataRepresentationId_t	representation )

<<eXtension>> Serializes the input sample into a buffer of octets.

This function serializes a sample into a buffer of octets using the input data representation. See FooTypeSupport_serialize_data_to_cdr_buffer for details.

Parameters

a_data	<<in>>. Input sample. Cannot be NULL.
buffer	<<out>>. Serialization buffer.
length	<<inout>>. Serialization buffer length.
representation	<<in>>. Representation used to serialize the data.

Returns

One of the Standard Return Codes

FooTypeSupport_serialize_data_to_cdr_buffer()

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 CDR buffer of octets.

This function serializes a sample into a buffer of octets and it uses CDR as the data representation. Calling this function is equivalent to calling FooTypeSupport_serialize_data_to_cdr_buffer_ex with DDS_AUTO_DATA_REPRESENTATION as the 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.

Parameters

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.

Returns

One of the Standard Return Codes

FooTypeSupport_deserialize_data_from_cdr_buffer()

DDS_ReturnCode_t FooTypeSupport_deserialize_data_from_cdr_buffer	(	Foo *	a_data,
		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.

Parameters

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

Returns

One of the Standard Return Codes

DDS_InstanceHandle_equals()

DDSCDllExport 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_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

DDS_HANDLE_NIL

DDSCDllVariable const DDS_InstanceHandle_t DDS_HANDLE_NIL

extern

The NIL instance handle.

Special DDS_InstanceHandle_t value

See also

DDS_InstanceHandle_is_nil