Domains

group domain

Defines

DDS_DOMAIN_DEFAULT

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.

It will not be created if a domain with the given domain id already exists. This could have been created implicitly by a dds_create_participant().

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

domain_id	domain id in config	result
n	any (or absent)	n, config is used
n	m == n	n, config is used
n	m != n	n, config is ignored: default

Config models:

1. <CycloneDDS>
      <Domain id="X">...</Domain>
      <!-- <Domain .../> -->
    </CycloneDDS>
   

   where … is all that can today be set in children of CycloneDDS with the exception of the id

2. <CycloneDDS>
      <Domain><Id>X</Id></Domain>
      <!-- more things here ... -->
   </CycloneDDS>
   

   Legacy form, domain id must be the first element in the file with a value (if nothing has been set previously, it a warning is good enough)

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

Parameters

• domain – [in] The domain to be created. 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.

It will not be created if a domain with the given domain id already exists. This could have been created implicitly by a dds_create_participant().

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

Parameters

• domain – [in] The domain to be created. 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.

If domain is set (not DDS_DOMAIN_DEFAULT) then it must match if the domain has also been configured or an error status will be returned. Currently only a single domain can be configured by providing configuration file. If no configuration file exists, the default domain is configured as 0.

Parameters

• domain – [in] The domain in which to create the participant (can be DDS_DOMAIN_DEFAULT). DDS_DOMAIN_DEFAULT is for using the domain in the configuration.

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