PROPID_M_LABEL_LEN

 

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.) The PROPID_M_LABEL_LEN property identifies the length (in Unicode characters) of the message label buffer.

Property ID

PROPID_M_LABEL_LEN

Type Indicator

VT_UI4

MQPROPVARIANT Field

ulVal

Property Value

Input: The size (in Unicode characters) of the message label buffer allocated by the receiving application. The maximum value allowed is MQ_MAX_MSG_LABEL_LEN (250 Unicode characters, including the end-of-string character).

Return: The length (in Unicode characters) of the label string plus the end-of-string character.

Remarks

PROPID_M_LABEL_LEN is only used by the receiving application. It is required whenever PROPID_M_LABEL is specified in the MQMSGPROPS structure.

On input, the message label buffer should be large enough to hold the complete label string including the end-of-string character. MQReceiveMessage or MQReceiveMessageByLookupId succeeds if the buffer is large enough to hold the message label. If the buffer is too small, the function call fails, returning an MQ_ERROR_BUFFER_TOO_SMALL error, and PROPID_M_LABEL_LEN can be used to obtain the required buffer length of the message label string.

To retrieve the label of a message, specify PROPID_M_LABEL_LEN and PROPID_M_LABEL in the MQMSGPROPS structure. Then call MQReceiveMessage or MQReceiveMessageByLookupId and examine the returned values.

When the function call succeeds, first test the returned value of PROPID_M_LABEL_LEN to see if a message label exists. A returned value of 0 indicates that no label was specified by the sending application. A non-0 returned value indicates that the label was returned by PROPID_M_LABEL.

When retrieving the label of several messages, make sure you reset the value of PROPID_M_LABEL_LEN to the maximum label size allowed by Message Queuing (MQ_MAX_MSG_LABEL_LEN or 250 Unicode characters) before retrieving the next label. If it is not reset, an error will be returned if the new label is longer than the previous label.

Equivalent COM Property

This property is not needed when you are using COM components.

Example Code

The following code fragment shows how PROPID_M_LABEL_LEN is specified in arrays that can be used to initialize an MQMSGPROPS structure when retrieving 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.

For an example of	See
Retrieving the labels of messages	C/C++ Code Example: Navigating Using Cursors

See Also

Message Properties
MQMSGPROPS
MQReceiveMessage
MQReceiveMessageByLookupId
MQSendMessage
PROPID_M_LABEL