RTI Connext Micro C API Version 4.2.0
Loading...
Searching...
No Matches
Topic

DDS_Topic entity and associated elements More...

Data Structures

struct  DDS_InconsistentTopicStatus
 DDS_INCONSISTENT_TOPIC_STATUS More...
 
struct  DDS_TopicQos
 QoS policies supported by a DDS_Topic entity. More...
 
struct  DDS_TopicListener
 <<interface>> DDS_Listener for DDS_Topic entities. More...
 

Macros

#define DDS_InconsistentTopicStatus_INITIALIZER
 <<cert>> Initializer for new status instances.
 
#define DDS_TopicQos_INITIALIZER
 <<cert>> Initializer for new QoS instances.
 
#define DDS_TopicListener_INITIALIZER
 <<cert>> Initializer for new DDS_TopicListener.
 

Typedefs

typedef struct DDS_TopicDescriptionImpl DDS_TopicDescription
 <<interface>> Base class for DDS_Topic.
 
typedef struct DDS_TopicImpl DDS_Topic
 <<interface>> The most basic description of the data to be published and subscribed.
 
typedef void(* DDS_TopicListener_InconsistentTopicCallback) (void *listener_data, DDS_Topic *topic, const struct DDS_InconsistentTopicStatus *status)
 Prototype of DDS_TopicListener::on_inconsistent_topic.
 

Functions

DDSCDllExport DDS_ReturnCode_t DDS_TopicQos_initialize (struct DDS_TopicQos *self)
 Initializer for new QoS instances.
 
DDSCDllExport DDS_ReturnCode_t DDS_TopicQos_copy (struct DDS_TopicQos *self, const struct DDS_TopicQos *source)
 Copy the contents of the given QoS into this QoS.
 
DDSCDllExport DDS_ReturnCode_t DDS_TopicQos_finalize (struct DDS_TopicQos *self)
 Free any dynamic memory allocated by the policies in this DDS_TopicQos.
 
DDSCDllExport const char * DDS_TopicDescription_get_type_name (DDS_TopicDescription *self)
 <<cert>> Get the associated type_name.
 
DDSCDllExport const char * DDS_TopicDescription_get_name (DDS_TopicDescription *self)
 <<cert>> Get the name used to create this DDS_TopicDescription .
 
DDSCDllExport DDS_DomainParticipantDDS_TopicDescription_get_participant (DDS_TopicDescription *self)
 <<cert>> Get the DDS_DomainParticipant to which the DDS_TopicDescription belongs.
 
DDSCDllExport DDS_EntityDDS_Topic_as_entity (DDS_Topic *self)
 <<cert>> Access a DDS_Topic's DDS_Entity supertype instance.
 
DDSCDllExport DDS_TopicDescriptionDDS_Topic_as_topicdescription (DDS_Topic *self)
 <<cert>> Access a DDS_Topic's DDS_TopicDescription supertype instance.
 
DDSCDllExport DDS_TopicDDS_Topic_narrow (DDS_TopicDescription *self)
 <<cert>> Narrow the given DDS_TopicDescription pointer to a DDS_Topic pointer.
 
DDSCDllExport DDS_ReturnCode_t DDS_Topic_get_inconsistent_topic_status (DDS_Topic *self, struct DDS_InconsistentTopicStatus *status)
 <<cert>> Allows the application to retrieve the DDS_INCONSISTENT_TOPIC_STATUS status of a DDS_Topic.
 
DDSCDllExport DDS_ReturnCode_t DDS_Topic_set_qos (DDS_Topic *self, const struct DDS_TopicQos *qos)
 Set the topic QoS.
 
DDSCDllExport DDS_ReturnCode_t DDS_Topic_get_qos (DDS_Topic *self, struct DDS_TopicQos *qos)
 Get the topic QoS.
 
DDSCDllExport DDS_ReturnCode_t DDS_Topic_set_listener (DDS_Topic *self, const struct DDS_TopicListener *listener, DDS_StatusMask mask)
 Set the topic listener.
 
