PROPID_M_EXTENSION

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_EXTENSION property provides a place to put additional application-defined information (called extension information) that is associated with the message.

Property ID

PROPID_M_EXTENSION

Type Indicator

VT_VECTOR | VT_UI1

MQPROPVARIANT Field

caub

Property Value

Array of bytes

Remarks

Sending Extension Information

To send extension information, specify PROPID_M_EXTENSION in the MQMSGPROPS structure, and call MQSendMessage.

Retrieving Extension Information

To retrieve extension information from a message, specify PROPID_M_EXTENSION and PROPID_M_EXTENSION_LEN in the MQMSGPROPS structure (the length property is used to verify that extension information was sent). Then call MQReceiveMessage or MQReceiveMessageByLookupId and examine the returned values.

If MQReceiveMessage or MQReceiveMessageByLookupId fails, returning an MQ_ERROR_BUFFER_OVERFLOW error, use the returned value of PROPID_M_EXTENSION_LEN to reallocate the extension information buffer and call the applicable function again.

Before using the returned extension information, always check the length property PROPID_M_EXTENSION_LEN to see if extension information was sent. If the returned value of the length property is 0, no information was sent. If the returned value is non-0, PROPID_M_EXTENSION contains extension information.

Equivalent COM Property

With COM components, the equivalent property for setting and retrieving extension information is MSMQMessage.Extension.

Example Code

The following code fragments show how PROPID_M_EXTENSION is specified in arrays that can be used to initialize an MQMSGPROPS structure for sending and retrieving extension information.

To Send Extension Information

aMsgPropId[i] = PROPID_M_EXTENSION;                     // Property ID  
aMsgPropVar[i].vt = VT_VECTOR | VT_UI1;                 // Type indicator  
aMsgPropVar[i].caub.pElems = ExtensionInformation;  
aMsgPropVar[i].caub.cElems = sizeof(ExtensionInformation);  
i++;  

To Retrieve Extension Information

ULONG ulExtInfoBufferSize = 1024;  
UCHAR * pucExtInfoBuffer = NULL;  
pucExtInfoBuffer = (UCHAR*)malloc(ulExtInfoBufferSize);  
if (pucExtInfoBuffer == NULL)  
{  
  return MQ_ERROR_INSUFFICIENT_RESOURCES;  
}  
memset(pucExtInfoBuffer, 0, ulExtInfoBufferSize);  
aMsgPropId[i] = PROPID_M_EXTENSION_LEN;                 // Property ID  
aMsgPropVar[i].vt = VT_NULL;                            // Type indicator  
i++;  
  
aMsgPropId[i] = PROPID_M_EXTENSION;                     // Property ID  
aMsgPropVar[i].vt = VT_VECTOR | VT_UI1;                 // Type indicator  
aMsgPropVar[i].caub.pElems = (UCHAR*)pucExtInfoBuffer;  
aMsgPropVar[i].caub.cElems = ulExtInfoBufferSize;  
i++;  
  
// Reallocate memory for the extension information buffer if necessary.  
ulExtInfoBufferSize = aMsgPropVar[0].ulVal*sizeof(UCHAR);  
pucExtInfoBuffer = (UCHAR*)realloc(pucExtInfoBuffer, ulExtInfoBufferSize);  
if (pucExtInfoBuffer == NULL)  
{  
  return MQ_ERROR_INSUFFICIENT_RESOURCES;  
}  
memset(pucExtInfoBuffer, 0, ulExtInfoBufferSize);  
aMsgPropVar[1].caub.pElems = (UCHAR*)pucExtInfoBuffer;  // Pointer to the new buffer  
aMsgPropVar[1].caub.cElems = ulExtInfoBufferSize;       // New buffer size  

See Also

Message Properties
MQMSGPROPS
MQReceiveMessage
MQReceiveMessageByLookupId
MQSendMessage
MSMQMessage.Extension
PROPID_M_EXTENSION_LEN