DDS_Publisher entity and associated elements More...

Data Structures
struct	DDS_PublisherSeq
	Declares IDL `sequence` < DDS_Publisher > . More...

struct	DDS_PublisherQos
	QoS policies supported by a DDS_Publisher entity. More...

struct	DDS_PublisherListener
	<<interface>> DDS_Listener for DDS_Publisher status. More...

Macros
#define	DDS_PublisherQos_INITIALIZER
	Initializer for new QoS instances.

#define	DDS_PublisherListener_INITIALIZER
	Initializer for new DDS_PublisherListener.

Typedefs
typedef struct DDS_PublisherImpl	DDS_Publisher
	<<interface>> A publisher is the object responsible for the actual dissemination of publications.

Functions
DDS_ReturnCode_t	DDS_PublisherQos_initialize (struct DDS_PublisherQos *self)
	Initializer for new QoS instances.

DDS_ReturnCode_t	DDS_PublisherQos_copy (struct DDS_PublisherQos self, const struct DDS_PublisherQos source)
	Copy the contents of the given QoS into this QoS.

DDS_ReturnCode_t	DDS_PublisherQos_finalize (struct DDS_PublisherQos *self)
	Free any dynamic memory allocated by the policies in this DDS_PublisherQos.

DDS_Entity *	DDS_Publisher_as_entity (DDS_Publisher *publisher)
	Access a DDS_Publisher's supertype instance.

DDS_ReturnCode_t	DDS_Publisher_get_default_datawriter_qos (DDS_Publisher self, struct DDS_DataWriterQos qos)
	Copies the default DDS_DataWriterQos values into the provided DDS_DataWriterQos instance.

DDS_ReturnCode_t	DDS_Publisher_set_default_datawriter_qos (DDS_Publisher self, const struct DDS_DataWriterQos qos)
	Sets the default DDS_DataWriterQos values for this publisher.

DDS_ReturnCode_t	DDS_Publisher_set_default_datawriter_qos_with_profile (DDS_Publisher self, const char library_name, const char *profile_name)
	<<eXtension>> Set the default DDS_DataWriterQos values for this publisher based on the input XML QoS profile.

DDS_ReturnCode_t	DDS_Publisher_set_default_profile (DDS_Publisher self, const char library_name, const char *profile_name)
	<<eXtension>> Sets the default XML profile for a DDS_Publisher.

DDS_ReturnCode_t	DDS_Publisher_set_default_library (DDS_Publisher self, const char library_name)
	<<eXtension>> Sets the default XML library for a DDS_Publisher.

DDS_DataWriter *	DDS_Publisher_create_datawriter (DDS_Publisher self, DDS_Topic topic, const struct DDS_DataWriterQos qos, const struct DDS_DataWriterListener listener, DDS_StatusMask mask)
	Creates a DDS_DataWriter that will be attached and belong to the DDS_Publisher.

DDS_DataWriter *	DDS_Publisher_create_datawriter_with_profile (DDS_Publisher self, DDS_Topic topic, const char library_name, const char profile_name, const struct DDS_DataWriterListener *listener, DDS_StatusMask mask)
	<<eXtension>> Creates a DDS_DataWriter object using the DDS_DataWriterQos associated with the input XML QoS profile.

DDS_ReturnCode_t	DDS_Publisher_delete_datawriter (DDS_Publisher self, DDS_DataWriter a_datawriter)
	Deletes a DDS_DataWriter that belongs to the DDS_Publisher.

DDS_DataWriter *	DDS_Publisher_lookup_datawriter (DDS_Publisher self, const char topic_name)
	Retrieves the DDS_DataWriter for a specific DDS_Topic.

DDS_ReturnCode_t	DDS_Publisher_suspend_publications (DDS_Publisher *self)
	Indicates to RTI Connext that the application is about to make multiple modifications using DDS_DataWriter objects belonging to the DDS_Publisher.

DDS_ReturnCode_t	DDS_Publisher_resume_publications (DDS_Publisher *self)
	Indicates to RTI Connext that the application has completed the multiple changes initiated by the previous DDS_Publisher_suspend_publications.

DDS_ReturnCode_t	DDS_Publisher_begin_coherent_changes (DDS_Publisher *self)
	Indicates that the application will begin a coherent set of modifications using DDS_DataWriter objects attached to the DDS_Publisher.

DDS_ReturnCode_t	DDS_Publisher_end_coherent_changes (DDS_Publisher *self)
	Terminates the coherent set initiated by the matching call to DDS_Publisher_begin_coherent_changes.

DDS_ReturnCode_t	DDS_Publisher_get_all_datawriters (DDS_Publisher self, struct DDS_DataWriterSeq writers)
	Retrieve all the DataWriters created from this Publisher.

DDS_DomainParticipant *	DDS_Publisher_get_participant (DDS_Publisher *self)
	Returns the DDS_DomainParticipant to which the DDS_Publisher belongs.

DDS_ReturnCode_t	DDS_Publisher_delete_contained_entities (DDS_Publisher *self)
	Deletes all the entities that were created by means of the "create" operation on the DDS_Publisher.

DDS_ReturnCode_t	DDS_Publisher_copy_from_topic_qos (DDS_Publisher self, struct DDS_DataWriterQos a_datawriter_qos, const struct DDS_TopicQos *a_topic_qos)
	Copies the policies in the DDS_TopicQos to the corresponding policies in the DDS_DataWriterQos.

