PROPID_Q_LABEL

  • Article

 

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

(Optional.) The PROPID_Q_LABEL property specifies a description of the queue.

Property ID

PROPID_Q_LABEL

Type Indicator

VT_LPWSTR

MQPROPVARIANT Field

pwszVal

Property Value

String (the default is ""). The maximum length of the string is MQ_MAX_Q_LABEL_LEN (124 Unicode characters).

Remarks

The label of a queue is used to identify the queue.

For public queues, the label can be used as the search criteria for a query. By using the same label for several queues, the application can later run a query on the queue label and locate all the queues. (A query can also be used to retrieve the label of a public queue.)

To specify the label of a queue when creating a queue, specify PROPID_Q_LABEL in the MQQUEUEPROPS structure and call MQCreateQueue.

To change the label of a queue, specify PROPID_Q_LABEL in the MQQUEUEPROPS structure and call MQSetQueueProperties.

To retrieve the label of a queue, specify PROPID_Q_LABEL in the MQQUEUEPROPS structure, call MQGetQueueProperties, and examine its returned value.

When specifying PROPID_Q_LABEL, set the type indicator for PROPID_Q_LABEL to VT_NULL. Message Queuing will automatically allocate memory for the wide-character string retrieved during the function call. After you no longer need the label buffer, you must free the memory allocated for it using MQFreeMemory.

Equivalent COM Property

When using COM components, the label of the queue can be set and retrieved using the MSMQQueueInfo.Label property.

Example Code

The following code fragments show how PROPID_Q_LABEL is specified in arrays that can be used to initialize an MQQUEUEPROPS structure for setting and retrieving the label of a queue.

To Set the Label of a Queue

LPWSTR wszQueueLabel = L"Test Queue";  
aQueuePropID[i] = PROPID_Q_LABEL;               // Property identifier  
aQueuePropVar[i].vt = VT_LPWSTR;                // Type indicator  
aQueuePropVar[i].pwszVal = wszQueueLabel ;      // Label of queue

To Retrieve the Label of a Queue

aQueuePropID[i] = PROPID_Q_LABEL;               // Property identifier  
aQueuePropVar[i].vt = VT_NULL;                  // Type indicator  
i++;

The following examples are included in Using Message Queuing.

For an example of See
Setting the queue label when creating a queue C/C++ Code Example: Creating a Queue
Setting and retrieving the label of an existing queue C/C++ Code Example: Setting PROPID_Q_LABEL

 C/C++ Code Example: Retrieving PROPID_Q_LABEL

See Also

Queue Properties
MQCreateQueue
MQFreeMemory
MQGetQueueProperties
MQQUEUEPROPS
MQSetQueueProperties