MessageQueue.SetPermissions Method

Definition

Namespace:

System.Messaging

Assembly:

System.Messaging.dll

Adds permissions to the current set. This controls who has access rights to queue properties and messages in the queue.

Overloads

SetPermissions(AccessControlList)	Assigns access rights to the queue based on the contents of an access control list.
SetPermissions(MessageQueueAccessControlEntry)	Assigns access rights to the queue based on the contents of an access control entry.
SetPermissions(String, MessageQueueAccessRights)	Gives a computer, group, or user the specified access rights.
SetPermissions(String, MessageQueueAccessRights, AccessControlEntryType)	Gives a computer, group, or user the specified access rights, with the specified access control type (allow, deny, revoke, or set).

SetPermissions(AccessControlList)

Assigns access rights to the queue based on the contents of an access control list.

public:
 void SetPermissions(System::Messaging::AccessControlList ^ dacl);

public void SetPermissions (System.Messaging.AccessControlList dacl);

member this.SetPermissions : System.Messaging.AccessControlList -> unit

Public Sub SetPermissions (dacl As AccessControlList)

Parameters

dacl

AccessControlList

A AccessControlList that contains one or more access control entries that specify the trustees and the permissions to grant.

Exceptions

MessageQueueException

An error occurred when accessing a Message Queuing method.

Examples

The following code example demonstrates the use of SetPermissions(AccessControlList).

// Connect to a queue on the local computer.
MessageQueue^ queue = gcnew MessageQueue(".\\exampleQueue");

// Create an AccessControlList.
AccessControlList^ list = gcnew AccessControlList();

// Create a new trustee to represent the "Everyone" user group.
Trustee^ tr = gcnew Trustee("Everyone");

// Create an AccessControlEntry, granting the trustee read access to
// the queue.
AccessControlEntry^ entry = gcnew AccessControlEntry(
    tr, GenericAccessRights::Read,
    StandardAccessRights::Read,
    AccessControlEntryType::Allow);

// Add the AccessControlEntry to the AccessControlList.
list->Add(entry);

// Apply the AccessControlList to the queue.
queue->SetPermissions(list);

queue->Close();

// Connect to a queue on the local computer.
MessageQueue queue = new MessageQueue(".\\exampleQueue");

// Create an AccessControlList.
AccessControlList list = new AccessControlList();

// Create a new trustee to represent the "Everyone" user group.
Trustee tr = new Trustee("Everyone");

// Create an AccessControlEntry, granting the trustee read access to
// the queue.
AccessControlEntry entry = new AccessControlEntry(
    tr, GenericAccessRights.Read,
    StandardAccessRights.Read,
    AccessControlEntryType.Allow);

// Add the AccessControlEntry to the AccessControlList.
list.Add(entry);

// Apply the AccessControlList to the queue.
queue.SetPermissions(list);

Remarks

Use this overload to grant, deny, or revoke rights by using a collection of access control entries to specify trustee and permissions information. This is used, for example, to grant permissions to multiple users at the same time.

The trustee you specify when you construct the ace parameter can be an individual user, a group of users, or a computer. If the trustee is an individual, use the format DOMAIN\user. You can specify "." for the trustee to indicate the local computer.

The permissions you assign through SetPermissions add rights to the existing list. By default, the creator of a public or private queue has full control, and the domain group Everyone has permission to get queue properties, get permissions, and write to the queue. When you call SetPermissions, the user and permissions information is appended to the bottom of the existing list.

The system examines each AccessControlEntry in sequence until one of the following events occurs:

• An access-denied AccessControlEntry explicitly denies any of the requested access rights to one of the trustees listed in the thread's access token.

• One or more access-allowed AccessControlEntry items for trustees listed in the thread's access token explicitly grant all the requested access rights.

• All AccessControlEntry items have been checked and there is still at least one requested access right that has not been explicitly allowed, in which case, access is implicitly denied.