DDS_ReturnCode_t	DDS_Publisher_set_qos (DDS_Publisher self, const struct DDS_PublisherQos qos)
	Sets the publisher QoS.

DDS_ReturnCode_t	DDS_Publisher_set_qos_with_profile (DDS_Publisher self, const char library_name, const char *profile_name)
	<<eXtension>> Change the QoS of this publisher using the input XML QoS profile.

DDS_ReturnCode_t	DDS_Publisher_get_qos (DDS_Publisher self, struct DDS_PublisherQos qos)
	Gets the publisher QoS.

const char *	DDS_Publisher_get_default_library (DDS_Publisher *self)
	<<eXtension>> Gets the default XML library associated with a DDS_Publisher.

const char *	DDS_Publisher_get_default_profile (DDS_Publisher *self)
	<<eXtension>> Gets the default XML profile associated with a DDS_Publisher.

const char *	DDS_Publisher_get_default_profile_library (DDS_Publisher *self)
	<<eXtension>> Gets the library where the default XML QoS profile is contained for a DDS_Publisher.

DDS_ReturnCode_t	DDS_Publisher_set_listener (DDS_Publisher self, const struct DDS_PublisherListener l, DDS_StatusMask mask)
	Sets the publisher listener.

struct DDS_PublisherListener	DDS_Publisher_get_listener (DDS_Publisher *self)
	Get the publisher listener.

DDS_ReturnCode_t	DDS_Publisher_get_listenerX (DDS_Publisher self, struct DDS_PublisherListener listener)
	<<eXtension>> Get the publisher listener.

DDS_ReturnCode_t	DDS_Publisher_wait_for_acknowledgments (DDS_Publisher self, const struct DDS_Duration_t max_wait)
	Blocks the calling thread until all data written by the Publisher's reliable DataWriters is acknowledged, or until timeout expires.

DDS_ReturnCode_t	DDS_Publisher_wait_for_asynchronous_publishing (DDS_Publisher self, const struct DDS_Duration_t max_wait)
	<<eXtension>> Blocks the calling thread until asynchronous sending is complete.

DDS_DataWriter *	DDS_Publisher_lookup_datawriter_by_name_exp (DDS_Publisher self, const char datawriter_name)
	<<experimental>> <<eXtension>> Retrieves a DDS_DataWriter contained within the DDS_Publisher the DDS_DataWriter entity name.

Variables
struct DDS_DataWriterQos	DDS_DATAWRITER_QOS_DEFAULT
	Special value for creating DDS_DataWriter with default QoS.

struct DDS_DataWriterQos	DDS_DATAWRITER_QOS_USE_TOPIC_QOS
	Special value for creating DDS_DataWriter with a combination of the default DDS_DataWriterQos and the DDS_TopicQos.

Detailed Description

DDS_Publisher entity and associated elements

Macro Definition Documentation

#define DDS_PublisherQos_INITIALIZER

Initializer for new QoS instances.

New DDS_PublisherQos instance 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:

struct DDS_PublisherQos myQos = DDS_PublisherQos_INITIALIZER;

Note that the above assignment is not a substitute for calling DDS_DomainParticipant_get_default_publisher_qos or DDS_Publisher_get_qos; one of those should be called subsequently to setting the QoS of a new or existing entity:

struct DDS_PublisherQos myQos = DDS_PublisherQos_INITIALIZER;
 DDS_DomainParticipant_get_default_publisher_qos(myParticipant, &myQos);
 DDS_Publisher_set_qos(myPub, &myQos);
 DDS_PublisherQos_finalize(&myQos);                     

See Also: DDS_DomainParticipant_get_default_publisher_qos; DDS_PublisherQos_finalize

#define DDS_PublisherListener_INITIALIZER

Initializer for new DDS_PublisherListener.

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

struct DDS_PublisherListener listener = DDS_PublisherListener_INITIALIZER;
 /* initialize listener functions */ 
 listener.as_datawriterlistener.on_offered_deadline_missed = ....; 
 DDS_Publisher_set_listener(myPublisher, &listener, mask);

See Also: DDS_Publisher_set_listener; DDS_PublisherListener; Operations Allowed in Listener Callbacks

Typedef Documentation

typedef struct DDS_PublisherImpl DDS_Publisher

<<interface>> A publisher is the object responsible for the actual dissemination of publications.

QoS:: DDS_PublisherQos

Listener:: DDS_PublisherListener

A publisher acts on the behalf of one or several DDS_DataWriter objects that belong to it. When it is informed of a change to the data associated with one of its DDS_DataWriter objects, it decides when it is appropriate to actually send the data-update message. In making this decision, it considers any extra information that goes with the data (timestamp, writer, etc.) as well as the QoS of the DDS_Publisher and the DDS_DataWriter.

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

See Also: Operations Allowed in Listener Callbacks

Function Documentation

DDS_ReturnCode_t DDS_PublisherQos_initialize ( struct DDS_PublisherQos * self )

Initializer for new QoS instances.

New DDS_PublisherQos instances on 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.

Calling this function is not a substitute for calling DDS_Publisher_get_qos or DDS_DomainParticipant_get_default_publisher_qos; one of those should be called subsequently to setting the QoS of any new or existing entity. DDS_PublisherQos_finalize should be called to free the contained QoS policies that use dynamic memory:

DDS_PublisherQos *myQos = malloc(sizeof(struct DDS_PublisherQos)); 
 DDS_PublisherQos_initialize(myQos); 
 DDS_Publisher_get_default_datawriter_qos(myFactory, myQos);
 DDS_Publisher_set_qos(myPublisher, myQos);
 DDS_PublisherQos_finalize(myQos);
 free(myQos);                     

