Domains

group domain

Defines

DDS_DOMAIN_DEFAULT ((uint32_t) 0xffffffffu)

Select the default domain.

Typedefs

typedef uint32_t dds_domainid_t

Domain IDs are 32 bit unsigned integers.

Functions

dds_entity_t dds_create_domain(const dds_domainid_t domain, const char *config)

Creates a domain with a given configuration

To explicitly create a domain based on a configuration passed as a string. A domain created in this manner must be explicitly deleted by calling dds_delete on the domain (or on DDS_CYCLONEDDS_HANDLE).

It will not be created if a domain with the given domain id already exists. This could have been created implicitly by a previous call to this function, dds_create_participant or dds_create_domain_with_rawconfig.

The domain configuration is constructed by amending the default configuration with the Domain configuration (fragments) for which the domain id is specifed as “any” and those for which the domain id matches the specified domain id in the order in which they are encountered in the configuration.

Using NULL or “” as config will create a domain with default settings.

Parameters

  • domain – [in] The domain to be created. DDS_DEFAULT_DOMAIN is not allowed.

  • config – [in] A configuration string containing file names and/or XML fragments representing the configuration.

Return values

  • DDS_RETCODE_BAD_PARAMETER – Illegal value for domain id or the configfile parameter is NULL.

  • DDS_RETCODE_PRECONDITION_NOT_MET – The domain already existed and cannot be created again.

  • DDS_RETCODE_ERROR – An internal error has occurred.

Returns

A valid entity handle or an error code.

dds_entity_t dds_create_domain_with_rawconfig(const dds_domainid_t domain, const struct ddsi_config *config)

Creates a domain with a given configuration, specified as an initializer (unstable interface)

To explicitly create a domain based on a configuration passed as a raw initializer rather than as an XML string. This allows bypassing the XML parsing, but tightly couples the initializing to implementation. See dds/ddsi/ddsi_config.h:ddsi_config_init_default for a way to initialize the default configuration. A domain created in this manner must be explicitly deleted by calling dds_delete on the domain (or on DDS_CYCLONEDDS_HANDLE).

It will not be created if a domain with the given domain id already exists. This could have been created implicitly by a previous call to this function, dds_create_participant or dds_create_domain_with_rawconfig.

Please be aware that the given domain_id always takes precedence over the configuration.

Parameters

  • domain – [in] The domain to be created. DDS_DEFAULT_DOMAIN is not allowed.

  • config – [in] A configuration initializer. The lifetime of any pointers in config must be at least that of the lifetime of the domain.

Return values

  • DDS_RETCODE_BAD_PARAMETER – Illegal value for domain id or the config parameter is NULL.

  • DDS_RETCODE_PRECONDITION_NOT_MET – The domain already existed and cannot be created again.

  • DDS_RETCODE_ERROR – An internal error has occurred.

Returns

A valid entity handle or an error code.

dds_return_t dds_lookup_participant(dds_domainid_t domain_id, dds_entity_t *participants, size_t size)

Get participants of a domain.

This operation acquires the participants created on a domain and returns the number of found participants.

This function takes a domain id with the size of pre-allocated participant’s list in and will return the number of found participants. It is possible that the given size of the list is not the same as the number of found participants. If less participants are found, then the last few entries in an array stay untouched. If more participants are found and the array is too small, then the participants returned are undefined.

Parameters

  • domain_id – [in] The domain id.

  • participants – [out] The participant for domain.

  • size – [in] Size of the pre-allocated participant’s list.

Return values

  • >0 – Number of participants found.

  • DDS_RETCODE_ERROR – An internal error has occurred.

  • DDS_RETCODE_BAD_PARAMETER – The participant parameter is NULL, while a size is provided.

Returns

Number of participants found or and error code.

Domain Participant

group domain_participant

Functions

dds_entity_t dds_create_participant(const dds_domainid_t domain, const dds_qos_t *qos, const dds_listener_t *listener)

Creates a new instance of a DDS participant in a domain

This function creates a new participant in the specified domain id, implicitly creating a domain entity if one doesn’t exist for the specified domain id. The domain entity can exist as a consequence of the existence of another participant in it, or because it was explicitly created using dds_create_domain or dds_create_domain_with_rawconfig. If the domain entity has not been created yet, a new domain entity is created using a configuration taken from the CYCLONEDDS_URI environment variable.

The domain id may be specified as DDS_DOMAIN_DEFAULT, in which case the behaviour depends on whether some domain entity already exists or not. If there is at least one, the one with the lowest id will be used. If there are none, one is created with the domain id taken from the first domain id specified in the configuration file (i.e., with a Domain element with the id attribute not “any”), and if no domain id is specified in the configuration file, domain id 0 is used.

The domain configuration is constructed by amending the default configuration with the Domain configuration (fragments) for which the domain id is specifed as “any” and those for which the domain id matches the specified domain id (not DDS_DOMAIN_DEFAULT) in the order in which they are encountered in the configuration.

Parameters

  • domain – [in] The domain in which to create the participant.

  • qos – [in] The QoS to set on the new participant (can be NULL).

  • listener – [in] Any listener functions associated with the new participant (can be NULL).

Return values

  • >0 – A valid participant handle.

  • DDS_RETCODE_NOT_ALLOWED_BY_SECURITY – An invalid DDS Security configuration was specified (whether that be missing or incorrect entries, expired certificates, or anything else related to the security settings and implementation).

  • DDS_RETCODE_PRECONDITION_NOT_MET – Some security properties specified in the QoS, but the Cyclone build does not include support for DDS Security.

  • DDS_RETCODE_OUT_OF_RESOURCES – Some resource limit (maximum participants, memory, handles, &c.) prevented creation of the participant.

  • DDS_RETCODE_ERROR – The “CYCLONEDDS_URI” environment variable lists non-existent or invalid configuration files, or contains invalid embedded configuration items; or an unspecified internal error has occurred.

Returns

A valid participant handle or an error code.