When you construct the dacl parameter, you add AccessControlEntry instances to your AccessControlList collection. When you construct each access control entry, you can specify generic or standard access rights. The rights to a queue can be any combination of the following:

• Delete

• Read Security

• Write Security

• Synchronize

• Modify Owner

• Read

• Write

• Execute

• Required

• All

• None

These rights are a set of bit flags that you can combine using the OR bitwise operator.

• Full Control

• Delete Message

• Receive Message

• Peek Message

• Receive Journal Message

• Get Queue Properties

• Set Queue Properties

• Get Permissions

• Set Permissions

• Take Queue Ownership

• Write Message

The following table shows whether this method is available in various Workgroup modes.

Workgroup mode	Available
Local computer	Yes
Local computer and direct format name	Yes
Remote computer	No
Remote computer and direct format name	No

See also

• ResetPermissions()
• Trustee
• AccessControlList

SetPermissions(MessageQueueAccessControlEntry)

Assigns access rights to the queue based on the contents of an access control entry.

public:
 void SetPermissions(System::Messaging::MessageQueueAccessControlEntry ^ ace);

public void SetPermissions (System.Messaging.MessageQueueAccessControlEntry ace);

member this.SetPermissions : System.Messaging.MessageQueueAccessControlEntry -> unit

Public Sub SetPermissions (ace As MessageQueueAccessControlEntry)

Parameters

ace

MessageQueueAccessControlEntry

A MessageQueueAccessControlEntry that specifies a user, an access type, and a permission type.

Exceptions

MessageQueueException

An error occurred when accessing a Message Queuing method.

Examples

The following code example demonstrates the use of SetPermissions(MessageQueueAccessControlEntry).

// Connect to a queue on the local computer.
MessageQueue^ queue = gcnew MessageQueue(".\\exampleQueue");

// Create a new trustee to represent the "Everyone" user group.
Trustee^ tr = gcnew Trustee("Everyone");

// Create a MessageQueueAccessControlEntry, granting the trustee the
// right to receive messages from the queue.
MessageQueueAccessControlEntry^ entry = gcnew
    MessageQueueAccessControlEntry(
    tr, MessageQueueAccessRights::ReceiveMessage,
    AccessControlEntryType::Allow);

// Apply the MessageQueueAccessControlEntry to the queue.
queue->SetPermissions(entry);

queue->Close();

// Connect to a queue on the local computer.
MessageQueue queue = new MessageQueue(".\\exampleQueue");

// Create a new trustee to represent the "Everyone" user group.
Trustee tr = new Trustee("Everyone");

// Create a MessageQueueAccessControlEntry, granting the trustee the
// right to receive messages from the queue.
MessageQueueAccessControlEntry entry = new
    MessageQueueAccessControlEntry(
    tr, MessageQueueAccessRights.ReceiveMessage,
    AccessControlEntryType.Allow);

// Apply the MessageQueueAccessControlEntry to the queue.
queue.SetPermissions(entry);

Remarks

Use this overload to grant, deny, or revoke rights by using an access control entry to specify trustee and rights information.

The trustee you specify when you construct the ace parameter can be an individual user, a group of users, or a computer. If the trustee is an individual, use the format DOMAIN\user. You can specify "." for the trustee to indicate the local computer.

The permissions you assign through SetPermissions add rights to the existing list. By default, the creator of a public or private queue has full control, and the domain group Everyone has permission to get queue properties, get permissions, and write to the queue. When you call SetPermissions, the user and permissions information is appended to the bottom of the existing list.

The system examines each AccessControlEntry in sequence until one of the following events occurs:

• An access-denied AccessControlEntry explicitly denies any of the requested access rights to one of the trustees listed in the thread's access token.

• One or more access-allowed AccessControlEntry items for trustees listed in the thread's access token explicitly grant all the requested access rights.

• All AccessControlEntry items have been checked and there is still at least one requested access right that has not been explicitly allowed, in which case, access is implicitly denied.