Parameters

self	<<in>> Cannot be NULL.

Returns: One of the Standard Return Codes

See Also: DDS_DomainParticipant_get_default_publisher_qos; DDS_PublisherQos_finalize

DDS_ReturnCode_t DDS_PublisherQos_copy	(	struct DDS_PublisherQos *	self,
		const struct DDS_PublisherQos *	source
	)

Copy the contents of the given QoS into this QoS.

DDS_PublisherQos 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>> The DDS_PublisherQos to copy from.

Returns: One of the Standard Return Codes

See Also: DDS_PublisherQos_INITIALIZER; DDS_PublisherQos_initialize; DDS_PublisherQos_finalize

DDS_ReturnCode_t DDS_PublisherQos_finalize ( struct DDS_PublisherQos * self )

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

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_PublisherQos_INITIALIZER; DDS_PublisherQos_initialize

DDS_Entity* DDS_Publisher_as_entity ( DDS_Publisher * publisher )

Access a DDS_Publisher's supertype instance.

Parameters

publisher <<in>> Cannot be NULL.

Returns: The DDS_Entity that is supertype instance of the publisher.

DDS_ReturnCode_t DDS_Publisher_get_default_datawriter_qos	(	DDS_Publisher *	self,
		struct DDS_DataWriterQos *	qos
	)

Copies the default DDS_DataWriterQos values into the provided DDS_DataWriterQos instance.

The retreived qos will match the set of values specified on the last successful call to DDS_Publisher_set_default_datawriter_qos or DDS_Publisher_set_default_datawriter_qos_with_profile, or else, if the call was never made, the default values from is owning DDS_DomainParticipant.

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

MT Safety:: UNSAFE. It is not safe to retrieve the default QoS value from a DDS_Publisher while another thread may be simultaneously calling DDS_Publisher_set_default_datawriter_qos.

Parameters

self	<<in>> Cannot be NULL.
qos	<<inout>> DDS_DataWriterQos to be filled-up. Cannot be NULL.

Returns: One of the Standard Return Codes

See Also: DDS_DATAWRITER_QOS_DEFAULT; DDS_Publisher_create_datawriter

DDS_ReturnCode_t DDS_Publisher_set_default_datawriter_qos	(	DDS_Publisher *	self,
		const struct DDS_DataWriterQos *	qos
	)

Sets the default DDS_DataWriterQos values for this publisher.

This call causes the default values inherited from the owning DDS_DomainParticipant to be overridden.

This default value will be used for newly created DDS_DataWriter if DDS_DATAWRITER_QOS_DEFAULT is specified as the qos parameter when DDS_Publisher_create_datawriter is called.

Precondition: The specified QoS policies must be consistent, or else the operation will have no effect and fail with DDS_RETCODE_INCONSISTENT_POLICY

MT Safety:: UNSAFE. It is not safe to set the default QoS value from a DDS_Publisher while another thread may be simultaneously calling DDS_Publisher_set_default_datawriter_qos, DDS_Publisher_get_default_datawriter_qos or calling DDS_Publisher_create_datawriter with DDS_DATAWRITER_QOS_DEFAULT as the qos parameter.

Parameters

self	<<in>> Cannot be NULL.
qos	<<in>> Default qos to be set. The special value DDS_DATAREADER_QOS_DEFAULT may be passed as `qos` to indicate that the default QoS should be reset back to the initial values the factory would used if DDS_Publisher_set_default_datawriter_qos had never been called. Cannot be NULL.

Returns: One of the Standard Return Codes, or DDS_RETCODE_INCONSISTENT_POLICY

DDS_ReturnCode_t DDS_Publisher_set_default_datawriter_qos_with_profile	(	DDS_Publisher *	self,
		const char *	library_name,
		const char *	profile_name
	)

<<eXtension>> Set the default DDS_DataWriterQos values for this publisher based on the input XML QoS profile.

This default value will be used for newly created DDS_DataWriter if DDS_DATAWRITER_QOS_DEFAULT is specified as the qos parameter when DDS_Publisher_create_datawriter is called.

Precondition: The DDS_DataWriterQos contained in the specified XML QoS profile must be consistent, or else the operation will have no effect and fail with DDS_RETCODE_INCONSISTENT_POLICY

MT Safety:: UNSAFE. It is not safe to set the default QoS value from a DDS_Publisher while another thread may be simultaneously calling DDS_Publisher_set_default_datawriter_qos, DDS_Publisher_get_default_datawriter_qos or calling DDS_Publisher_create_datawriter with DDS_DATAWRITER_QOS_DEFAULT as the qos parameter.

Parameters

self	<<in>> Cannot be NULL.
library_name	<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDS_Publisher_set_default_library).
profile_name	<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDS_Publisher_set_default_profile).

If the input profile cannot be found, the function fails with DDS_RETCODE_ERROR.

Returns: One of the Standard Return Codes, or DDS_RETCODE_INCONSISTENT_POLICY

See Also: DDS_DATAWRITER_QOS_DEFAULT; DDS_Publisher_create_datawriter_with_profile

DDS_ReturnCode_t DDS_Publisher_set_default_profile	(	DDS_Publisher *	self,
		const char *	library_name,
		const char *	profile_name
	)

<<eXtension>> Sets the default XML profile for a DDS_Publisher.

