7.5.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 20. Multi-channel DataWriters for complete documentation on multi-channel DataWriters.
Note: Durable writer history is not supported for multi-channel DataWriters; an error is reported if a multi-channel DataWriter tries to configure Durable Writer History.
This QosPolicy includes the members presented in Table 7.57 DDS_MultiChannelQosPolicy, Table 7.58 DDS_ChannelSettings_t, and Table 7.59 DDS_TransportMulticastSettings_t. For defaults and valid ranges, please refer to the API Reference HTML documentation.
|
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 7.58 DDS_ChannelSettings_t. |
|
char * |
filter_name |
Name of the filter class used to describe the filter expressions1 In Java and C#, you can access the names of the built-in filters by using DomainParticipant.SQLFILTER_NAME and DomainParticipant.STRINGMATCHFILTER_NAME.. The following values are supported: DDS_SQLFILTER_NAME (see 5.4.6 SQL Filter Expression Notation) DDS_STRINGMATCHFILTER_NAME (see 5.4.7 STRINGMATCH Filter Expression Notation) |
|
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. |
|
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 5.4.6 SQL Filter Expression Notation and 5.4.7 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 7.5.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. |
|
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 5.4.6 SQL Filter Expression Notation)
- DDS_STRINGMATCHFILTER_NAME (see 5.4.7 STRINGMATCH Filter Expression Notation
A DataReader can use the ContentFilteredTopic API (see 5.4.5 Using a ContentFilteredTopic) to subscribe to a subset of the channels used by a DataWriter.
7.5.16.1 Example
See 20. Multi-channel DataWriters.
7.5.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.
7.5.16.3 Related Qos Policies
7.5.16.4 Applicable Entities
7.5.16.5 System Resource Considerations
The following fields in the 9.5.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 20. Multi-channel DataWriters.
© 2020 RTI