The rights to a queue, which you specify in the rights parameter when you construct your MessageQueueAccessControlEntry, can be any combination of the following:

• Full Control

• Delete Message

• Receive Message

• Peek Message

• Receive Journal Message

• Get Queue Properties

• Set Queue Properties

• Get Permissions

• Set Permissions

• Take Queue Ownership

• Write Message

The rights parameter you specify in the constructor for the ace parameter is a flag of the MessageQueueAccessRights enumeration. It represents a set of bit flags that you can combine using the bitwise operator OR when you build the rights parameter.

The following table shows whether this method is available in various Workgroup modes.

Workgroup mode	Available
Local computer	Yes
Local computer and direct format name	Yes
Remote computer	No
Remote computer and direct format name	No

See also

• ResetPermissions()
• Trustee
• MessageQueueAccessRights
• MessageQueueAccessControlEntry

SetPermissions(String, MessageQueueAccessRights)

Gives a computer, group, or user the specified access rights.

public:
 void SetPermissions(System::String ^ user, System::Messaging::MessageQueueAccessRights rights);

public void SetPermissions (string user, System.Messaging.MessageQueueAccessRights rights);

member this.SetPermissions : string * System.Messaging.MessageQueueAccessRights -> unit

Public Sub SetPermissions (user As String, rights As MessageQueueAccessRights)

Parameters

user

String

The individual, group, or computer that gets additional rights to the queue.

rights

MessageQueueAccessRights

A MessageQueueAccessRights that indicates the set of rights to the queue that Message Queuing assigns to the user passed in.

Exceptions

ArgumentException

The user is null.

MessageQueueException

An error occurred when accessing a Message Queuing method.

Examples

The following code example demonstrates the use of SetPermissions(String, MessageQueueAccessRights).

// Connect to a queue on the local computer.
MessageQueue^ queue = gcnew MessageQueue(".\\exampleQueue");

// Grant all users in the "Everyone" user group the right to receive
// messages from the queue.
queue->SetPermissions("Everyone",
    MessageQueueAccessRights::ReceiveMessage);

queue->Close();

// Connect to a queue on the local computer.
MessageQueue queue = new MessageQueue(".\\exampleQueue");

// Grant all users in the "Everyone" user group the right to receive
// messages from the queue.
queue.SetPermissions("Everyone", MessageQueueAccessRights.ReceiveMessage);

Remarks

Use this overload to grant specified rights to an individual user. The user can be any valid trustee, which includes individual users, groups of users, or a computer. If the user is an individual, use the format DOMAIN\user for the user parameter. You can specify "." for the user parameter to indicate the local computer.

The permissions you assign through SetPermissions add rights to the existing list. By default, the creator of a public or private queue has full control, and the domain group Everyone has permission to get queue properties, get permissions, and write to the queue. When you call SetPermissions, the user and permissions information is appended to the bottom of the existing list.

The system examines each AccessControlEntry in sequence until one of the following events occurs:

• An access-denied AccessControlEntry explicitly denies any of the requested access rights to one of the trustees listed in the thread's access token.

• One or more access-allowed AccessControlEntry items for trustees listed in the thread's access token explicitly grant all the requested access rights.

• All AccessControlEntry items have been checked and there is still at least one requested access right that has not been explicitly allowed, in which case, access is implicitly denied.

The rights to a queue, specified in the rights parameter, can be any combination of the following:

• Full Control

• Delete Message

• Receive Message

• Peek Message

• Receive Journal Message

• Get Queue Properties

• Set Queue Properties

• Get Permissions

• Set Permissions

• Take Queue Ownership

• Write Message

The MessageQueueAccessRights enumeration represents a set of bit flags that you can combine using the bitwise operator OR to build the rights parameter.

With this overload, you can only grant permissions; you cannot revoke or deny them. You must use a different overload to explicitly grant any AccessControlEntryType other than Allow.