This function specifies the profile that will be used as the default the next time a default Publisher profile is needed during a call to one of this Publisher's operations. When calling a DDS_Publisher function that requires a profile_name parameter, you can use NULL to refer to the default profile. (This same information applies to setting a default library.)

If the default profile is not set, the DDS_Publisher inherits the default from the DDS_DomainParticipant (see DDS_DomainParticipant_set_default_profile).

This function does not set the default QoS for DDS_DataWriter objects created by the DDS_Publisher; for this functionality, use DDS_Publisher_set_default_datawriter_qos_with_profile (you may pass in NULL after having called set_default_profile()).

This function does not set the default QoS for newly created Publishers; for this functionality, use DDS_DomainParticipant_set_default_publisher_qos_with_profile.

Parameters

self	<<in>> Cannot be NULL.
library_name	<<in>> The library name containing the profile.
profile_name	<<in>> The profile name. If profile_name is null any previous default is unset.

Returns: One of the Standard Return Codes

See Also: DDS_Publisher_get_default_profile; DDS_Publisher_get_default_profile_library

DDS_ReturnCode_t DDS_Publisher_set_default_library	(	DDS_Publisher *	self,
		const char *	library_name
	)

<<eXtension>> Sets the default XML library for a DDS_Publisher.

This function specifies the library that will be used as the default the next time a default library is needed during a call to one of this Publisher's operations.

Any API requiring a library_name as a parameter can use null to refer to the default library.

If the default library is not set, the DDS_Publisher inherits the default from the DDS_DomainParticipant (see DDS_DomainParticipant_set_default_library).

Parameters

self	<<in>> Cannot be NULL.
library_name	<<in>> Library name. If library_name is null any previous default is unset.

Returns: One of the Standard Return Codes

See Also: DDS_Publisher_get_default_library

DDS_DataWriter* DDS_Publisher_create_datawriter	(	DDS_Publisher *	self,
		DDS_Topic *	topic,
		const struct DDS_DataWriterQos *	qos,
		const struct DDS_DataWriterListener *	listener,
		DDS_StatusMask	mask
	)

Creates a DDS_DataWriter that will be attached and belong to the DDS_Publisher.

For each application-defined type, Foo, there is an implied, auto-generated class FooDataWriter that extends DDS_DataWriter and contains the operations to write data of type Foo.

Note that a common application pattern to construct the QoS for the DDS_DataWriter is to:

Retrieve the QoS policies on the associated DDS_Topic by means of the DDS_Topic_get_qos operation.
Retrieve the default DDS_DataWriter qos by means of the DDS_Publisher_get_default_datawriter_qos operation.
Combine those two QoS policies (for example, using DDS_Publisher_copy_from_topic_qos) and selectively modify policies as desired.

When a DDS_DataWriter is created, only those transports already registered are available to the DDS_DataWriter. See Built-in Transport Plugins for details on when a builtin transport is registered.

Precondition: If publisher is enabled, topic must have been enabled. Otherwise, this operation will fail and no DDS_DataWriter will be created.; The given DDS_Topic must have been created from the same participant as this publisher. If it was created from a different participant, this function will fail.

MT Safety:: UNSAFE. If DDS_DATAWRITER_QOS_DEFAULT is used for the qos parameter, it is not safe to create the datawriter while another thread may be simultaneously calling DDS_Publisher_set_default_datawriter_qos.

Parameters

self	<<in>> Cannot be NULL.
topic	<<in>> The DDS_Topic that the DDS_DataWriter will be associated with. Cannot be NULL.
qos	<<in>> QoS to be used for creating the new DDS_DataWriter. The special value DDS_DATAWRITER_QOS_DEFAULT can be used to indicate that the DDS_DataWriter should be created with the default DDS_DataWriterQos set in the DDS_Publisher. The special value DDS_DATAWRITER_QOS_USE_TOPIC_QOS can be used to indicate that the DDS_DataWriter should be created with the combination of the default DDS_DataWriterQos set on the DDS_Publisher and the DDS_TopicQos of the DDS_Topic. Cannot be NULL.
listener	<<in>> The listener of the DDS_DataWriter.
mask	<<in>>. Changes of communication status to be invoked on the listener. See DDS_StatusMask.

Returns: A DDS_DataWriter of a derived class specific to the data type associated with the DDS_Topic or NULL if an error occurred.

See Also: FooDataWriter; Specifying QoS on entities for information on setting QoS before entity creation; DDS_DataWriterQos for rules on consistency among QoS; DDS_DATAWRITER_QOS_DEFAULT; DDS_DATAWRITER_QOS_USE_TOPIC_QOS; DDS_Publisher_create_datawriter_with_profile; DDS_Publisher_get_default_datawriter_qos; DDS_Topic_set_qos; DDS_Publisher_copy_from_topic_qos; DDS_DataWriter_set_listener

Examples:: HelloWorld_publisher.c.

DDS_DataWriter* DDS_Publisher_create_datawriter_with_profile	(	DDS_Publisher *	self,
		DDS_Topic *	topic,
		const char *	library_name,
		const char *	profile_name,
		const struct DDS_DataWriterListener *	listener,
		DDS_StatusMask	mask
	)

<<eXtension>> Creates a DDS_DataWriter object using the DDS_DataWriterQos associated with the input XML QoS profile.

The DDS_DataWriter will be attached and belong to the DDS_Publisher.

For each application-defined type, Foo, there is an implied, auto-generated class FooDataWriter that extends DDS_DataWriter and contains the operations to write data of type Foo.

