PROPID_MGMT_QUEUE_NEXTHOPS
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
(Read-only, introduced in MSMQ 3.0.) The PROPID_MGMT_QUEUE_NEXTHOPS property returns the address or, if the queue is in the process of being connected, that is, in the WAITING state, a list of possible addresses, for routing messages to the destination queue in the next hop.
Property ID
PROPID_MGMT_QUEUE_NEXTHOPS
Type Indicator
VT_LPWSTR | VT_VECTOR
MQPROPVARIANT Field
calpwstr
Property Value
A counted array of pointers to strings containing an address or a list of possible addresses. Each string can be in one of the following formats:
IP = <IP address>
IPX = <IPX address>
FOREIGN = <GUID of foreign site or foreign CN>
Remarks
To retrieve the address or a list of possible addresses for routing messages to the destination queue in the next hop, include PROPID_MGMT_QUEUE_NEXTHOPS in the MQMGMTPROPS structure, and then call MQMgmtGetInfo.
This property can be retrieved only for an active queue. MQMgmetGetInfo will return a non-specific error (MQ_ERROR) if your application attempts to retrieve this information for a queue that does not contain messages and is not opened by an application.
When specifying PROPID_MGMT_QUEUE_NEXTHOPS in the MQMGMTPROPS structure, set its type indicator to VT_NULL. During the function call, Message Queuing automatically changes the type indicator to VT_LPWSTR | VT_VECTOR and creates the buffers needed to receive the property values. The number of possible addresses is returned in the cElems member of the calpwstr field of the applicable MQPROPVARIANT element in the property values array, and the addresses themselves are returned in the array of strings specified by the pElems member of the calpwstr field. After you no longer need the array of strings, you must free the memory allocated for it using MQFreeMemory.
Equivalent COM Property
When using COM components, you can retrieve the address or a list of possible addresses for routing messages to the destination queue in the next hop using the MSMQOutgoingQueueManagement.NextHops property.
Example Code
The following code fragment shows how PROPID_MGMT_QUEUE_NEXTHOPS is specified in arrays that can be used to initialize an MQMGMTPROPS structure.
aMgmtPropID[i] = PROPID_MGMT_QUEUE_NEXTHOPS; // Property identifier
aMgmtPropVar[i].vt = VT_NULL; // Type indicator
i++;
The following code fragment shows how to free the memory allocated for the array of strings.
for (j = 0; j < aMgmtPropVar[i].calpwstr.cElems; j++)
{
MQFreeMemory(aMgmtPropVar[i].calpwstr.pElems[j]); //Free each element
}
MQFreeMemory(aMgmtPropVar[i].calpwstr.pElems); //Free the array