PROPID_M_CORRELATIONID

 

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_CORRELATIONID property specifies the correlation identifier of the message.

Property ID

PROPID_M_CORRELATIONID

Type Indicator

VT_VECTOR | VT_UI1

MQPROPVARIANT Field

caub

Property Value

Application-defined 20-byte message identifier (default is 0).

Remarks

When sending a message, PROPID_M_CORRELATIONID provides an application-defined identifier that the receiving application can use to sort or filter messages. The correlation identifier must be a 20-byte identifier. If the length of the correlation identifier is not exactly 20 bytes, an MQ_ERROR_ILLEGAL_PROPERTY_SIZE error will be returned when the application attempts to send the message.

To set the correlation identifier of a message, specify PROPID_M_CORRELATIONID in the MQMSGPROPS structure and call MQSendMessage. The correlation ID is specified in an array of unsigned characters, whose size must be PROPID_M_CORRELATIONID_SIZE (20).

To retrieve the correlation identifier of a message, include PROPID_M_CORRELATIONID and a buffer consisting of an array of unsigned characters with a length of PROPID_M_CORRELATIONID_SIZE (20) to receive its value in the MQMSGPROPS structure. Then call MQReceiveMessage or MQReceiveMessageByLookupId and examine its returned value.

Note

The buffer must consist of exactly 20 unsigned characters. Specifying either a smaller or larger buffer will result in an error.

When sending response messages to the sending application, PROPID_M_CORRELATIONID can be set to the message identifier (PROPID_M_MSGID) of the message that is in the queue. This provides an easy mechanism that the sending application can use to match the response message with the message that was sent.

When Message Queuing generates an acknowledgment message, it uses the PROPID_M_CORRELATIONID property to specify the message identifier of the original message. The application retrieving the acknowledgment messages can then use PROPID_M_CORRELATIONID to identify the original message associated with the acknowledgment message.

When sending messages to a foreign queue, the value of PROPID_M_CORRELATIONID is used to verify the sender's signature.

Equivalent COM Property

With COM components, the equivalent property for setting and retrieving the correlation identifier is MSMQMessage.CorrelationId.

For information on	See
What is in a response message	Response Messages
Acknowledgment messages in administration queues	Administration Queues
Sending messages to foreign queues	Connector Services

Example Code

The following code fragment shows how PROPID_M_CORRELATIONID is specified in arrays that can be used to initialize an MQMSGPROPS structure.

UCHAR rgucCorrelationID[PROPID_M_CORRELATIONID_SIZE];  
aMsgPropId[i] = PROPID_M_CORRELATIONID;      // Property ID  
aMsgPropVar[i].vt = VT_VECTOR | VT_UI1;      // Type indicator  
aMsgPropVar[i].caub.pElems = rgucCorrelationID;  
aMsgPropVar[i].caub.cElems = PROPID_M_CORRELATIONID_SIZE;  
i++;  

The following examples are included in Using Message Queuing.

For an example of	See
Setting the correlation identifier in a response message	C/C++ Code Example: Returning Response Messages
Using the correlation identifier to filter the messages in a queue	C/C++ Code Example: Correlation Identifier Filters
Using the correlation identifier to locate the acknowledgment message that was returned for a specific message	C/C++ Code Example: Matching Acknowledgment Messages

See Also

Message Properties
MQMSGPROPS
MQReceiveMessage
MQReceiveMessageByLookupId
MQSendMessage
PROPID_M_MSGID