When a DDS_DataWriter is created, only those transports already registered are available to the DDS_DataWriter. See Built-in Transport Plugins for details on when a builtin transport is registered.

Precondition: If publisher is enabled, topic must have been enabled. Otherwise, this operation will fail and no DDS_DataWriter will be created.; The given DDS_Topic must have been created from the same participant as this publisher. If it was created from a different participant, this function will return NULL.

Parameters

self	<<in>> Cannot be NULL.
topic	<<in>> The DDS_Topic that the DDS_DataWriter will be associated with. Cannot be NULL.
library_name	<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDS_Publisher_set_default_library).
profile_name	<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDS_Publisher_set_default_profile).
listener	<<in>> The listener of the DDS_DataWriter.
mask	<<in>>. Changes of communication status to be invoked on the listener. See DDS_StatusMask.

Returns: A DDS_DataWriter of a derived class specific to the data type associated with the DDS_Topic or NULL if an error occurred.

See Also: FooDataWriter; Specifying QoS on entities for information on setting QoS before entity creation; DDS_DataWriterQos for rules on consistency among QoS; DDS_Publisher_create_datawriter; DDS_Publisher_get_default_datawriter_qos; DDS_Topic_set_qos; DDS_Publisher_copy_from_topic_qos; DDS_DataWriter_set_listener

DDS_ReturnCode_t DDS_Publisher_delete_datawriter	(	DDS_Publisher *	self,
		DDS_DataWriter *	a_datawriter
	)

Deletes a DDS_DataWriter that belongs to the DDS_Publisher.

The deletion of the DDS_DataWriter will automatically unregister all instances. Depending on the settings of the WRITER_DATA_LIFECYCLE QosPolicy, the deletion of the DDS_DataWriter may also dispose all instances.

Special Instructions if Using 'Timestamp' APIs and BY_SOURCE_TIMESTAMP Destination Ordering:

If the DataWriter's DDS_DestinationOrderQosPolicy::kind is DDS_BY_SOURCE_TIMESTAMP_DESTINATIONORDER_QOS, calls to delete_datawriter() may fail if your application has previously used the 'with timestamp' APIs (write_w_timestamp(), register_instance_w_timestamp(), unregister_instance_w_timestamp(), or dispose_w_timestamp()) with a timestamp larger (later) than the time at which delete_datawriter() is called. To prevent delete_datawriter() from failing in this situation, either:

Change the WRITER_DATA_LIFECYCLE QosPolicy so that RTI Connext will not autodispose unregistered instances (set DDS_WriterDataLifecycleQosPolicy::autodispose_unregistered_instances to DDS_BOOLEAN_FALSE.) or
Explicitly call unregister_instance_w_timestamp() for all instances modified with the *_w_timestamp() APIs before calling delete_datawriter().

Precondition: If the DDS_DataWriter does not belong to the DDS_Publisher, the operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET.

Postcondition: Listener installed on the DDS_DataWriter will not be called after this function completes successfully.

Parameters

self	<<in>> Cannot be NULL.
a_datawriter	<<in>> The DDS_DataWriter to be deleted.

Returns: One of the Standard Return Codes or DDS_RETCODE_PRECONDITION_NOT_MET.

DDS_DataWriter* DDS_Publisher_lookup_datawriter	(	DDS_Publisher *	self,
		const char *	topic_name
	)

Retrieves the DDS_DataWriter for a specific DDS_Topic.

This returned DDS_DataWriter is either enabled or disabled.

Parameters

self	<<in>> Cannot be NULL.
topic_name	<<in>> Name of the DDS_Topic associated with the DDS_DataWriter that is to be looked up. Cannot be NULL.

Returns: A DDS_DataWriter that belongs to the DDS_Publisher attached to the DDS_Topic with topic_name. If no such DDS_DataWriter exists, this operation returns NULL.

If more than one DDS_DataWriter is attached to the DDS_Publisher with the same topic_name, then this operation may return any one of them.

MT Safety:: UNSAFE. It is not safe to lookup a DDS_DataWriter in one thread while another thread is simultaneously creating or destroying that DDS_DataWriter.

DDS_ReturnCode_t DDS_Publisher_suspend_publications ( DDS_Publisher * self )

Indicates to RTI Connext that the application is about to make multiple modifications using DDS_DataWriter objects belonging to the DDS_Publisher.

It is a hint to RTI Connext so it can optimize its performance by e.g., holding the dissemination of the modifications and then batching them.

The use of this operation must be matched by a corresponding call to DDS_Publisher_resume_publications indicating that the set of modifications has completed.

If the DDS_Publisher is deleted before DDS_Publisher_resume_publications is called, any suspended updates yet to be published will be discarded.

RTI Connext is not required and does not currently make use of this hint in any way. However, similar results can be achieved by using asynchronous publishing. Combined with DDS_FlowController, DDS_ASYNCHRONOUS_PUBLISH_MODE_QOS DDS_DataWriter instances allow the user even finer control of traffic shaping and sample coalescing.

Parameters

self	<<in>> Cannot be NULL.

Returns: One of the Standard Return Codes or DDS_RETCODE_NOT_ENABLED.

See Also: DDS_FlowController; DDS_FlowController_trigger_flow; DDS_ON_DEMAND_FLOW_CONTROLLER_NAME; DDS_PublishModeQosPolicy

DDS_ReturnCode_t DDS_Publisher_resume_publications ( DDS_Publisher * self )

