MSMQQueueInfo.FormatName (Compact 2013)
3/26/2014
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.
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.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
Header |
mqoai.h |
Library |
mqoa.lib |