PROPID_M_LABEL

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

The PROPID_M_LABEL property specifies a label of the message.

Property ID

PROPID_M_LABEL

Type Indicator

VT_LPWSTR

MQPROPVARIANT Field

pwszVal

Property Value

Arbitrary string (the default is none). The maximum length is MQ_MAX_MSG_LABEL_LEN (250 Unicode characters, including the end-of-string character).

Remarks

If the sending application specifies a message label longer than 250 Unicode characters (MQ_MAX_MSG_LABEL_LEN), Message Queuing returns an MQ_ERROR_LABEL_TOO_LONG error to the aStatus array.

To send a label with a message, specify PROPID_M_LABEL in the MQMSGPROPS structure and call MQSendMessage.

To retrieve the label of a message, create a buffer that can hold up to 250 Unicode characters (MQ_MAX_MSG_LABEL_LEN), and specify PROPID_M_LABEL and PROPID_M_LABEL_LEN in the MQMSGPROPS structure. Then call MQReceiveMessage or MQReceiveMessageByLookupId and examine the returned values.

Before using the message label, always check the length property PROPID_M_LABEL_LEN to see if the label was sent with the message. If the returned value of PROPID_M_LABEL_LEN is 0, no label was sent with the message. If the returned value is non-0, PROPID_M_LABEL contains the label of the message.

Equivalent COM Property

With COM components, the equivalent property for setting and retrieving the message label is MSMQMessage.Label.

Example Code

The following code fragments show how PROPID_M_LABEL is specified in arrays that can be used to initialize an MQMSGPROPS structure for setting and retrieving the message label:

To Specify a Message Label

aMsgPropId[i] = PROPID_M_LABEL;                // Property ID  
aMsgPropVar[i].vt = VT_LPWSTR;                 // Type indicator  
aMsgPropVar[i].pwszVal = L"Test Message";      // Label assigned  
i++;  

To Retrieve the Message Label

WCHAR wszLabelBuffer[MQ_MAX_MSG_LABEL_LEN];    // Label buffer  
aMsgPropId[i] = PROPID_M_LABEL_LEN;            // Property ID  
aMsgPropVar[i].vt =VT_UI4;                     // Type indicator  
aMsgPropVar[i].ulVal = MQ_MAX_MSG_LABEL_LEN;   // Label buffer size  
i++;  
  
aMsgPropId[i] = PROPID_M_LABEL;                // Property ID  
aMsgPropVar[i].vt = VT_LPWSTR;                 // Type indicator  
aMsgPropVar[i].pwszVal = wszLabelBuffer;  
i++;  

The following example is included in Using Message Queuing.

See Also

Message Properties
aStatus
MQMSGPROPS
MQReceiveMessage
MQReceiveMessageByLookupId
MQSendMessage
PROPID_M_LABEL_LEN