Indicates to RTI Connext that the application has completed the multiple changes initiated by the previous DDS_Publisher_suspend_publications.

This is a hint to RTI Connext that can be used for example, to batch all the modifications made since the DDS_Publisher_suspend_publications.

RTI Connext is not required and does not currently make use of this hint in any way. However, similar results can be achieved by using asynchronous publishing. Combined with DDS_FlowController, DDS_ASYNCHRONOUS_PUBLISH_MODE_QOS DDS_DataWriter instances allow the user even finer control of traffic shaping and sample coalescing.

Precondition: A call to DDS_Publisher_resume_publications must match a previous call to DDS_Publisher_suspend_publications. Otherwise the operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET.

Parameters

self	<<in>> Cannot be NULL.

Returns: One of the Standard Return Codes or DDS_RETCODE_PRECONDITION_NOT_MET or DDS_RETCODE_NOT_ENABLED.

See Also: DDS_FlowController; DDS_FlowController_trigger_flow; DDS_ON_DEMAND_FLOW_CONTROLLER_NAME; DDS_PublishModeQosPolicy

DDS_ReturnCode_t DDS_Publisher_begin_coherent_changes ( DDS_Publisher * self )

Indicates that the application will begin a coherent set of modifications using DDS_DataWriter objects attached to the DDS_Publisher.

A 'coherent set' is a set of modifications that must be propagated in such a way that they are interpreted at the receiver's side as a consistent set of modifications; that is, the receiver will only be able to access the data after all the modifications in the set are available at the receiver end.

A connectivity change may occur in the middle of a set of coherent changes; for example, the set of partitions used by the DDS_Publisher or one of its DDS_Subscriber s may change, a late-joining DDS_DataReader may appear on the network, or a communication failure may occur. In the event that such a change prevents an entity from receiving the entire set of coherent changes, that entity must behave as if it had received none of the set.

These calls can be nested. In that case, the coherent set terminates only with the last call to DDS_Publisher_end_coherent_changes.

The support for coherent changes enables a publishing application to change the value of several data-instances that could belong to the same or different topics and have those changes be seen atomically by the readers. This is useful in cases where the values are inter-related (for example, if there are two data-instances representing the altitude and velocity vector of the same aircraft and both are changed, it may be useful to communicate those values in a way the reader can see both together; otherwise, it may e.g., erroneously interpret that the aircraft is on a collision course).

Parameters

self	<<in>> Cannot be NULL.

Returns: One of the Standard Return Codes or DDS_RETCODE_NOT_ENABLED.

DDS_ReturnCode_t DDS_Publisher_end_coherent_changes ( DDS_Publisher * self )

Terminates the coherent set initiated by the matching call to DDS_Publisher_begin_coherent_changes.

Precondition: If there is no matching call to DDS_Publisher_begin_coherent_changes the operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET.

Parameters

self	<<in>> Cannot be NULL.

Returns: One of the Standard Return Codes, DDS_RETCODE_PRECONDITION_NOT_MET or DDS_RETCODE_NOT_ENABLED.

DDS_ReturnCode_t DDS_Publisher_get_all_datawriters	(	DDS_Publisher *	self,
		struct DDS_DataWriterSeq *	writers
	)

Retrieve all the DataWriters created from this Publisher.

Parameters

self	<<in>> Cannot be NULL.
writers	<<inout>> Sequence where the DataWriters will be added

Returns: One of the Standard Return Codes

DDS_DomainParticipant* DDS_Publisher_get_participant ( DDS_Publisher * self )

Returns the DDS_DomainParticipant to which the DDS_Publisher belongs.

Parameters

self	<<in>> Cannot be NULL.

Returns: the DDS_DomainParticipant to which the DDS_Publisher belongs.

DDS_ReturnCode_t DDS_Publisher_delete_contained_entities ( DDS_Publisher * self )

Deletes all the entities that were created by means of the "create" operation on the DDS_Publisher.

Deletes all contained DDS_DataWriter objects. Once DDS_Publisher_delete_contained_entities completes successfully, the application may delete the DDS_Publisher, knowing that it has no contained DDS_DataWriter objects.

The operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET if any of the contained entities is in a state where it cannot be deleted.

Parameters

self	<<in>> Cannot be NULL.

Returns: One of the Standard Return Codes or DDS_RETCODE_PRECONDITION_NOT_MET.

DDS_ReturnCode_t DDS_Publisher_copy_from_topic_qos	(	DDS_Publisher *	self,
		struct DDS_DataWriterQos *	a_datawriter_qos,
		const struct DDS_TopicQos *	a_topic_qos
	)

Copies the policies in the DDS_TopicQos to the corresponding policies in the DDS_DataWriterQos.

Copies the policies in the DDS_TopicQos to the corresponding policies in the DDS_DataWriterQos (replacing values in the DDS_DataWriterQos, if present).

This is a "convenience" operation most useful in combination with the operations DDS_Publisher_get_default_datawriter_qos and DDS_Topic_get_qos. The operation DDS_Publisher_copy_from_topic_qos can be used to merge the DDS_DataWriter default QoS policies with the corresponding ones on the DDS_Topic. The resulting QoS can then be used to create a new DDS_DataWriter, or set its QoS.

This operation does not check the resulting DDS_DataWriterQos for consistency. This is because the 'merged' DDS_DataWriterQos may not be the final one, as the application can still modify some policies prior to applying the policies to the DDS_DataWriter.

Parameters

