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 Multi-channel DataWriters for complete documentation on multi-channel DataWriters.

Note:Durable writer history is not supported for multi-channel DataWriters (see 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 , , and . For defaults and valid ranges, please refer to the API Reference HTML documentation.

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 .
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 SQL Filter Expression Notation) DDS_STRINGMATCHFILTER_NAME (see STRINGMATCH Filter Expression Notation)

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 to four. (A locator is defined by a transport alias, a multicast address and a port.) See .
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 SQL Filter Expression Notation and 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 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 Prioritized DDS Samples. Note: Prioritized DDS samples are not supported when using the Java, Ada, or .NET APIs. Therefore the priority field does not exist when using these APIs.

 

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 SQL Filter Expression Notation)
• DDS_STRINGMATCHFILTER_NAME (see STRINGMATCH Filter Expression Notation

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

Example

See Multi-channel DataWriters.

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.

Related Qos Policies

• DOMAIN_PARTICIPANT_RESOURCE_LIMITS QosPolicy (DDS Extension)

Applicable Entities

• DataWriters

System Resource Considerations

The following fields in the 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 Multi-channel DataWriters.

© 2016 RTI