C-C++ Code Example: Opening a Queue

 

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 opens a queue using information provided by the caller. In this function, the path name of the queue, provided by the caller, is converted to the public or private format name required to open the queue.

The public format name of any public queue must be retrieved from the directory service, and the private format name of a local private queue can be obtained from information stored on the local computer. This function cannot be used to open a remote private queue.

Note

To open remote queues while operating offline, the application must obtain and cache the public or private format name of the remote queues while online, or have the information needed to construct a direct format name for the queue.

The following procedure shows how the function opens the queue based on the information provided by its parameters.

To open a queue

1. Obtain a format name for the queue. This example uses MQPathNameToFormatName to generate a format name from the queue path name provided by the caller.

2. Using the access and share mode provided by the caller, call MQOpenQueue to open the queue.

3. Return the handle to the queue specified in the phQueue parameter of the MQOpenQueue function. If MQOpenQueue fails, Message Queuing returns a NULL pointer.

Code Example

The following code example contains no version-specific Message Queuing calls.

int OpenMyQueue(  
                LPWSTR wszPathName,  
                DWORD dwAccess,  
                DWORD dwShareMode,  
                QUEUEHANDLE *phQueue  
                )  
{  
  HRESULT hr = MQ_OK;  
  
  // Validate the input parameters.  
  if ((wszPathName == NULL) || (phQueue == NULL))  
  {  
    return MQ_ERROR_INVALID_PARAMETER;  
  }  
  
  // Call MQPathNameToFormatName to obtain the format name required  
  // to open the queue.  
  DWORD dwFormatNameBufferLength = 256;               // Length of the format name buffer  
  WCHAR wszFormatNameBuffer[256];                     // Format name buffer  
  
  hr = MQPathNameToFormatName(wszPathName,  
                              wszFormatNameBuffer,  
                              &dwFormatNameBufferLength);  
  if (FAILED(hr))  
  {  
     fprintf(stderr, "An error occurred in MQPathNameToFormatName (error: 0x%x).\n", hr);  
     return hr;  
  }  
  
  // Call MQOpenQueue to open the queue with the access and  
  // share mode provided by the caller.  
  hr = MQOpenQueue(  
                   wszFormatNameBuffer,               // Format name of the queue  
                   dwAccess,                          // Access mode  
                   dwShareMode,                       // Share mode  
                   phQueue                            // OUT: Queue handle  
                   );  
  if (FAILED(hr))  
  {  
     fprintf(stderr, "An error occurred in MQOpenQueue (error: 0x%x.)\n",hr);  
     return hr;  
  }  
  return hr;  
}