Publisher

DDS_Publisher entity and associated elements More...

Data Structures
struct	DDS_PublisherQos
	<<cert>> QoS policies supported by a DDS_Publisher entity. More...
struct	DDS_PublisherListener
	<<interface>> <<cert>> DDS_Listener for DDS_Publisher status. More...

Macros
#define	DDS_PublisherQos_INITIALIZER
	<<cert>> Initializer for new QoS instances.
#define	DDS_PublisherListener_INITIALIZER
	<<cert>> Initializer for new DDS_PublisherListener.

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

Functions
DDSCDllExport DDS_ReturnCode_t	DDS_PublisherQos_initialize (struct DDS_PublisherQos *self)
	Initializer for new QoS instances.
DDSCDllExport 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.
DDSCDllExport 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)
	<<cert>> Access a DDS_Publisher's supertype instance.
DDSCDllExport 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.
DDSCDllExport 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.
DDSCDllExport 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)
	<<cert>> Creates a DDS_DataWriter that will be attached and belong to the DDS_Publisher.
DDSCDllExport DDS_ReturnCode_t	DDS_Publisher_delete_datawriter (DDS_Publisher *self, DDS_DataWriter *a_datawriter)
	Deletes a DDS_DataWriter that belongs to the DDS_Publisher.
DDSCDllExport DDS_DataWriter *	DDS_Publisher_lookup_datawriter (DDS_Publisher *self, const char *topic_name)
	<<cert>> Retrieves the DDS_DataWriter for a specific DDS_Topic.
DDSCDllExport DDS_DataWriter *	DDS_Publisher_lookup_datawriter_by_name (DDS_Publisher *self, const char *writer_name)
	<<cert>> Retrieves a DDS_DataWriter by its entity name within this DDS_Publisher
DDSCDllExport DDS_DomainParticipant *	DDS_Publisher_get_participant (DDS_Publisher *self)
	<<cert>> Returns the DDS_DomainParticipant to which the DDS_Publisher belongs.
DDSCDllExport 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.
DDSCDllExport DDS_ReturnCode_t	DDS_Publisher_set_qos (DDS_Publisher *self, const struct DDS_PublisherQos *qos)
	Sets the publisher QoS.
DDSCDllExport DDS_ReturnCode_t	DDS_Publisher_get_qos (DDS_Publisher *self, struct DDS_PublisherQos *qos)
	Gets the publisher QoS.
DDSCDllExport DDS_ReturnCode_t	DDS_Publisher_set_listener (DDS_Publisher *self, const struct DDS_PublisherListener *listener, DDS_StatusMask mask)
	Sets the publisher listener.
DDSCDllExport struct DDS_PublisherListener	DDS_Publisher_get_listener (DDS_Publisher *self)
	Get the publisher listener.

Variables
DDSCDllVariable const struct DDS_DataWriterQos	DDS_DATAWRITER_QOS_DEFAULT
	<<cert>> Special value for creating DDS_DataWriter with default QoS

Detailed Description

DDS_Publisher entity and associated elements

Macro Definition Documentation

DDS_PublisherQos_INITIALIZER

#define DDS_PublisherQos_INITIALIZER

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

DDS_PublisherQos myQos = DDS_PublisherQos_INITIALIZER;                      

See also

DDS_PublisherQos_finalize

DDS_PublisherListener_INITIALIZER

#define DDS_PublisherListener_INITIALIZER

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

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

Typedef Documentation

DDS_Publisher

typedef struct DDS_PublisherImpl DDS_Publisher

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

• The base-class operations DDS_Entity_enable
• DDS_Publisher_create_datawriter, DDS_Publisher_delete_datawriter, DDS_Publisher_delete_contained_entities,

Function Documentation

DDS_PublisherQos_initialize()

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

Parameters

self	<<in>> Cannot be NULL.

Returns

One of the Standard Return Codes

See also

DDS_PublisherQos_finalize

DDS_PublisherQos_copy()

DDSCDllExport 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_PublisherQos_finalize()

DDSCDllExport 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_Publisher_as_entity()

DDS_Entity * DDS_Publisher_as_entity

(

DDS_Publisher *

publisher

)

<<cert>> 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_Publisher_get_default_datawriter_qos()

DDSCDllExport 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 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_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	<<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_Publisher_set_default_datawriter_qos()

DDSCDllExport 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 retrieve the default QoS value from a DDS_Publisher while another thread may be simultaneously calling 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 have 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_Publisher_create_datawriter()

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

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

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.

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.

Cannot be NULL.

Parameters

listener	<<in>> The listener of the DDS_DataWriter.
mask	<<in>>. Changes of communication status to be invoked on the listener.

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

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_Publisher_delete_datawriter()

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

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_Publisher_lookup_datawriter()

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

<<cert>> 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_Publisher_lookup_datawriter_by_name()

DDSCDllExport DDS_DataWriter * DDS_Publisher_lookup_datawriter_by_name	(	DDS_Publisher *	self,
		const char *	writer_name )

<<cert>> Retrieves a DDS_DataWriter by its entity name within this DDS_Publisher

This returned DDS_DataWriter is either enabled or disabled.

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

This operation retrieves a DDS_DataWriter within the DDS_Publisher given the entity's name. If there are several DDS_DataWriter with the same name within the DDS_Publisher, this function returns the first matching occurrence.

Parameters

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

Returns

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

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_Publisher_get_participant()

DDSCDllExport DDS_DomainParticipant * DDS_Publisher_get_participant

(

DDS_Publisher *

self

)

<<cert>> 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_Publisher_delete_contained_entities()

DDSCDllExport 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_Publisher_set_qos()

DDSCDllExport 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::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. 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)

DDS_Publisher_get_qos()

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

DDS_Publisher_set_listener()

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

Sets the publisher listener.

Parameters

self	<<in>> Cannot be NULL.
listener	<<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)

DDS_Publisher_get_listener()

DDSCDllExport struct DDS_PublisherListener DDS_Publisher_get_listener

(

DDS_Publisher *

self

)

Get the publisher listener.

Parameters

self	<<in>> Cannot be NULL.

Returns

DDS_PublisherListener of the DDS_Publisher.

References DDS_Publisher_get_listener().

Referenced by DDS_Publisher_get_listener().

Variable Documentation

DDS_DATAWRITER_QOS_DEFAULT

DDSCDllVariable const struct DDS_DataWriterQos DDS_DATAWRITER_QOS_DEFAULT

extern

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

See also

DDS_Publisher_create_datawriter