Writing a Message Queuing Application using C-C++

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 following list describes what is needed to start writing a sending or receiving application using C/C++. This list provides a basic understanding of what functions and structures are used to reference a queue by creating a new queue or locate an existing queue, open the queue, then send or read messages.

• Make sure that you know how Message Queuing is deployed. For example: are the queues you are sending messages to or reading messages from local or remote, is your application going to have access to the directory service at all times, is Message Queuing deployed across different enterprises, is Message Queuing deployed in a mixed mode environment where different versions of Message Queuing are running.

• Make sure that your application includes the appropriate header file and references the mqrt.lib run-time library.

• To create a queue define an MQQUEUEPROPS structure and specify the queue properties that you need to define the queue's behavior (the PROPID_Q_PATHNAME property is the only queue property required to create a queue).

  The example below defines an MQQUEUPROPS structure that can contain two queue properties.

  const int NUMBEROFPROPERTIES = 5;        // Number of properties.  
  DWORD cPropId = 0;              // Counter for adding properties.  
  MQQUEUEPROPS QueueProps;  
  MQPROPVARIANT aQueuePropVar[NUMBEROFPROPERTIES];  
  QUEUEPROPID aQueuePropId[NUMBEROFPROPERTIES];  
  HRESULT aQueueStatus[NUMBEROFPROPERTIES];  
  

  For an example of creating a queue, see Creating Queue Examples.

• To locate existing queues, define an MQRESTRICTION and one or more MQPROPERTYRESTRICTION structures to define the query and an MQCOLUMNSET structure to specify what properties to retrieve.

  The example below defines a single MQPROPERTYRESTRICTION structure indicating that only one queue property will be used in the query, and an MQCOLUMNSET structure that indicates two queue properties will be retrieved for each queue found.

  MQPROPERTYRESTRICTION PropertyRestriction;  
  MQRESTRICTION Restriction;  
  
  MQCOLUMNSET Column  
  DWORD cColumnCount = 0;  
  PROPID aPropId[2];  
  

  For an example of locating a queue, see Locating Queue Examples.

• Define an MQMSGPROPS structure and specify the appropriate message properties. An MQMSGPROPS structure is required for sending and reading messages.

  For sending applications, these are the properties that will be set by your application to define the behavior of the message.

  Note

  When a message is sent, Message Queuing sets default values for all message properties that are not set by your application.

  For receiving applications, these are the message properties that will be retrieved by your application.

• Obtain a reference to the queue (the format name of the queue) by creating a new queue or locating an existing queue.

  Note

  There are many ways to obtain the format name of the queue, however applications typically create a new queue or locate an existing queue to obtain the format name of a queue. For information on other ways to obtain format names, see Obtaining Format Names.

  To create a queue call the MQCreateQueue function. The path name of the queue is required to create the queue.

  To locate an existing public queue, call the MQLocateBegin, MQLocateNext, and MQLocateEnd functions (applications cannot use the locate functions to locate private queues).

• To send messages the following functions are typically called.

  Using the format name returned when the queue was created or when the queue was located, call MQOpenQueue to open the destination queue (other format names that can be used to open destination queues include distribution list format names, multicast address format names, multiple-element format names, and queue aliases).

  Using the handle returned by the MQOpenQueue function, call the MQSendMessage function to send the message.

  Using the handle returned by the MQOpenQueue function, call the MQCloseQueue function to free resources.

• To read messages in the queue the following functions are typically called.

  Using the format name returned when the queue was created or when the queue was located, call MQOpenQueue to open the destination queue.

  Using the handle returned by the MQOpenQueue function, call the MQReceiveMessage function to send the message. (MSMQ 3.0 provides an MQReceiveMessageByLookupId function for reading message based on their message identifier

  Using the handle returned by the MQOpenQueue function, call the MQCloseQueue function to free resources.