CoreDX DDS C Reference Manual
|
The DDS_DomainParticipant is used to configure, create and destroy Publisher, Subscriber and Topic objects. More...
The DDS_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.
|
related |
Provide a block of memory for CoreDX DDS to use.
On CoreDX DDS builds configured to not use Heap memory allocation routines from the Operating System (common for embedded or Safety Critical environments), this routine is used to assign a block of memory for CoreDX DDS usage. All memory required by CoreDX DDS will be constrained to this block of memory, and no other memory resources will be used.
| DDS_RETCODE_OK | on success |
| DDS_RETCODE_BAD_PARAMETER | if 'size == 0' or 'heap_ptr == NULL' |
| DDS_RETCODE_UNSUPPORTED | if the build is configured to use the Heap from the OS. |
|
related |
Adds the provided transport to the DomainParticipant.
The transport is registered with the DomainParticipant, and will be used for communication. If no transports are manually added, then the DomainParticipant will automatically add the default UDP transport. The DomainParticipant takes ownership of the provided transport; when the DomainParticipant is deleted, it will release the resources of all added transports.
|
related |
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 DDS_MANUAL_BY_PARTICIPANT. In this case, the operation will assert the liveliness of those particular DataWriter objects.
|
related |
Tests the provided version information against the version of the running CoreDX DDS library.
If the provided major and minor numbers match those of the running library, then the routine returns 0. If the provided numbers are larger than those of the running library, then the routine returns a positive number (indicating that the provided version is greater than the library version). Finaly, if the provied version is less than the library version, a negative number is returned. Currently, the 'patch' value is ignored.
|
related |
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.
|
related |
This operation creates a ContentFilteredTopic.
The ContentFilteredTopic is associated with another un-filtered topic related_topic. It applies a filter to the data of the related topic. If a data sample passes the filter, it will be made available to a DataReader associated with the ContentFilteredTopic.
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).
CoreDX DDS supports the 'LIKE' operator (and NOT LIKE) for regular expression string matching. The pattern string in a LIKE clause can contain '' to match zero or more characters, '_' to match a single character, or '[<characters>]' to match a range of characters.
CoreDX DDS also includes support for the 'IN' operator. This provides a very powerful mechanism for testing that a value appears in a set of values. For example "symbol IN ('ge', 'msft', 'ibm')" will select all samples that have a symbol value of 'ge', 'msft', or 'ibm'. This could also be written as a series of equality tests combined with the OR operator; however, the IN operator is much more efficient. A filter that matches on several hundred or even thousands of values can be implemented very efficiently using the 'IN' operator.
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.
|
related |
|
related |
This operation creates a DDS_Publisher with the specified DDS_PublisherQoS settings and DDS_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.
|
related |
This operation creates a DDS_Subscriber with the specified DDS_SubscriberQos and DDS_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.
|
related |
This operation creates a DDS_Topic with the specified DDS_TopicQos settings and DDS_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 DDS_DomainParticipant_delete_topic().
|
related |
Construct a TypeSupport to handle the type identified by the provided TypecodeQosPolicy.
A discovered publication or subscription may include type information in the TypecodeQosPolicy. This type information can be used to create a TypeSupport for use by CoreDX DDS. The application can use this TypeSupport to register a type, create a Topic, and create DataReaders and DataWriters. The TypecodeQosPolicy can hold either a 'TypeCode' or a 'TypeObject' type representation.
This routine can be successful only if the TypecodeQosPolicy holds a 'TypeCode'; otherwise, it returns DDS_RETCODE_BAD_PARAMETER.
|
related |
Construct a TypeSupport to handle the type identified by the provided TypecodeQosPolicy.
A discovered publication or subscription may include type information in the TypecodeQosPolicy. This type information can be used to create a TypeSupport for use by CoreDX DDS. The application can use this TypeSupport to register a type, create a Topic, and create DataReaders and DataWriters. The TypecodeQosPolicy can hold either a 'TypeCode' or a 'TypeObject' type representation.
This routine can be successful only if the TypecodeQosPolicy holds a 'TypeObject'; otherwise, it returns DDS_RETCODE_BAD_PARAMETER.
|
related |
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 DDS_DomainParticipantFactory_delete_participant().
If any of the objects cannot be deleted, this routine will return DDS_RETCODE_PRECONDITION_NOT_MET.
|
related |
This operation deletes a previously allocated ContentFilteredTopic.
This operation will fail if there are any DDS_DataReader, DDS_DataWriter, DDS_ContentFilteredTopic, or DDS_MultiTopic objects that reference the specified Topic. In this case, the operation will return DDS_RETCODE_PRECONDITION_NOT_MET.
The Topic must be owned by DomainPartipant dp; otherwise DDS_RETCODE_PRECONDITION_NOT_MET will be returned.
|
related |
|
related |
This operation deletes an existing DDS_Publisher.
A Publisher cannot be deleted if it contains any DDS_DataWriter objects. In this case, delete_publisher will return DDS_RETCODE_PRECONDITION_NOT_MET.
If the DomainParticipant dp does not contain the provided Publisher p, the operation will return DDS_RETCODE_PRECONDITION_NOT_MET.
|
related |
This operation deletes an existing DDS_Subscriber.
A Subscriber cannot be deleted if it contains any DDS_DataReader objects. In this case, delete_subscriber will return DDS_RETCODE_PRECONDITION_NOT_MET.
If the DomainParticipant dp does not contain the provided Subscriber s, the operation will return DDS_RETCODE_PRECONDITION_NOT_MET.
|
related |
This operation deletes a DDS_Topic.
This operation will fail if there are any DDS_DataReader, DDS_DataWriter, DDS_ContentFilteredTopic, or DDS_MultiTopic objects that reference the specified Topic. In this case, the operation will return DDS_RETCODE_PRECONDITION_NOT_MET.
The Topic must be owned by DomainPartipant dp; otherwise DDS_RETCODE_PRECONDITION_NOT_MET will be returned.
|
related |
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.
|
related |
Enables the DomainParticipant.
A DomainParticipant is created either enabled or not based on the DDS_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 DDS_NOT_ENABLED error. DDS_DomainParticipant_enable() may be called on an already enabled DomainParticipant [it will have no effect].
| DDS_RETCODE_OK | if the Participant is enabled OK. |
| DDS_RETCODE_ERROR | if all installed transports failled to initialize successfully. |
| DDS_RETCODE_BAD_PARAMETER | if a null 'dp' value is passed in. |
|
related |
This operation returns a DDS_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 DDS_DomainParticipant_create_topic(), the topic returned from this operation (if not NULL) must be deleted by calling DDS_DomainParticipant_delete_topic().
|
related |
Returns the built-in DDS_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 DDS_DomainParticipant, DDS_Topic, DDS_DataReader, and DDS_DataWriter objects.
An application should not explicitly delete the Subscriber returned by this operation - it is managed internally.
|
related |
Provides access to the default DDS_PublisherQos settings held in the factory.
The provided qos argument is populated with the default qos settings.
|
related |
Provides access to the default DDS_SubscriberQos settings held in the factory.
The provided qos argument is populated with the default qos settings.
|
related |
Provides access to the default DDS_TopicQos settings held in the factory.
The provided qos argument is populated with the default qos settings.
|
related |
This operation returns data that describes a particular discovered participant identified by participant_handle.
An appropriate handle can be obtained through a call to DDS_DomainParticipant_get_discovered_participants().
If participant_handle does not identify a known DomainParticipant, this routine will return DDS_RETCODE_PRECONDITION_NOT_MET. To reclaim any memory returned in the participant_data paramter, call DDS_DCPSParticipant_clear(participant_data).
|
related |
This operation returns the list of handles identifying the DDS_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 DDS_DomainParticipant_ignore_participant().
This routine allocates memory to populate the participant_handles sequence. The application is responsible for freeing this memory.
|
related |
This operation returns data that describes a particular known DataWriter identified by publication_handle.
An appropriate handle can be obtained through a call to DDS_DataReader_get_matched_publications().
If publication_handle does not identify a known DataWriter, this routine will return DDS_RETCODE_PRECONDITION_NOT_MET. To reclaim any memory returned in the 'publication_data' parameter, call DDS_DCPSPublication_clear(publication_data).
|
related |
This operation returns data that describes a particular known DataReader identified by subscription_handle.
An appropriate handle can be obtained through a call to DDS_DataWriter_get_matched_subscriptions().
If subscription_handle does not identify a known DataReader, this routine will return DDS_RETCODE_PRECONDITION_NOT_MET. To reclaim any memory returned in the 'subscription_data' parameter, call DDS_DCPSSubscription_clear(subscription_data).
|
related |
This operation returns data that describes a particular discovered topic identified by topic_handle.
An appropriate handle can be obtained through a call to DDS_DomainParticipant_get_discovered_topics().
If topic_handle does not identify a known Topic, this routine will return DDS_RETCODE_PRECONDITION_NOT_MET.
|
related |
This operation returns the list of handles identifying the DDS_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 DDS_DomainParticipant_ignore_topic().
This routine allocates memory to populate the topic_handles sequence. The application is responsible for freeing this memory.
|
related |
This operation returns the currently installed DDS_DomainParticipantListener.
|
related |
This operation returns the currently installed DDS_DomainParticipantListener_cd.
|
related |
This returns the list of triggered communication statuses in the DomainParticipant.
If the DomainParticipant is not enabled, all statuses will be untriggered. The list returned by get_status_changes may be empty. The list of statuses returned by get_status_changes operation contains statuses that are triggered on the DomainParticipant itself and does not include statuses from contained objects.
|
related |
This operation allows access to the DDS_StatusCondition associated with the DomainParticipant.
The returned condition can be added to a DDS_WaitSet.
|
related |
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.
|
related |
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.
|
related |
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.
|
related |
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.
|
related |
This operation returns an existing, locally-created DDS_TopicDescription, named name.
If a TopicDescription named name does not exist, then this routine will return NULL.
|
related |
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, then an error is returned and the previously registered TypeSupport is maintained.
|
related |
Sets the default DDS_PublisherQos held in the DomainParticipant.
This default qos will be used during subsequent calls to DDS_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, DDS_INCONSISTENT_POLICY will be returned, and no changes will be made to the DomainParticipant.
|
related |
Sets the default DDS_SubscriberQos held in the DomainParticipant.
This default qos will be used during subsequent calls to DDS_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, DDS_INCONSISTENT_POLICY will be returned, and no changes will be made to the DomainParticipant.
|
related |
Sets the default DDS_TopicQos held in the DomainParticipant.
This default qos will be used during subsequent calls to DDS_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, DDS_INCONSISTENT_POLICY will be returned, and no changes will be made to the DomainParticipant.
|
related |
This operation installs a DDS_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.
|
related |
This operation installs a DDS_DomainParticipantListener_cd on the DomainParticipant.
Only one listener may be attached to a DomainParticipant at a time. A call to set_listener_cd() will replace any current listener with a_listener.
a_listener can be NULL, which indicates a listener that does nothing.
The infrastructure does not make an internal copy of the listener structure which means that it must persisted by the application.
|
related |
Sets the DDS_DomainParticipantQoS values.
These QoS values affect the behavior of the DomainParticipant.
|
related |
Tests the provided version information against the version of the running CoreDX DDS library.
Returns the same values as DDS_DomainParticpant_check_version. Also will print an error to standard error if the provided version does not match the running library version. The printed error message will contain the string in 'source' for reference.
