PROPID_Q_MULTICAST_ADDRESS

 

Applies To: Windows 10, Windows 7, Windows 8, Windows 8.1, Windows Server 2008, Windows Server 2008 R2, Windows Server 2012, Windows Server 2012 R2, Windows Server Technical Preview, Windows Vista

(Introduced in MSMQ 3.0.) The PROPID_Q_MULTICAST_ADDRESS property specifies the IP multicast address associated with the queue.

Property ID

PROPID_Q_MULTICAST_ADDRESS

Type Indicator

VT_LPWSTR or VT_EMPTY

MQPROPVARIANT Field

pwszVal

Property Value

When the type indicator is set to VT_LPWSTR, the property value is a string containing a valid multicast address (in the form shown below).

<address>:<port>  

The address must be in the class D range from 224.0.0.0 to 239.255.255.255. However, only certain ranges of addresses in this range are unreserved and available for sending multicast messages. For the latest list of reserved multicast addresses, see the Internet Assigned Number Authority (IANA) Internet Multicast Addresses Web page. There are no restrictions on the port number.

When the type indicator is set to VT_EMPTY, the property value is meaningless and the queue is not associated with a multicast address.

Remarks

The PROPID_Q_MULTICAST_ADDRESS property is used to associate a nontransactional queue with a multicast address that can be used when sending messages. You cannot associate a transactional queue with a multicast address. When the sending application sends messages to a multicast address, Message Queuing sends a copy of the message to every queue associated with that address.

Note

If several source computers are sending multicast messages and you want a specific queue to receive messages from only one source computer, each source computer must send messages to a different combination of IP address and port number.

A queue can be associated with a multicast address when the queue is created or, after the queue has been created, with a call to MQSetQueueProperties.

To create a queue call MQCreateQueue. To change properties of existing queues call MQSetQueueProperties.

To disassociate an existing queue from a multicast address set the type indicator of PROPID_Q_MULTICAST_ADDRESS to VT_EMPTY and call MQSetQueueProperties.

To retrieve the multicast address with which a queue is associated, specify PROPID_Q_MULTICAST_ADDRESS in the MQQUEUEPROPS structure, call MQGetQueueProperties, and examine its returned value.

When retrieving the multicast address, the type indicator must be set to VT_NULL. Message Queuing automatically allocates memory for the wide-character string retrieved during the function call. After you no longer need the string, you must free the memory allocated for it using MQFreeMemory.

For more information on sending messages to multiple queues using multicast addresses, see Multicast addresses.

Equivalent COM Property

When using COM components, the multicast address associated with the queue can be set or retrieved using the MSMQQueueInfo.MulticastAddress property.

Example code

The following code fragments show how PROPID_Q_MULTICAST_ADDRESS is specified in arrays that can be used to initialize an MQQUEUEPROPS structure when you specify a multicast address, disassociate a queue from a multicast address, and retrieve the multicast address associated with the queue.

To Specify a Multicast Address

WCHAR AddressBuffer[]=L"224.0.0.255:80";  
aQueuePropId[i] = PROPID_Q_MULTICAST_ADDRESS;    // Property ID  
aQueuePropVar[i].vt = VT_LPWSTR;                 // Type indicator  
aQueuePropVar[i].pwszVal = &AddressBuffer;       // Multicast address  
i++;  

To Disassociate a Queue from a Multicast Address

aQueuePropId[i] = PROPID_Q_MULTICAST_ADDRESS;    // Property ID  
aQueuePropVar[i].vt = VT_EMPTY;                  // Type indicator  
i++;  

To Retrieve PROPID_Q_MULTICAST_ADDRESS

aQueuePropId[i] = PROPID_Q_MULTICAST_ADDRESS;    // Property ID  
aQueuePropVar[i].vt = VT_NULL;                   // Type indicator  
i++;  

The following examples are included in Using Message Queuing.

For an example of	See
Sending messages to multiple destinations using multicast addresses	C/C++ Code Example: Sending Messages Using Multicast Addresses
Setting and retrieving the multicast address associated with an existing queue	C/C++ Code Example: Setting PROPID_Q_MULTICAST_ADDRESS  C/C++ Code Example: Retrieving PROPID_Q_MULTICAST_ADDRESS

See Also

Queue Properties
MQCreateQueue
MQFreeMemory
MQQUEUEPROPS
MQSetQueueProperties
MSMQQueueInfo.MulticastAddress