DDSCDllExport struct DDS_TopicListener DDS_Topic_get_listener (DDS_Topic *self)
 Get the topic listener.
 

Detailed Description

DDS_Topic entity and associated elements

Macro Definition Documentation

◆ DDS_InconsistentTopicStatus_INITIALIZER

#define DDS_InconsistentTopicStatus_INITIALIZER

<<cert>> Initializer for new status instances.

New DDS_InconsistentTopicStatus instances that are stored on the stack should be initialized with this value before they are passed to any function. This step ensures that those fields that use dynamic memory are properly initialized. This does not allocate memory.

The simplest way to create a status structure is to initialize it on the stack at the time of its creation.

◆ DDS_TopicQos_INITIALIZER

#define DDS_TopicQos_INITIALIZER

<<cert>> Initializer for new QoS instances.

New DDS_TopicQos instances stored on the stack should be initialized with this value before they are passed to any function. This step ensures that those contained QoS policies that use dynamic memory are properly initialized. This does not allocate memory.

The simplest way to create a new QoS structure is to initialize it on the stack at the time of its creation:

#define DDS_TopicQos_INITIALIZER
<<cert>> Initializer for new QoS instances.
Definition dds_c_topic.h:165
QoS policies supported by a DDS_Topic entity.
Definition dds_c_topic.h:115
See also
DDS_TopicQos_finalize

◆ DDS_TopicListener_INITIALIZER

#define DDS_TopicListener_INITIALIZER

<<cert>> Initializer for new DDS_TopicListener.

All the new DDS_TopicListener instances allocated in the stack should be initialized to this value.No memory is allocated.

/* initialize listener functions */
listener.on_inconsistent_topic = ....;
DDS_Topic_set_listener(myTopic, &listener, mask);
DDSCDllExport DDS_ReturnCode_t DDS_Topic_set_listener(DDS_Topic *self, const struct DDS_TopicListener *listener, DDS_StatusMask mask)
Set the topic listener.
#define DDS_TopicListener_INITIALIZER
<<cert>> Initializer for new DDS_TopicListener.
Definition dds_c_topic.h:224
<<interface>> DDS_Listener for DDS_Topic entities.
Definition dds_c_topic.h:212
DDS_TopicListener_InconsistentTopicCallback on_inconsistent_topic
Handle the DDS_INCONSISTENT_TOPIC_STATUS status.
Definition dds_c_topic.h:219
See also
DDS_TopicListener

Typedef Documentation

◆ DDS_TopicDescription

typedef struct DDS_TopicDescriptionImpl DDS_TopicDescription

<<interface>> Base class for DDS_Topic.

DDS_TopicDescription represents the fact that both publications and subscriptions are tied to a single data-type. Its attribute type_name defines a unique resulting type for the publication or the subscription and therefore creates an implicit association with a type.

DDS_TopicDescription has also a name that allows it to be retrieved locally.

◆ DDS_Topic

typedef struct DDS_TopicImpl DDS_Topic

<<interface>> The most basic description of the data to be published and subscribed.

QoS:
DDS_TopicQos
Status:
DDS_INCONSISTENT_TOPIC_STATUS, DDS_InconsistentTopicStatus
Listener:
DDS_TopicListener

A DDS_Topic is identified by its name, which must be unique in the whole domain. In addition (by virtue of extending DDS_TopicDescription) it fully specifies the type of the data that can be communicated when publishing or subscribing to the DDS_Topic.

DDS_Topic is the only DDS_TopicDescription that can be used for publications and therefore associated with a DDS_DataWriter.

The following operations may be called even if the DDS_Topic is not enabled. Other operations will fail with the value DDS_RETCODE_NOT_ENABLED if called on a disabled DDS_Topic:

  • get_inconsistent_topic_status()

◆ DDS_TopicListener_InconsistentTopicCallback

typedef void(* DDS_TopicListener_InconsistentTopicCallback) (void *listener_data, DDS_Topic *topic, const struct DDS_InconsistentTopicStatus *status)

Prototype of DDS_TopicListener::on_inconsistent_topic.

