MessageQueue Constructor (String^, Boolean)
Initializes a new instance of the MessageQueue class that references the Message Queuing queue at the specified path and with the specified read-access restriction.
Assembly: System.Messaging (in System.Messaging.dll)
Parameters
- path
-
Type:
System::String^
The location of the queue referenced by this MessageQueue, which can be "." for the local computer. For information about the proper syntax for this parameter, see the Remarks section.
- sharedModeDenyReceive
-
Type:
System::Boolean
true to grant exclusive read access to the first application that accesses the queue; otherwise, false.
| Exception | Condition |
|---|---|
| ArgumentException | The Path property is not valid, possibly because it has not been set. |
Use this overload when you want to tie the new MessageQueue to a particular Message Queuing queue, for which you know the path, format name, or label. If you want to grant exclusive access to the first application that references the queue, set the sharedModeDenyReceive parameter to true. Otherwise, set sharedModeDenyReceive to false or use the constructor that has only a path parameter.
Setting sharedModeDenyReceive to true affects all objects that access the Message Queuing queue, including other applications. The effects of the parameter are not restricted to this application.
The MessageQueue constructor creates a new instance of the MessageQueue class; it does not create a new Message Queuing queue. To create a new queue in Message Queuing, use Create(String^).
The syntax of the path parameter depends on the type of queue.
Queue type | Syntax |
|---|---|
Public queue | MachineName\QueueName |
Private queue | MachineName\Private$\QueueName |
Journal queue | MachineName\QueueName\Journal$ |
Machine journal queue | MachineName\Journal$ |
Machine dead-letter queue | MachineName\Deadletter$ |
Machine transactional dead-letter queue | MachineName\XactDeadletter$ |
Alternatively, you can use the format name or label of a Message Queuing queue to describe the queue path.
Reference | Syntax | Example |
|---|---|---|
Format name | FormatName: [ format name ] | FormatName:Public= 5A5F7535-AE9A-41d4-935C-845C2AFF7112 FormatName:DIRECT=SPX:NetworkNumber; HostNumber\QueueName FormatName:DIRECT=TCP:IPAddress\QueueName FormatName:DIRECT=OS:MachineName\QueueName |
Label | Label: [ label ] | Label: TheLabel |
To work offline, you must use the format name syntax, rather than the friendly name syntax. Otherwise, an exception is thrown because the primary domain controller (on which Active Directory resides) is not available to resolve the path to the format name.
If a MessageQueue opens a queue with the sharedModeDenyReceive parameter set to true, any MessageQueue that subsequently tries to read from the queue generates a MessageQueueException because of a sharing violation. A MessageQueueException is also thrown if a MessageQueue tries to access the queue in exclusive mode while another MessageQueue already has non-exclusive access to the queue.
The following table shows initial property values for an instance of MessageQueue. These values are based on the properties of the Message Queuing queue, with the path specified by the path parameter.
Property | Initial value |
|---|---|
false. | |
0. | |
The values set by the default constructor of the DefaultPropertiesToSend class. | |
true, if the Message Queuing queue's privacy level setting is "Body"; otherwise, false. | |
The value of the Message Queuing queue's computer name property. | |
The values set by the default constructor of the MessagePropertyFilter class. | |
Empty, if not set by the constructor. | |
Empty, if not set by the constructor. | |
The value of the sharedModeDenyReceive parameter. | |
true, if the Message Queuing object's journal setting is enabled; otherwise, false. |
The following code example creates a new MessageQueue with exclusive access, sets its path, and sends a message to the queue.
#using <system.dll> #using <system.messaging.dll> using namespace System; using namespace System::Messaging; ref class MyNewQueue { public: // Requests exlusive read access to the queue. If // access is granted, receives a message from the // queue. void GetExclusiveAccess() { try { // Request exclusive read access to the queue. MessageQueue^ myQueue = gcnew MessageQueue( ".\\myQueue",true ); // Receive a message. This is where SharingViolation // exceptions would be thrown. Message^ myMessage = myQueue->Receive(); } catch ( MessageQueueException^ e ) { // Handle request for denial of exclusive read access. if ( e->MessageQueueErrorCode == MessageQueueErrorCode::SharingViolation ) { Console::WriteLine( "Denied exclusive read access" ); } // Handle other sources of a MessageQueueException. } // Handle other exceptions as necessary. return; } }; // Provides an entry point into the application. // This example connects to a message queue, and // requests exclusive read access to the queue. int main() { // Create a new instance of the class. MyNewQueue^ myNewQueue = gcnew MyNewQueue; // Output the count of Lowest priority messages. myNewQueue->GetExclusiveAccess(); return 0; }
Available since 1.1