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