The DomainParticipant is used to configure, create and destroy Publisher, Subscriber and Topic objects. More...
Public Member Functions | |
ReturnCode_t | enable () |
Enables the DomainParticipant. More... | |
ReturnCode_t | get_qos (DomainParticipantQos qos) |
ReturnCode_t | set_qos (DomainParticipantQos qos) |
ReturnCode_t | set_listener (DomainParticipantListener new_listener, long mask) |
DomainParticipantListener | get_listener () |
Publisher | create_publisher (PublisherQos qos, PublisherListener listener, long mask) |
ReturnCode_t | delete_publisher (Publisher p) |
Subscriber | create_subscriber (SubscriberQos qos, SubscriberListener listener, long mask) |
ReturnCode_t | delete_subscriber (Subscriber s) |
Topic | create_topic (String topic_name, String type_name, TopicQos qos, TopicListener listener, long mask) |
ContentFilteredTopic | create_contentfilteredtopic (String name, Topic related_topic, String filter_expression, Vector filter_parameters) |
ReturnCode_t | delete_contentfilteredtopic (ContentFilteredTopic cft) |
MultiTopic | create_multitopic (String name, String type_name, String subscription_expression, Vector expression_params) |
ReturnCode_t | delete_multitopic (MultiTopic a_multitopic) |
ReturnCode_t | delete_topic (Topic topic) |
Topic | find_topic (String topic_name, Duration_t timeout) |
TopicDescription | lookup_topicdescription (String name) |
Subscriber | get_builtin_subscriber () |
ReturnCode_t | ignore_participant (InstanceHandle_t handle) |
ReturnCode_t | ignore_topic (InstanceHandle_t handle) |
ReturnCode_t | ignore_publication (InstanceHandle_t handle) |
ReturnCode_t | ignore_subscription (InstanceHandle_t handle) |
long | get_domain_id () |
ReturnCode_t | delete_contained_entities () |
ReturnCode_t | assert_liveliness () |
ReturnCode_t | set_default_publisher_qos (PublisherQos qos) |
ReturnCode_t | get_default_publisher_qos (PublisherQos qos) |
ReturnCode_t | set_default_subscriber_qos (SubscriberQos qos) |
ReturnCode_t | get_default_subscriber_qos (SubscriberQos qos) |
ReturnCode_t | set_default_topic_qos (TopicQos qos) |
ReturnCode_t | get_default_topic_qos (TopicQos qos) |
ReturnCode_t | get_discovered_participants (InstanceHandleSeq participant_handles) |
ReturnCode_t | get_discovered_participant_data (ParticipantBuiltinTopicData participant_data, InstanceHandle_t participant_handle) |
ReturnCode_t | get_discovered_topics (Vector topic_handles) |
ReturnCode_t | get_discovered_topic_data (TopicBuiltinTopicData topic_data, InstanceHandle_t topic_handle) |
boolean | contains_entity (InstanceHandle_t handle) |
ReturnCode_t | get_current_time (Time_t current_time) |
ReturnCode_t | register_type (TypeSupport ts, String type_name) |
Registers a TypeSupport with the Participant. More... | |
ReturnCode_t | get_guid (GUID_t g) |
Access the GUID which uniquely identifies this participant. | |
ReturnCode_t | add_tcp_transport () |
Removed. Install the TCP Transport. Must be called before enabling the DomainParticipant. The DomainParticipant will default to using standard UDP RTPS transport. Adding the TCP Transport will override this default. More... | |
ReturnCode_t | add_transport (Transport t) |
Install the provided Transport. More... | |
ReturnCode_t | do_work (Duration_t time_slice) |
Transfer control to the DomainParticipant so it can do background processing. More... | |
ReturnCode_t | builtin_wait_for_acknowledgments (Duration_t max_wait) |
Public Member Functions inherited from Entity | |
StatusCondition | get_statuscondition () |
int | get_status_changes () |
ReturnCode_t | enable () |
InstanceHandle_t | get_instance_handle () |
The DomainParticipant is used to configure, create and destroy Publisher, Subscriber and Topic objects.
The DomainParticipant is a container for the objects that it creates. The objects operate within the domain identified by the domain_id provided when the DomainParticipant was created. Objects within different domains do not communicate or interfere with each other.
ReturnCode_t add_tcp_transport | ( | ) |
Removed. Install the TCP Transport. Must be called before enabling the DomainParticipant. The DomainParticipant will default to using standard UDP RTPS transport. Adding the TCP Transport will override this default.
ReturnCode_t add_transport | ( | Transport | t | ) |
Install the provided Transport.
Must be called before enabling the DomainParticipant. The DomainParticipant will default to using standard UDP RTPS transport, if no other transports are added.
ReturnCode_t assert_liveliness | ( | ) |
This operation manually asserts the liveliness of the DomainParticipant dp. This operation indicates that the DomainParticipant is still alive. It is effective only if the DomainParticipant contains on ore more DataWriter objects with LIVELINES QoS set to MANUAL_BY_PARTICIPANT_LIVELINESS_QOS. In this case, the operation will assert the liveliness of those particular DataWriter objects.
Writing data via the DataWriter write operation automatically asserts the liveliness of the DataWriter and its containing DomainParticipant. Therefore, the use of DomainParticipant.assert_liveliness() is needed only if the application is not writing data frequently enough to keep the DataWriter considered 'alive'.
ReturnCode_t builtin_wait_for_acknowledgments | ( | Duration_t | max_wait | ) |
Ensure that local discovery information has been received by all known peers.
boolean contains_entity | ( | InstanceHandle_t | handle | ) |
This operation checks whether or not the given handle a_handle represents an object that was created by the DomainParticipant d. This applies recursively to all objects created by the DomainParticipant.
The routine will return true (non-zero) if the handle is found, zero otherwise.
ContentFilteredTopic create_contentfilteredtopic | ( | String | name, |
Topic | related_topic, | ||
String | filter_expression, | ||
Vector | filter_parameters | ||
) |
This operation creates a ContentFilteredTopic.
The ContentFilteredTopic is associated with another un-filtered topic related_topic.
The filter_expression is an SQL like condition expression, and filter_parameters provide optional parameters that are referenced by the filter_expression. The syntax of the filter expression is similar to the WHERE clause in SQL. For example "x<4" is a valid filter expression. It would test that data member 'x' is less than value '4'. If the filter expression evaluates to TRUE, then the data sample will be available, otherwise the data sample would be 'filtered' (excluded).
The filter_expression can refer to parameters. The syntax for paramters is the percent sign '' followed by a number. The number is the index of the paramter in the filter_paramters sequence. Parameters are counted starting at zero. So, "%0" refers to the first parameter, and "%4" refers to the fifth paramter. Using this syntax, the expression "x<%0" would test the value of 'x' against the first parameter in the sequence.
MultiTopic create_multitopic | ( | String | name, |
String | type_name, | ||
String | subscription_expression, | ||
Vector | expression_params | ||
) |
Publisher create_publisher | ( | PublisherQos | qos, |
PublisherListener | listener, | ||
long | mask | ||
) |
This operation creates a Publisher with the specified PublisherQoS settings and PublisherListener. The value DDS.PUBLISHER_QOS_DEFAULT may be provided for the qos argument. This will indicate that the the default publisher QoS settings held in the DomainParticipant should be used.
This operation may fail and return NULL if the QoS settings are internally inconsistent.
Subscriber create_subscriber | ( | SubscriberQos | qos, |
SubscriberListener | listener, | ||
long | mask | ||
) |
This operation creates a Subscriber with the specified SubscriberQos and SubscriberListener. The value DDS.SUBSCRIBER_QOS_DEFAULT may be provided for the qos argument. This will indicate that the the default subscriber QoS settings held in the DomainParticipant should be used.
This operation may fail and return NULL if the QoS settings are internally inconsistent.
Topic create_topic | ( | String | topic_name, |
String | type_name, | ||
TopicQos | qos, | ||
TopicListener | listener, | ||
long | mask | ||
) |
This operation creates a Topic with the specified TopicQos settings and TopicListener.
The value DDS.TOPIC_QOS_DEFAULT may be provided for the qos argument. This will indicate that the the default topic QoS settings held in the DomainParticipant should be used.
The topic is created with a reference to the data type indicated by the type_name argument. The data type must have been registered with the DomainParticipant (by a call to register_type() on the appropriate TypeSupport object) prior to calling create_topic().
This operation may fail and return NULL if the QoS settings are internally inconsistent.
The topic returned from this operation (if not NULL) must be deleted by calling DomainParticipant.delete_topic().
ReturnCode_t delete_contained_entities | ( | ) |
This operation deletes all the objects created by means of the create operations on DomainParticipant dp. This routine will recursively call the corresponding delete_contained_entities() operation on each of the contained objects (Publishers, Subscribers, Topics, ContentFilteredTopics, and MultiTopics). If successful, this operation will recursively delete all objects contained with this DomainParticipant. After successful execution, the application may delete the DomainParticipant by calling DomainParticipantFactory.delete_participant().
If any of the objects cannot be deleted, this routine will return ReturnCode_t.RETCODE_PRECONDITION_NOT_MET.
ReturnCode_t delete_contentfilteredtopic | ( | ContentFilteredTopic | cft | ) |
This operation deletes a previously allocated ContentFilteredTopic. This operation will fail if there are any DataReader, DataWriter, ContentFilteredTopic, or MultiTopic objects that reference the specified Topic. In this case, the operation will return ReturnCode_t.RETCODE_PRECONDITION_NOT_MET.
The Topic must be owned by DomainPartipant dp; otherwise ReturnCode_t.RETCODE_PRECONDITION_NOT_MET will be returned.
ReturnCode_t delete_multitopic | ( | MultiTopic | a_multitopic | ) |
ReturnCode_t delete_publisher | ( | Publisher | p | ) |
This operation deletes an existing Publisher. A Publisher cannot be deleted if it contains any DataWriter objects. In this case, delete_publisher will return ReturnCode_t.RETCODE_PRECONDITION_NOT_MET.
If the DomainParticipant dp does not contain the provided Publisher p, the operation will return ReturnCode_t.RETCODE_PRECONDITION_NOT_MET.
ReturnCode_t delete_subscriber | ( | Subscriber | s | ) |
This operation deletes an existing Subscriber. A Subscriber cannot be deleted if it contains any DataReader objects. In this case, delete_subscriber will return ReturnCode_t.RETCODE_PRECONDITION_NOT_MET.
If the DomainParticipant dp does not contain the provided Subscriber s, the operation will return ReturnCode_t.RETCODE_PRECONDITION_NOT_MET.
ReturnCode_t delete_topic | ( | Topic | topic | ) |
This operation deletes a Topic. This operation will fail if there are any DataReader, DataWriter, ContentFilteredTopic, or MultiTopic objects that reference the specified Topic. In this case, the operation will return ReturnCode_t.RETCODE_PRECONDITION_NOT_MET.
The Topic must be owned by DomainPartipant dp; otherwise ReturnCode_t.RETCODE_PRECONDITION_NOT_MET will be returned.
ReturnCode_t do_work | ( | Duration_t | time_slice | ) |
Transfer control to the DomainParticipant so it can do background processing.
This function is to be called only if the DomainParticipant is configured to use NO threads via the thread_model QoS policy. The participant will continue to execute background processing until at least 'time_slice' time passes. This routine will attempt to use no more than 'time_slice' time, but this is not a guarantee.
ReturnCode_t enable | ( | ) |
Enables the DomainParticipant.
A DomainParticipant is created either enabled or not based on the DomainParticipantFactoryQoS setting entity_factory. When a DomainPartcipant is not enabled, only the following sub-set of all DomainParticipant operations are legal:
Any other DomainParticipant operation will return the ReturnCode_t.RETCODE_NOT_ENABLED error. DomainParticipant.enable() may be called on an already enabled DomainParticipant [it will have no effect].
Topic find_topic | ( | String | topic_name, |
Duration_t | timeout | ||
) |
This operation returns a Topic identified by the provided topic_name. If a topic with name topic_name is known to exist, the function returns this matching topic immediately. Otherwise, the operation will block for up to the timeout duration. If a topic with name topic_name is discovered or otherwise created, the operation will cease to wait, and will return the matching topic.
If a matching topic is not known by the time the timout has expired, the operation will return NULL.
Like DomainParticipant_create_topic(), the topic returned from this operation (if not NULL) must be deleted by calling DomainParticipant.delete_topic().
Subscriber get_builtin_subscriber | ( | ) |
Returns the built-in Subscriber.
Each DomainParticipant contains several built-in Topic objects as well as corresponding DataReader objects to access them. These built-in DataReader objects belong to the single built-in Subscriber that is accessed through this operation.
The built-in Topics are used to communicate information about other DomainParticipant, Topic, DataReader, and DataWriter objects.
An application should not explicitly delete the Subscriber returned by this operation - it is managed internally.
ReturnCode_t get_current_time | ( | Time_t | current_time | ) |
This operation returns the current value of the time used by the service.
ReturnCode_t get_default_publisher_qos | ( | PublisherQos | qos | ) |
Provides access to the default PublisherQos settings held in the factory. The provided qos argument is populated with the default qos settings.
ReturnCode_t get_default_subscriber_qos | ( | SubscriberQos | qos | ) |
Provides access to the default SubscriberQos settings held in the factory. The provided qos argument is populated with the default qos settings.
ReturnCode_t get_default_topic_qos | ( | TopicQos | qos | ) |
Provides access to the default TopicQos settings held in the factory. The provided qos argument is populated with the default qos settings.
ReturnCode_t get_discovered_participant_data | ( | ParticipantBuiltinTopicData | participant_data, |
InstanceHandle_t | participant_handle | ||
) |
This operation returns data that describes a particular discovered participant identified by participant_handle. An appropriate handle can be obtained through a call to DomainParticipant.get_discovered_participants().
If participant_handle does not identify a known DomainParticipant, this routine will return ReturnCode_t.RETCODE_PRECONDITION_NOT_MET.
ReturnCode_t get_discovered_participants | ( | InstanceHandleSeq | participant_handles | ) |
This operation returns the list of handles identifying the DomainParticipant objects that have been discovered. The returned list will include only participants which are in the same domain as participant d, and which are not explicitly ignored as a result of a call to DomainParticipant.ignore_participant().
ReturnCode_t get_discovered_topic_data | ( | TopicBuiltinTopicData | topic_data, |
InstanceHandle_t | topic_handle | ||
) |
This operation returns data that describes a particular discovered topic identified by topic_handle. An appropriate handle can be obtained through a call to DomainParticipant.get_discovered_topics().
If topic_handle does not identify a known Topic, this routine will return ReturnCode_t.RETCODE_PRECONDITION_NOT_MET.
ReturnCode_t get_discovered_topics | ( | Vector | topic_handles | ) |
This operation returns the list of handles identifying the Topic objects that have been discovered. The returned list will include only topics which are in the same domain as participant d, and which are not explicitly ignored as a result of a call to DomainParticipant.ignore_topic().
long get_domain_id | ( | ) |
Gets the domain_id to which the DomainParticipant belongs.
DomainParticipantListener get_listener | ( | ) |
This operation returns the currently installed DomainParticipantListener. Because the infrastructure makes a copy of the listener provided in DomainParticipant.set_listener(), the returned structure pointer will not match the pointer originally provided. However, the function pointers within the structure will match. Also, the application should not free the data referenced by the returned pointer.
ReturnCode_t get_qos | ( | DomainParticipantQos | qos | ) |
Gets the DomainParticipantQoS settings of the DomainParticipant.
ReturnCode_t ignore_participant | ( | InstanceHandle_t | handle | ) |
Instructs the DomainParticipant dp to ignore the external DomainParticipant identified by handle. This will cause the infrastructure to behave as if the external participant handle did not exist. The handle can be discovered by accessing the built-in topic DCPSParticipant via the appropriate built-in DataReader.
There is no mechanism to reverse this operation.
ReturnCode_t ignore_publication | ( | InstanceHandle_t | handle | ) |
This operation instructs the DomainParticipant dp to ignore a Publication identified by handle. The handle can be discovered by accessing the built-in topic DCPSPublication via the appropriate built-in DataReader.
There is no mechanism to reverse this operation.
ReturnCode_t ignore_subscription | ( | InstanceHandle_t | handle | ) |
This operation instructs the DomainParticipant dp to ignore a Subscription identified by handle. The handle can be discovered by accessing the built-in topic DCPSSubscription via the appropriate built-in DataReader.
There is no mechanism to reverse this operation.
ReturnCode_t ignore_topic | ( | InstanceHandle_t | handle | ) |
This operation instructs the DomainParticipant dp to ignore a Topic identified by handle. This can be used to save resources if a participant will never participate on certain Topics. The handle can be discovered by accessing the built-in topic DCPSTopic via the appropriate built-in DataReader.
There is no mechanism to reverse this operation.
TopicDescription lookup_topicdescription | ( | String | name | ) |
This operation returns an existing, locally-created TopicDescription, named name. If a TopicDescription named name does not exist, then this routine will return NULL.
ReturnCode_t register_type | ( | TypeSupport | ts, |
String | type_name | ||
) |
Registers a TypeSupport with the Participant.
Associates a TypeSupport object with the provided 'type_name'. This TypeSupport will be used to handle data that has a matching type_name. If a TypeSupport has already been registered for the provied type_name, and the new type does not match the previously registered type, then an error is returned and the previously registered TypeSupport is maintained. [Upon error, the new type is not registered.]
ReturnCode_t set_default_publisher_qos | ( | PublisherQos | qos | ) |
Sets the default PublisherQos held in the DomainParticipant. This default qos will be used during subsequent calls to DomainParticipant.create_publisher() if the special DDS.PUBLISHER_QOS_DEFAULT value is provided for qos. This routine may fail if the provided qos argument is not internally consistent. In this case, ReturnCode_t.RETCODE_INCONSISTENT_POLICY will be returned, and no changes will be made to the DomainParticipant.
ReturnCode_t set_default_subscriber_qos | ( | SubscriberQos | qos | ) |
Sets the default SubscriberQos held in the DomainParticipant. This default qos will be used during subsequent calls to DomainParticipant.create_subscriber() if the special DDS.SUBSCRIBER_QOS_DEFAULT value is provided for qos. This routine may fail if the provided qos argument is not internally consistent. In this case, ReturnCode_t.RETCODE_INCONSISTENT_POLICY will be returned, and no changes will be made to the DomainParticipant.
ReturnCode_t set_default_topic_qos | ( | TopicQos | qos | ) |
Sets the default TopicQos held in the DomainParticipant. This default qos will be used during subsequent calls to DomainParticipant.create_topic() [and related] if the special DDS.TOPIC_QOS_DEFAULT value is provided for qos. This routine may fail if the provided qos argument is not internally consistent. In this case, ReturnCode_t.RETCODE_INCONSISTENT_POLICY will be returned, and no changes will be made to the DomainParticipant.
ReturnCode_t set_listener | ( | DomainParticipantListener | new_listener, |
long | mask | ||
) |
This operation installs a DomainParticipantListener on the DomainParticipant. Only one listener may be attached to a DomainParticipant at a time. A call to set_listener() will replace any current listener with a_listener.
a_listener can be NULL, which indicates a listener that does nothing.
The infrastructure will make an internal copy of the listener structure so that it need not be persisted by the application.
ReturnCode_t set_qos | ( | DomainParticipantQos | qos | ) |
Sets the DomainParticipantQoS values. These QoS values affect the behavior of the DomainParticipant. This routine may fail if the provided qos argument is not internally consistent. In this case, ReturnCode_t.RETCODE_INCONSISTENT_POLICY will be returned, and no changes will be made to the DomainParticipant QoS.