C-C++ Code Example: Requesting Acknowledgment Messages

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

This example provides an application-defined function that requests acknowledgment messages based on the acknowledgment level provided by the caller and sets the message's time-to-be-received timer.

For information on how acknowledgment messages are returned, see Acknowledgment Messages.

To request acknowledgments

1. Define the required constants and variables.

2. Define the MQMSGPROPS structure.

3. Specify message properties. This example specifies the following properties.

   • PROPID_M_ADMIN_QUEUE: Specifies the administration queue for returned acknowledgment messages. An HTTP direct format name must be used to set this property in an HTTP message.

   • PROPID_M_ACKNOWLEDGE: Specifies the type of acknowledgments requested.

   • PROPID_M_LABEL: Identifies the message.

   • PROPID_M_TIME_TO_BE_RECEIVED: Specifies the total time (in seconds) that the message is allowed to live before being discarded.

4. Initialize the MQMSGPROPS structure.

5. Call MQOpenQueue to open the queue with send access.

6. Call MQSendMessage to send the message that is requesting acknowledgments.

7. Call MQCloseQueue to close the queue.

Code Example

The following code example can be run on all versions of Message Queuing.

HRESULT RequestingAcknowledgment(  
                                 LPCWSTR wszDestQueueFormatName,  
                                 LPCWSTR wszAdminQueueFormatName,  
                                 UCHAR bAckLevel,  
                                 ULONG ulTimeToBeReceived  
                                 )  
{  
  
  // Validate the input strings.  
  if (wszDestQueueFormatName == NULL || wszAdminQueueFormatName == NULL)  
  {  
    return MQ_ERROR_INVALID_PARAMETER;  
  }  
  
  // Define the maximum total number of message properties and a property counter.  
  const int NUMBEROFPROPERTIES = 5;  
  DWORD cPropId = 0;  
  
  // Define the MQMSGPROPS structure.  
  MQMSGPROPS MsgProps;  
  MSGPROPID aMsgPropId[NUMBEROFPROPERTIES];  
  MQPROPVARIANT aMsgPropVar[NUMBEROFPROPERTIES];   
  HRESULT aMsgStatus[NUMBEROFPROPERTIES];  
  
  HRESULT hr = MQ_OK;  
  
  // Set message properties.  
  aMsgPropId[cPropId] = PROPID_M_ADMIN_QUEUE;          // Property ID  
  aMsgPropVar[cPropId].vt = VT_LPWSTR;                 // Type indicator  
  aMsgPropVar[cPropId].pwszVal = const_cast<WCHAR*>(wszAdminQueueFormatName);  
  cPropId++;  
  
  aMsgPropId[cPropId] = PROPID_M_ACKNOWLEDGE;          // Property ID  
  aMsgPropVar[cPropId].vt = VT_UI1;                    // Type indicator  
  aMsgPropVar[cPropId].bVal = bAckLevel;  
  cPropId++;  
  
  aMsgPropId[cPropId] = PROPID_M_LABEL;                // Property ID  
  aMsgPropVar[cPropId].vt = VT_LPWSTR;                 // Type indicator  
  aMsgPropVar[cPropId].pwszVal = L"Test Message: Ack";  
  cPropId++;  
  
  aMsgPropId[cPropId] = PROPID_M_TIME_TO_BE_RECEIVED;  // Property ID  
  aMsgPropVar[cPropId].vt = VT_UI4;                    // Type indicator  
  aMsgPropVar[cPropId].ulVal = ulTimeToBeReceived;  
  cPropId++;  
  
  // Initialize the MQMSGPROPS structure.  
  MsgProps.cProp = cPropId;                      // Number of message properties  
  MsgProps.aPropID = aMsgPropId;                 // IDs of the message properties  
  MsgProps.aPropVar = aMsgPropVar;               // Values of the message properties  
  MsgProps.aStatus = aMsgStatus;                 // Error reports  
  
  // Call MQOpenQueue to open the queue with send access.  
  HANDLE hQueue = NULL;  
  hr = MQOpenQueue (wszDestQueueFormatName,      // Format name of the queue  
                    MQ_SEND_ACCESS,              // Access mode  
                    MQ_DENY_NONE,                // Share mode  
                    &hQueue);                    // OUT: Queue handle  
  if (FAILED(hr))  
  {  
    return hr;  
  }  
  
  // Call MQSendMessage to send the message to the opened queue.  
  hr = MQSendMessage(  
                     hQueue,                     // Queue handle  
                     &MsgProps,                  // Message property structure  
                     MQ_NO_TRANSACTION  
                     );  
  if (FAILED(hr))  
  {  
    MQCloseQueue(hQueue);  
    return hr;  
  }  
  
  // Call MQCloseQueue to close the queue.  
  hr = MQCloseQueue(hQueue);  
  return hr;  
}