Parameters
listener_data<<out>> Data associated with the listener when the listener is set
topic<<out>> Locally created DDS_Topic that triggers the listener callback
status<<out>> Current inconsistent status of the locally created DDS_Topic

Function Documentation

◆ DDS_TopicQos_initialize()

DDSCDllExport DDS_ReturnCode_t DDS_TopicQos_initialize ( struct DDS_TopicQos * self)

Initializer for new QoS instances.

New DDS_TopicQos on the heap should be initialized with this function before they are passed to any function. This step ensures that those contained QoS policies that use dynamic memory are properly initialized. This function does not allocate memory.

Parameters
self<<in>> Cannot be NULL.
Returns
One of the Standard Return Codes
See also
DDS_TopicQos_INITIALIZER
DDS_TopicQos_finalize

◆ DDS_TopicQos_copy()

DDSCDllExport DDS_ReturnCode_t DDS_TopicQos_copy ( struct DDS_TopicQos * self,
const struct DDS_TopicQos * source )

Copy the contents of the given QoS into this QoS.

DDS_TopicQos instances can use dynamic memory because of the sequences contained in some QoS policies. A shallow copy by assignment is therefore unsafe. This function performs a deep-copy, allocating memory if necessary.

Parameters
self<<in>> Cannot be NULL.
source<<in>>. QoS to be copied from.
Returns
One of the Standard Return Codes
See also
DDS_TopicQos_INITIALIZER
DDS_TopicQos_initialize
DDS_TopicQos_finalize

◆ DDS_TopicQos_finalize()

DDSCDllExport DDS_ReturnCode_t DDS_TopicQos_finalize ( struct DDS_TopicQos * self)

Free any dynamic memory allocated by the policies in this DDS_TopicQos.

Some QoS policies may use dynamic memory (regardless of whether the QoS itself is in dynamic memory). This function frees that memory but otherwise leaves this QoS unchanged. It should be called on all instances before they are freed (or, in the case of stack-based instances, before they go out of scope).

This function does not leave this object in an invalid state. It is permissable to clear a QoS and then subsequently allocate new dynamic memory in one or more of its QoS policies.

Note that if this QoS instance is stored in heap memory, calling this function will not call free() on it; the user is responsible for explicitly freeing any heap-based QoS instance after calling this function.

Parameters
self<<in>> Cannot be NULL.
Returns
One of the Standard Return Codes
See also
DDS_TopicQos_INITIALIZER
DDS_TopicQos_initialize

◆ DDS_TopicDescription_get_type_name()

DDSCDllExport const char * DDS_TopicDescription_get_type_name ( DDS_TopicDescription * self)

<<cert>> Get the associated type_name.

The type name defines a locally unique type for the publication or the subscription.

The type_name corresponds to a unique string used to register a type via the DDS_DomainParticipant_register_type function.

Thus, the type_name implies an association with a corresponding type and this DDS_TopicDescription.

Parameters
self<<in>> Cannot be NULL.
Returns
the type name. The returned type name is valid until the DDS_TopicDescription is deleted.
Postcondition
The result is NULL if self is NULL, otherwise result is non-NULL.

◆ DDS_TopicDescription_get_name()

DDSCDllExport const char * DDS_TopicDescription_get_name ( DDS_TopicDescription * self)

<<cert>> Get the name used to create this DDS_TopicDescription .

Parameters
self<<in>> Cannot be NULL.
Returns
the name used to create this DDS_TopicDescription. The returned topic name is valid until the DDS_TopicDescription is deleted.
Postcondition
The result is NULL if self is NULL, otherwise result is non-NULL.

◆ DDS_TopicDescription_get_participant()

DDSCDllExport DDS_DomainParticipant * DDS_TopicDescription_get_participant ( DDS_TopicDescription * self)

<<cert>> Get the DDS_DomainParticipant to which the DDS_TopicDescription belongs.

Parameters
self<<in>> Cannot be NULL.
Returns
The DDS_DomainParticipant to which the DDS_TopicDescription belongs.
Postcondition
TThe result is NULL if self is NULL, otherwise result is non-NULL.

