Peer Descriptor Format

You are here: Part 3: Advanced Concepts > Discovery > Configuring the Peers List Used in Discovery > Peer Descriptor Format

Peer Descriptor Format

A peer descriptor string specifies a range of participants at a given locator. Peer descriptor strings are used in the DISCOVERY QosPolicy (DDS Extension) initial_peers field (see Setting the ‘Initial Peers’ List) and the DomainParticipant’s add_peer() and remove_peer() operations (see Adding and Removing Peers List Entries).

The anatomy of a peer descriptor is illustrated in Example Peer Descriptor Address Strings using a special "StarFabric" transport example.

Figure 1 Example Peer Descriptor Address Strings

A peer descriptor consists of:

[optional] A participant ID limit. If a simple integer is specified, it indicates the maximum participant ID to be contacted by the Connext DDS discovery mechanism at the given locator. If that integer is enclosed in square brackets (e.g., [2]), then only that Participant ID will be used. You can also specify a range in the form of [a-b]: in this case only the Participant IDs in that specific range are contacted. If omitted, a default value of 4 is implied and participant IDs 0, 1, 2, 3, and 4 will be contacted.
A locator, as described in Locator Format.

These are separated by the '@' character. The separator may be omitted if a participant ID limit is not explicitly specified.

The "participant ID limit" only applies to unicast locators; it is ignored for multicast locators (and therefore should be omitted for multicast peer descriptors).

Locator Format

A locator string specifies a transport and an address in string format. Locators are used to form peer descriptors. A locator is equivalent to a peer descriptor with the default participant ID limit (4).

A locator consists of:

[optional] Transport name (alias or class). This identifies the set of transport plug-ins (transport aliases) that may be used to parse the address portion of the locator. Note that a transport class name is an implicit alias used to refer to all the transport plug-in instances of that class.
[optional] An address, as described in Address Format.

These are separated by the "://" string. The separator is specified if and only if a transport name is specified.

If a transport name is specified, the address may be omitted; in that case all the unicast addresses (across all transport plug-in instances) associated with the transport class are implied. Thus, a locator string may specify several addresses.

If an address is specified, the transport name and the separator string may be omitted; in that case all the available transport plug-ins for the Entity may be used to parse the address string.

The transport names for the built-in transport plug-ins are:

shmem - Shared Memory Transport
udpv4 - UDPv4 Transport
udpv6 - UDPv6 Transport

Address Format

An address string specifies a transport-independent network address that qualifies a transport-dependent address string. Addresses are used to form locators. Addresses are also used in the DISCOVERY QosPolicy (DDS Extension) multicast_receive_addresses and the DDS_TransportMulticastSettings_t::receive_address fields. An address is equivalent to a locator in which the transport name and separator are omitted.

An address consists of:

[optional] A network address in IPv4 or IPv6 string notation. If omitted, the network address of the transport is implied.
[optional] A transport address, which is a string that is passed to the transport for processing. The transport maps this string into NDDS_Transport_Property_t::address_bit_count bits. If omitted, the network address is used as the fully qualified address.

The network and transport addressed are separated by the '#' character. If a separator is specified, it must be followed by a non-empty string that is passed to the transport plug-in. If the separator is omitted, it is treated as a transport address with an implicit network address (of the transport plugin). The implicit network address is the address used when registering the transport: e.g., the UDPv4 implicit network address is 0.0.0.0.0.0.0.0.0.0.0.0.

The bits resulting from the transport address string are prepended with the network address. The least significant NDDS_Transport_Property_t::address_bit_count bits of the network address are ignored.