MULTI_CHANNEL QosPolicy (DDS Extension)

47.16 MULTI_CHANNEL QosPolicy (DDS Extension)

This QosPolicy is used to partition the data published by a DataWriter across multiple channels. A channel is defined by a filter expression and a sequence of multicast locators.

By using this QosPolicy, a DataWriter can be configured to send data to different multicast groups based on the content of the data. Using syntax similar to those used in Content-Based Filters, you can associate different multicast addresses with filter expressions that operate on the values of the fields within the data. When your application’s code calls write(), data is sent to any multicast address for which the data passes the filter.

See Chapter 36 Multi-Channel DataWriters for High-Performance Filtering for complete documentation on MultiChannel DataWriters.

Note: Durable writer history is not supported for MultiChannel DataWriters; an error is reported if a MultiChannel DataWriter tries to configure Durable Writer History.

This QosPolicy includes the members presented in Table 47.29 DDS_MultiChannelQosPolicy, Table 47.30 DDS_ChannelSettings_t, and Table 47.31 DDS_TransportMulticastSettings_t. For defaults and valid ranges, please refer to the API Reference HTML documentation.

Table 47.29 DDS_MultiChannelQosPolicy
Type	Field Name	Description
DDS_ChannelSettingsSeq	channels	A sequence of channel settings used to configure the channels’ properties. If the length of the sequence is zero, the QosPolicy will be ignored. See Table 47.30 DDS_ChannelSettings_t.
char *	filter_name	Name of the filter class used to describe the filter expressions1. The following values are supported: DDS_SQLFILTER_NAME (see 35.5 SQL Filter Expression Notation) DDS_STRINGMATCHFILTER_NAME (see 35.6 STRINGMATCH Filter Expression Notation) More details are described in the API Reference HTML documentation.

Table 47.30 DDS_ChannelSettings_t
Type	Field Name	Description
DDS_TransportMulticastSettingsSeq	multicast_settings	A sequence of multicast settings used to configure the multicast addresses associated with a channel. The sequence cannot be empty. The maximum number of multicast locators in a channel is limited by default to 16. This is a hard limit that cannot be increased. However, this limit can be decreased by configuring the DomainParticipant property dds.domain_participant.max_announced_locator_list_size. See Table 47.31 DDS_TransportMulticastSettings_t.
char *	filter_expression	A logical expression used to determine the data that will be published in the channel. This string cannot be NULL. An empty string always evaluates to TRUE. See 35.5 SQL Filter Expression Notation and 35.6 STRINGMATCH Filter Expression Notation for expression syntax.
DDS_Long	priority	A positive integer designating the relative priority of the channel, used to determine the transmission order of pending transmissions. Larger numbers have higher priority. To use publication priorities, the DataWriter’s 47.20 PUBLISH_MODE QosPolicy (DDS Extension) must be set for asynchronous publishing and the DataWriter must use a FlowController that is configured for highest-priority-first (HPF) scheduling. See 34.4.4 Prioritized DDS Samples.

Table 47.31 DDS_TransportMulticastSettings_t
Type	Field Name	Description
DDS_StringSeq	transports	A sequence of transport aliases that specifies which transport should be used to publish multicast messages for this channel.
char *	receive_address	A multicast group address on which DataReaders subscribing to this channel will receive data.
DDS_Long	receive_port	The multicast port on which DataReaders subscribing to this channel will receive data.

The format of the filter_expression should correspond to one of the following filter classes:

DDS_SQLFILTER_NAME (see 35.5 SQL Filter Expression Notation)
DDS_STRINGMATCHFILTER_NAME (see 35.6 STRINGMATCH Filter Expression Notation

A DataReader can use the ContentFilteredTopic API (see 35.4 Using a ContentFilteredTopic) to subscribe to a subset of the channels used by a DataWriter.

47.16.1 Example

See Chapter 36 Multi-Channel DataWriters for High-Performance Filtering.

47.16.2 Properties

This QosPolicy cannot be modified after the DataWriter is created.

It does not apply to DataReaders, so there is no requirement that the publishing and subscribing sides use compatible values.

47.16.3 Related Qos Policies

44.4 DOMAIN_PARTICIPANT_RESOURCE_LIMITS QosPolicy (DDS Extension)

47.16.4 Applicable Entities

Chapter 31 DataWriters

47.16.5 System Resource Considerations

The following fields in the 44.4 DOMAIN_PARTICIPANT_RESOURCE_LIMITS QosPolicy (DDS Extension) configure the resources associated with the channels stored in the MULTI_CHANNEL QosPolicy:

channel_seq_max_length
channel_filter_expression_max_length

For information about partitioning topic data across multiple channels, please refer to Chapter 36 Multi-Channel DataWriters for High-Performance Filtering.