MSMQQueueInfo.MulticastAddress

 

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 MulticastAddress property of the MSMQQueueInfo object specifies the multicast address associated with the queue.

Data type:	String
Run-time access:	Read/write

Property MulticastAddress As String  

Property Value

A string containing a valid multicast address (in the form shown below) or a zero-length string. A zero-length string "" indicates that the queue is not associated with a multicast address.

<address>:<port>  

Remarks

The MulticastAddress 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.

IP multicast addresses must be in the class D range from 224.0.0.0 to 239.255.255.255, which corresponds to setting the first four high-order bits equal to 1110. 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.

Note that 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.

The MSMQQueueInfo.MulticastAddress property can be used as search criteria when making a query of existing public queues. See the MSMQQuery.LookupQueue method for details on running a query.

To specify the multicast address when creating the queue, set the MSMQQueueInfo.PathName property and the MulticastAddress property, and then call the MSMQQueueInfo.Create method.

To reset or retrieve the multicast address of an existing queue, your application must first obtain an MSMQQueueInfo object that represents the queue. This object can be returned by a query using the MSMQQuery.LookupQueue method or created by the sending or receiving application.

Before using an application-created MSMQQueueInfo object, the application must initialize it to reference the queue by setting its MSMQQueueInfo.PathName or MSMQQueueInfo.FormatName property. For public queues, setting the FormatName property with a cached public format name instead of the PathName property frees Message Queuing from the need to retrieve information stored in the directory service to generate this format name. Direct format names can be used only for local private queues.

To reset the multicast address of an existing queue, set MulticastAddress to a new value and call the MSMQQueueInfo.Update method. This method updates the queue information stored by Message Queuing. For public queues, this information is stored in the directory service. For private queues, this information is stored on the computer where the messages of the queue are stored.

To retrieve the stored multicast address of a queue, call the MSMQQueueInfo.Refresh method and inspect the MulticastAddress property. The property values of the MSMQQueueInfo object are not updated with the values stored by Message Queuing until the MSMQQueueInfo.Refresh method is called.

To dissociate a queue from a multicast address, set the MulticastAddress property to a zero-length string.

Message Queuing COM components ignore any characters that follow the first Null character in a string without returning an error.

In C++ COM applications, you must use a smart pointer to the IMSMQQueueInfo3 interface to expose the MulticastAddress property.

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

Equivalent API Function Property

With function calls, the equivalent property is PROPID_Q_MULTICAST_ADDRESS.

Example Code

The following code fragment dissociates a specified queue from a multicast address.

Dim qinfo as New MSMQQueueInfo  
qinfo.Pathname = ".\testqueue"  
qinfo.Refresh  
qinfo.MulticastAddress = ""  
qinfo.Update  

The following examples are included in Using Message Queuing.

For an example of	See
Sending messages to queues associated with a multicast address	Visual Basic Code Example: Sending Messages Using Multicast Addresses
Setting and retrieving the multicast address associated of an existing queue	Visual Basic Code Example: Setting MSMQQueueInfo.MulticastAddress  Visual Basic Code Example: Retrieving MSMQQueueInfo.MulticastAddress

Requirements

Windows NT/2000/XP: Included in Windows XP and Windows Server 2003.

Windows 95/98/Me: Unsupported.

Header: Declared in Mqoai.h.

Library: Use Mqoa.lib.

See Also

MSMQQuery.LookupQueue
MSMQQueueInfo
MSMQQueueInfo.Create
MSMQQueueInfo.Refresh
MSMQQueueInfo.Update
PROPID_Q_MULTICAST_ADDRESS