◆ DDS_Topic_as_entity()

DDSCDllExport DDS_Entity * DDS_Topic_as_entity ( DDS_Topic * self)

<<cert>> Access a DDS_Topic's DDS_Entity supertype instance.

Returns
DDS_Topic's supertype DDS_Entity instance

◆ DDS_Topic_as_topicdescription()

DDSCDllExport DDS_TopicDescription * DDS_Topic_as_topicdescription ( DDS_Topic * self)

<<cert>> Access a DDS_Topic's DDS_TopicDescription supertype instance.

Returns
DDS_Topic's supertype DDS_TopicDescription instance

◆ DDS_Topic_narrow()

DDSCDllExport DDS_Topic * DDS_Topic_narrow ( DDS_TopicDescription * self)

<<cert>> Narrow the given DDS_TopicDescription pointer to a DDS_Topic pointer.

Returns
DDS_Topic if this DDS_TopicDescription is a DDS_Topic. Otherwise, return NULL.

◆ DDS_Topic_get_inconsistent_topic_status()

DDSCDllExport DDS_ReturnCode_t DDS_Topic_get_inconsistent_topic_status ( DDS_Topic * self,
struct DDS_InconsistentTopicStatus * status )

<<cert>> Allows the application to retrieve the DDS_INCONSISTENT_TOPIC_STATUS status of a DDS_Topic.

Retrieve the current DDS_InconsistentTopicStatus

Parameters
self<<in>> Cannot be NULL.
status<<inout>> Status to be retrieved. Cannot be NULL.
Returns
One of the Standard Return Codes
See also
DDS_InconsistentTopicStatus

◆ DDS_Topic_set_qos()

DDSCDllExport DDS_ReturnCode_t DDS_Topic_set_qos ( DDS_Topic * self,
const struct DDS_TopicQos * qos )

Set the topic QoS.

Parameters
qos<<in>> Set of policies to be applied to DDS_Topic.

Policies must be consistent. Policies cannot be changed after DDS_Topic is enabled. The special value DDS_TOPIC_QOS_DEFAULT can be used to indicate that the QoS of the DDS_Topic should be changed to match the current default DDS_TopicQos set in the DDS_DomainParticipant. Cannot be NULL.

Parameters
self<<in>> Cannot be NULL.
Returns
One of the Standard Return Codes, DDS_RETCODE_IMMUTABLE_POLICY if immutable policy is changed, or DDS_RETCODE_INCONSISTENT_POLICY if policies are inconsistent
See also
DDS_TopicQos for rules on consistency among QoS
set_qos (abstract)

◆ DDS_Topic_get_qos()

DDSCDllExport DDS_ReturnCode_t DDS_Topic_get_qos ( DDS_Topic * self,
struct DDS_TopicQos * qos )

Get the topic QoS.

This function may potentially allocate memory depending on the sequences contained in some QoS policies.

Parameters
self<<in>> Cannot be NULL.
qos<<inout>> QoS to be filled up. Cannot be NULL.
Returns
One of the Standard Return Codes
See also
get_qos (abstract)

◆ DDS_Topic_set_listener()

DDSCDllExport DDS_ReturnCode_t DDS_Topic_set_listener ( DDS_Topic * self,
const struct DDS_TopicListener * listener,
DDS_StatusMask mask )

Set the topic listener.

Parameters
self<<in>> Cannot be NULL.
listener<<in>> Listener to be installed on entity.
mask<<in>> Changes of communication status to be invoked on the listener. The callback function on the listener cannot be NULL if the corresponding status is turned on in the mask.
Returns
One of the Standard Return Codes

◆ DDS_Topic_get_listener()

DDSCDllExport struct DDS_TopicListener DDS_Topic_get_listener ( DDS_Topic * self)

Get the topic listener.

Parameters
self<<in>> Cannot be NULL.
Returns
Existing listener attached to the DDS_Topic.

References DDS_Topic_get_listener().

Referenced by DDS_Topic_get_listener().