self	<<in>> Cannot be NULL.
a_datawriter_qos	<<inout>> DDS_DataWriterQos to be filled-up. Cannot be NULL.
a_topic_qos	<<in>> DDS_TopicQos to be merged with DDS_DataWriterQos. Cannot be NULL.

Returns: One of the Standard Return Codes

DDS_ReturnCode_t DDS_Publisher_set_qos	(	DDS_Publisher *	self,
		const struct DDS_PublisherQos *	qos
	)

Sets the publisher QoS.

This operation modifies the QoS of the DDS_Publisher.

The DDS_PublisherQos::group_data, DDS_PublisherQos::partition and DDS_PublisherQos::entity_factory can be changed. The other policies are immutable.

Parameters

self	<<in>> Cannot be NULL.
qos	<<in>> DDS_PublisherQos to be set to. Policies must be consistent. Immutable policies cannot be changed after DDS_Publisher is enabled. The special value DDS_PUBLISHER_QOS_DEFAULT can be used to indicate that the QoS of the DDS_Publisher should be changed to match the current default DDS_PublisherQos set in the DDS_DomainParticipant. Cannot be NULL.

Returns: One of the Standard Return Codes, DDS_RETCODE_IMMUTABLE_POLICY, or DDS_RETCODE_INCONSISTENT_POLICY.

See Also: DDS_PublisherQos for rules on consistency among QoS; set_qos (abstract); Operations Allowed in Listener Callbacks

DDS_ReturnCode_t DDS_Publisher_set_qos_with_profile	(	DDS_Publisher *	self,
		const char *	library_name,
		const char *	profile_name
	)

<<eXtension>> Change the QoS of this publisher using the input XML QoS profile.

This operation modifies the QoS of the DDS_Publisher.

The DDS_PublisherQos::group_data, DDS_PublisherQos::partition and DDS_PublisherQos::entity_factory can be changed. The other policies are immutable.

Parameters

self	<<in>> Cannot be NULL.
library_name	<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDS_Publisher_set_default_library).
profile_name	<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDS_Publisher_set_default_profile).

Returns: One of the Standard Return Codes, DDS_RETCODE_IMMUTABLE_POLICY, or DDS_RETCODE_INCONSISTENT_POLICY.

See Also: DDS_PublisherQos for rules on consistency among QoS; Operations Allowed in Listener Callbacks

DDS_ReturnCode_t DDS_Publisher_get_qos	(	DDS_Publisher *	self,
		struct DDS_PublisherQos *	qos
	)

Gets the publisher QoS.

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

Parameters

self	<<in>> Cannot be NULL.
qos	<<in>> DDS_PublisherQos to be filled in. Cannot be NULL.

Returns: One of the Standard Return Codes

See Also: get_qos (abstract)

const char* DDS_Publisher_get_default_library ( DDS_Publisher * self )

<<eXtension>> Gets the default XML library associated with a DDS_Publisher.

Parameters

self	<<in>> Cannot be NULL.

Returns: The default library or null if the default library was not set.

See Also: DDS_Publisher_set_default_library

const char* DDS_Publisher_get_default_profile ( DDS_Publisher * self )

<<eXtension>> Gets the default XML profile associated with a DDS_Publisher.

Parameters

self	<<in>> Cannot be NULL.

Returns: The default profile or null if the default profile was not set.

See Also: DDS_Publisher_set_default_profile

const char* DDS_Publisher_get_default_profile_library ( DDS_Publisher * self )

<<eXtension>> Gets the library where the default XML QoS profile is contained for a DDS_Publisher.

The default profile library is automatically set when DDS_Publisher_set_default_profile is called.

This library can be different than the DDS_Publisher default library (see DDS_Publisher_get_default_library).

Parameters

self	<<in>> Cannot be NULL.

Returns: The default profile library or null if the default profile was not set.

See Also: DDS_Publisher_set_default_profile

DDS_ReturnCode_t DDS_Publisher_set_listener	(	DDS_Publisher *	self,
		const struct DDS_PublisherListener *	l,
		DDS_StatusMask	mask
	)

Sets the publisher listener.

Parameters

self	<<in>> Cannot be NULL.
l	<<in>> DDS_PublisherListener to set to.
mask	<<in>> DDS_StatusMask associated with the DDS_PublisherListener. 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

See Also: set_listener (abstract)

struct DDS_PublisherListener DDS_Publisher_get_listener ( DDS_Publisher * self )

read

Get the publisher listener.

Parameters

self	<<in>> Cannot be NULL.

Returns: DDS_PublisherListener of the DDS_Publisher.

See Also: DDS_Publisher_get_listenerX; get_listener (abstract)

DDS_ReturnCode_t DDS_Publisher_get_listenerX	(	DDS_Publisher *	self,
		struct DDS_PublisherListener *	listener
	)

<<eXtension>> Get the publisher listener.

An alternative form of get_listener that fills in an existing listener structure rather than returning one on the stack.

Parameters

self	<<in>> Cannot be NULL.
listener	<<inout>> DDS_PublisherListener structure to be filled up. Cannot be NULL.

Returns: One of the Standard Return Codes

See Also: DDS_Publisher_get_listener; get_listener (abstract)

DDS_ReturnCode_t DDS_Publisher_wait_for_acknowledgments	(	DDS_Publisher *	self,
		const struct DDS_Duration_t *	max_wait
	)

Blocks the calling thread until all data written by the Publisher's reliable DataWriters is acknowledged, or until timeout expires.

