Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

The FormatNameproperty of the MSMQQueueInfoobject specifies the format name of the queue. This property is used by Message Queuing to open the queue.

Syntax 

HRESULT get_FormatName( 
  BSTR* 
pbstrFormatName 
);
HRESULT put_FormatName( 
  BSTR 
bstrFormatName
);

Parameters

pbstrFormatNameor bstrFormatName

Specifies the format name of the queue.

The following list shows the possible String property values.

  • PUBLIC=QueueGUID

  • DIRECT=Protocol:MachineAddress\QueueName

  • DIRECT=OS:MachineName\QueueName

  • PRIVATE=MachineGUID\QueueNumber

Return Value

The following table describes the common return values.

Value Description

S_OK

Success

E_INVALIDARG

One or more arguments are invalid

E_NOTIMPL

The function contains no implementation

E_OUTOFMEMORY

Out of memory

Remarks

The MSMQQueueInfo.FormatNameproperty must be specified to open the queue. Message Queuing uses the format name of the queue to identify which queue to open and how to access the opened queue.

When creating a queue, if a format name is not provided by the application, Message Queuing generates a format name based on the pathname of the queue, MSMQQueueInfo.PathName.

After the queue is created, you can use the name generated by Message Queuing or specify a different one. For example, to open the journal of the queue modify the format name of the destination queue and then use the MSMQQueueInfoobject to open the journal.

The format name of a queue cannot be changed while the queue is open.

Opening queues for Direct Messaging

To send messages directly to and read messages directly from a queue the MSMQQueueInfo.FormatNameproperty must contain a direct format name, as shown in the following list

  • DIRECT=AddressSpecification\QueueName (for public queues)

  • DIRECT=AddressSpecification\PRIVATE$\QueueName (for private queues)

  • DIRECT=AddressSpecification\SYSTEM$;computersystemqueue (introduced in MSMQ 2.0)

  • DIRECT=HTTP://URLAddressSpecification\msmq\QueueName (introduced in MSMQ 3.0)

  • DIRECT=HTTPS://URLAddressSpecification\msmq\QueueName (introduced in MSMQ 3.0)

Setting and Retrieving the Format Name

To specify the format name of the queue when opening a queue, set the MSMQQueueInfo.FormatNameproperty and call the MSMQQueueInfo.Openmethod.

To retrieve the stored format name of a queue, call the MSMQQueueInfo.Refreshmethod and inspect the MSMQQueueInfo.FormatNameproperty.

For public queues, this information is stored in the directory service.

For private queues, this information is stored on the computer where the messages of the queue are stored.

Using Null characters in Format Name strings

Message Queuing COM components ignore characters that follow the first Null character in a string without returning an error.

Equivalent Function property

There is no equivalent function property for the format name of the queue. When using function calls, the format name of the queue is specified as a parameter of the MQOpenQueuefunction call.

Requirements

Header mqoai.h
Library mqoa.lib
Windows Embedded CE Windows CE .NET 4.0 and later
Windows Mobile Windows Mobile Version 5.0 and later