Partager via

PROPID_M_RESP_FORMAT_NAME

  • Article

 

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

(Introduced in MSMQ 3.0.) The PROPID_M_RESP_FORMAT_NAME property supersedes the PROPID_M_RESP_QUEUE property (both properties cannot be set at the same time for the message). This property specifies the response queues used for returning application-generated response messages.

Property ID

PROPID_M_RESP_FORMAT_NAME

Type Indicator

VT_LPWSTR

MQPROPVARIANT Field

pwszVal

Property Value

String that contains a public, private, direct, distribution list, multicast address, or multiple-element format name.

Remarks

The PROPID_M_RESP_FORMAT_NAME property is set by the sending application when requesting response messages from the receiving application. Response messages are application-defined messages that must be understood by the application sending the response and the application reading the response. Message Queuing has no control over the content of the response message.

Response queues can be any transactional or nontransactional queue.

Sets of response queues can be specified using the following format names.

  • Distribution list format names are used to reference response queues based on a public distribution list that is published in the Active Directory Domain Services (AD DS). For information on the syntax of distribution list format names, see Distribution List Format Names.

  • Multicast address format names are used to reference response queues that are associated with a specific multicast address. For information on the syntax of multicast address format names, see Multicast Address Format Names.

  • Multiple-element format names are used to reference response queues based on a private list of destination queues. For information on the syntax of multiple element format names, see Multiple-Element Format Names.

Message Queuing provides backwards compatibility for sending applications that send messages to MSMQ 2.0 computers and for receiving applications that read messages sent from MSMQ 2.0 computers.

When sending messages, the queue manager sets the PROPID_M_RESP_QUEUE property of the message to one of the following values.

  • If the PROPID_M_RESP_FORMAT_NAME property contains a single public, private, or direct format name, the PROPID_M_RESP_QUEUE property is set to the format name string specified by PROPID_M_RESP_FORMAT_NAME.

  • If the PROPID_M_RESP_FORMAT_NAME property contains a multiple-element format name, the PROPID_M_RESP_QUEUE property is set to the first non-distribution list element in the format name string.

  • If PROPID_M_RESP_FORMAT_NAME contains a distribution list, the PROPID_M_RESP_QUEUE property is set to NULL.

When accepting an MSMQ 1.0 or MSMQ 2.0 message, the destination queue manager sets PROPID_M_RESP_FORMAT_NAME to the format name specified by the PROPID_M_RESP_QUEUE property.

When acknowledgment messages are returned by Message Queuing or a connector application, the PROPID_M_RESP_FORMAT_NAME property of the acknowledgment message is set to the value of the PROPID_M_DEST_FORMAT_NAME property of the original message.

Setting PROPID_M_RESP_FORMAT_NAME

To set response queues, include PROPID_M_RESP_FORMAT_NAME in the MQMSGPROPS structure and then call MQSendMessage.

To retrieve the response queues specified by the sending application, include the following two properties in the MQMSGPROPS structure, then call MQReceiveMessage or MQReceiveMessageByLookupId and examine the returned values.

If MQReceiveMessage or MQReceiveMessageByLookupId fails, returning an MQ_ERROR_FORMATNAME_BUFFER_TOO_SMALL error, use the returned value of PROPID_M_RESP_FORMAT_NAME_LEN to reallocate the buffer, and call the applicable function again.

When retrieving the response queue set, always check the PROPID_M_RESP_FORMAT_NAME_LEN property first to see if the response queues were specified by the sending application. If the returned value of PROPID_M_RESP_FORMAT_NAME_LEN is 0, no response queues were sent with the message. If the returned value is non-0, PROPID_M_RESP_FORMAT_NAME contains the public, private, direct, multiple-element, multicast address, or distribution list format name of the response queue set.

Equivalent COM Property

With COM components, the equivalent property is MSMQMessage.ResponseDestination.

Example Code

The following code fragments show how PROPID_M_RESP_FORMAT_NAME is specified in arrays that can be used to initialize an MQMSGPROPS structure for setting and retrieving the response format name.

To Set the Response Format Name

aMsgPropId[i] = PROPID_M_RESP_FORMAT_NAME;      // Property ID  
aMsgPropVar[i].vt = VT_LPWSTR;                  // Type indicator  
aMsgPropVar[i].pwszVal = wszRespFormatName;   // Application-defined buffer  
i++;

To Retrieve the Response Format Name

ULONG ulBufferLength = 1024;  
WCHAR * wszRespFormatNameBuffer = NULL;  
wszRespFormatNameBuffer = (WCHAR*)malloc(ulBufferLength*sizeof(WCHAR));  
if (wszRespFormatNameBuffer == NULL)  
{  
  return MQ_ERROR_INSUFFICIENT_RESOURCES;  
}  
memset(wszRespFormatNameBuffer, 0, ulBufferLength*sizeof(WCHAR));  
aMsgPropId[i] = PROPID_M_RESP_FORMAT_NAME;         // Property ID  
aMsgPropVar[i].vt = VT_LPWSTR;                     // Type indicator  
aMsgPropVar[i].pwszVal = wszRespFormatNameBuffer;      // Application-defined buffer  
i++;  
  
aMsgPropId[i] = PROPID_M_RESP_FORMAT_NAME_LEN;     // Property ID  
aMsgPropVar[i].vt = VT_UI4;                        // Type indicator  
aMsgPropVar[i].ulVal = ulBufferLength;  
i++;  
  
// Reallocate memory for the response format name buffer if necessary.  
wszRespFormatNameBuffer = (WCHAR*)realloc(wszRespFormatNameBuffer, aMsgPropVar[1].ulVal*sizeof(WCHAR));  
if (wszRespFormatNameBuffer == NULL)  
{  
  return MQ_ERROR_INSUFFICIENT_RESOURCES;  
}  
memset(wszRespFormatNameBuffer, 0, aMsgPropVar[1].ulVal*sizeof(WCHAR));  
aMsgPropVar[0].pwszVal = wszRespFormatNameBuffer;  // Pointer to the new buffer

The following example is included in Using Message Queuing.

For an example of See
Retrieving the response format name to return a response message C/C++ Code Example: Returning Response Messages

See Also

Message Properties
MQMSGPROPS
MSMQMessage.ResponseDestination
MQReceiveMessage
MQReceiveMessageByLookupId
MQSendMessage
PROPID_M_DEST_FORMAT_NAME
PROPID_M_RESP_QUEUE
PROPID_M_RESP_FORMAT_NAME_LEN