This operation blocks the calling thread until either all data written by the reliable DataWriters entities is acknowledged by (a) all reliable DDS_DataReader entities that are matched and alive and (b) by all required subscriptions, or until the duration specified by the max_wait parameter elapses, whichever happens first. A successful completion indicates that all the samples written have been acknowledged; a return value of TIMEOUT indicates that max_wait elapsed before all the data was acknowledged.

Note that if a thread is blocked in the call to this operation on a DDS_Publisher and a different thread writes new samples on any of the reliable DataWriters that belong to this Publisher, the new samples must be acknowledged before unblocking the thread that is waiting on this operation.

If none of the DDS_DataWriter instances have DDS_ReliabilityQosPolicy kind set to RELIABLE, the operation will complete successfully.

Parameters

self	<<in>> Cannot be NULL.
max_wait	<<in>> Specifies maximum time to wait for acknowledgements DDS_Duration_t .

Returns: One of the Standard Return Codes, DDS_RETCODE_NOT_ENABLED, DDS_RETCODE_TIMEOUT

DDS_ReturnCode_t DDS_Publisher_wait_for_asynchronous_publishing	(	DDS_Publisher *	self,
		const struct DDS_Duration_t *	max_wait
	)

<<eXtension>> Blocks the calling thread until asynchronous sending is complete.

This operation blocks the calling thread (up to max_wait) until all data written by the asynchronous DDS_DataWriter entities is sent and acknowledged (if reliable) by all matched DDS_DataReader entities. A successful completion indicates that all the samples written have been sent and acknowledged where applicable; if it times out, this indicates that max_wait elapsed before all the data was sent and/or acknowledged.

In other words, this guarantees that sending to best effort DDS_DataReader is complete in addition to what DDS_Publisher_wait_for_acknowledgments provides.

If none of the DDS_DataWriter instances have DDS_PublishModeQosPolicy::kind set to DDS_ASYNCHRONOUS_PUBLISH_MODE_QOS, the operation will complete immediately, with DDS_RETCODE_OK.

Parameters

self	<<in>> Cannot be NULL.
max_wait	<<in>> Specifies maximum time to wait for acknowledgements DDS_Duration_t.

Returns: One of the Standard Return Codes, DDS_RETCODE_NOT_ENABLED, DDS_RETCODE_TIMEOUT

DDS_DataWriter* DDS_Publisher_lookup_datawriter_by_name_exp	(	DDS_Publisher *	self,
		const char *	datawriter_name
	)

<<experimental>> <<eXtension>> Retrieves a DDS_DataWriter contained within the DDS_Publisher the DDS_DataWriter entity name.

Every DDS_DataWriter in the system has an entity name which is configured and stored in the <<eXtension>> EntityName policy, ENTITY_NAME.

This operation retrieves the DDS_DataWriter within the DDS_Publisher whose name matches the one specified. If there are several DDS_DataWriter with the same name within the DDS_Publisher, the operation returns the first matching occurrence.

Parameters

self	<<in>> Cannot be NULL.
datawriter_name	<<in>> Entity name of the DDS_DataWriter.

Returns: The first DDS_DataWriter found with the specified name or NULL if it is not found.

See Also: DDS_DomainParticipant_lookup_datawriter_by_name_exp

Variable Documentation

struct DDS_DataWriterQos DDS_DATAWRITER_QOS_DEFAULT

Special value for creating DDS_DataWriter with default QoS.

When used in DDS_Publisher_create_datawriter, this special value is used to indicate that the DDS_DataWriter should be created with the default DDS_DataWriter QoS by means of the operation get_default_datawriter_qos and using the resulting QoS to create the DDS_DataWriter.

When used in DDS_Publisher_set_default_datawriter_qos, this special value is used to indicate that the default QoS should be reset back to the initial value that would be used if the DDS_Publisher_set_default_datawriter_qos operation had never been called.

When used in DDS_DataWriter_set_qos, this special value is used to indicate that the QoS of the DDS_DataWriter should be changed to match the current defualt QoS set in the DDS_Publisher that the DDS_DataWriter belongs to.

Note: You cannot use this value to get the default QoS values for a DataWriter; for this purpose, use DDS_DomainParticipant_get_default_datawriter_qos.

See Also: DDS_Publisher_create_datawriter; DDS_Publisher_set_default_datawriter_qos; DDS_DataWriter_set_qos

Examples:: HelloWorld_publisher.c.

struct DDS_DataWriterQos DDS_DATAWRITER_QOS_USE_TOPIC_QOS

Special value for creating DDS_DataWriter with a combination of the default DDS_DataWriterQos and the DDS_TopicQos.

The use of this value is equivalent to the application obtaining the default DDS_DataWriterQos and the DDS_TopicQos (by means of the operation DDS_Topic_get_qos) and then combining these two QoS using the operation DDS_Publisher_copy_from_topic_qos whereby any policy that is set on the DDS_TopicQos "overrides" the corresponding policy on the default QoS. The resulting QoS is then applied to the creation of the DDS_DataWriter.

This value should only be used in DDS_Publisher_create_datawriter.

See Also: DDS_Publisher_create_datawriter; DDS_Publisher_get_default_datawriter_qos; DDS_Topic_get_qos; DDS_Publisher_copy_from_topic_qos

Data Structures

Macros

Typedefs

Functions

Variables

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation

Special Instructions if Using 'Timestamp' APIs and BY_SOURCE_TIMESTAMP Destination Ordering:

Variable Documentation