The following table shows whether this method is available in various Workgroup modes.

Workgroup mode	Available
Local computer	Yes
Local computer and direct format name	Yes
Remote computer	No
Remote computer and direct format name	No

See also

• ResetPermissions()
• Trustee
• MessageQueueAccessRights

SetPermissions(String, MessageQueueAccessRights, AccessControlEntryType)

Gives a computer, group, or user the specified access rights, with the specified access control type (allow, deny, revoke, or set).

public:
 void SetPermissions(System::String ^ user, System::Messaging::MessageQueueAccessRights rights, System::Messaging::AccessControlEntryType entryType);

public void SetPermissions (string user, System.Messaging.MessageQueueAccessRights rights, System.Messaging.AccessControlEntryType entryType);

member this.SetPermissions : string * System.Messaging.MessageQueueAccessRights * System.Messaging.AccessControlEntryType -> unit

Public Sub SetPermissions (user As String, rights As MessageQueueAccessRights, entryType As AccessControlEntryType)

Parameters

user

String

The individual, group, or computer that gets additional rights to the queue.

rights

MessageQueueAccessRights

A MessageQueueAccessRights that indicates the set of rights to the queue that Message Queuing assigns to the user passed in.

entryType

AccessControlEntryType

A AccessControlEntryType that specifies whether to grant, deny, or revoke the permissions specified by the rights parameter.

Exceptions

MessageQueueException

An error occurred when accessing a Message Queuing method.

Examples

The following code example demonstrates the use of SetPermissions(String, MessageQueueAccessRights, AccessControlEntryType).

// Connect to a queue on the local computer.
MessageQueue^ queue = gcnew MessageQueue(".\\exampleQueue");

// Grant all users in the "Everyone" user group the right to receive
// messages from the queue.
queue->SetPermissions("Everyone",
    MessageQueueAccessRights::ReceiveMessage,
    AccessControlEntryType::Allow);

queue->Close();

// Connect to a queue on the local computer.
MessageQueue queue = new MessageQueue(".\\exampleQueue");

// Grant all users in the "Everyone" user group the right to receive
// messages from the queue.
queue.SetPermissions("Everyone", MessageQueueAccessRights.ReceiveMessage,
    AccessControlEntryType.Allow);

Remarks

Use this overload to grant, deny, or revoke specified rights for an individual user. The user can be any valid trustee, which includes individual users, groups of users, or a computer. If the user is an individual, use the format DOMAIN\user for the user parameter. You can specify "." for the user parameter to indicate the local computer.

The permissions you assign through SetPermissions add rights to the existing list. By default, the creator of a public or private queue has full control, and the domain group Everyone has permission to get queue properties, get permissions, and write to the queue. When you call SetPermissions, the user and permissions information is appended to the bottom of the existing list.

The system examines each AccessControlEntry in sequence until one of the following events occurs:

• An access-denied AccessControlEntry explicitly denies any of the requested access rights to one of the trustees listed in the thread's access token.

• One or more access-allowed AccessControlEntry items for trustees listed in the thread's access token explicitly grant all the requested access rights.

• All AccessControlEntry items have been checked and there is still at least one requested access right that has not been explicitly allowed, in which case, access is implicitly denied.

The rights to a queue, specified in the rights parameter, can be any combination of the following:

• Full Control

• Delete Message

• Receive Message

• Peek Message

• Receive Journal Message

• Get Queue Properties

• Set Queue Properties

• Get Permissions

• Set Permissions

• Take Queue Ownership

• Write Message

The MessageQueueAccessRights enumeration represents a set of bit flags that you can combine using the bitwise operator OR to build the rights parameter.

The following table shows whether this method is available in various Workgroup modes.

Workgroup mode	Available
Local computer	Yes
Local computer and direct format name	Yes
Remote computer	No
Remote computer and direct format name	No

See also

• ResetPermissions()
• Trustee
• MessageQueueAccessRights
• AccessControlEntry