MSMQQueueInfo.FormatName (Windows Embedded CE 6.0)

1/6/2010

The FormatName property of the MSMQQueueInfo object 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

• pbstrFormatName or 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.

Remarks

The MSMQQueueInfo.FormatName property 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 MSMQQueueInfo object 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.FormatName property 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.FormatName property and call the MSMQQueueInfo.Open method.

To retrieve the stored format name of a queue, call the MSMQQueueInfo.Refresh method and inspect the MSMQQueueInfo.FormatName property.

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 MQOpenQueue function call.

Requirements

See Also

Reference

MSMQQueueInfo