MQGetQueueSecurity

Applies To: Windows 10, Windows 7, Windows 8, Windows 8.1, Windows Server 2008, Windows Server 2008 R2, Windows Server 2012, Windows Server 2012 R2, Windows Server Technical Preview, Windows Vista

The MQGetQueueSecurity function retrieves information from the access control security descriptor of the specified queue.

HRESULT APIENTRY MQGetQueueSecurity(  
  LPCWSTR lpwcsFormatName,                       
  SECURITY_INFORMATION SecurityInformation,    
  PSECURITY_DESCRIPTOR pSecurityDescriptor,    
  DWORD nLength,                                 
  LPDWORD lpnLengthNeeded                        
);  

Parameters

lpwcsFormatName

[in] Pointer to the format name string of the queue whose security information will be retrieved. A public or private format name can be used to specify the queue. You can use a direct format name only to obtain information from the security descriptor of a local private queue. See "Remarks" for limitations on private queues.

SecurityInformation

[in] Specifies a SECURITY_INFORMATION value that identifies the component or components of access control information being requested. The information requested is placed in the security descriptor buffer pointed to by the pSecurityDescriptor parameter. The following SECURITY_INFORMATION bit flags or a combination of these bit flags can be used to identify the components of security information being retrieved.

DACL_SECURITY_INFORMATION

Indicates that the discretionary access control list (DACL) is being retrieved.

GROUP_SECURITY_INFORMATION

Indicates that the primary group security identifier is being retrieved.

OWNER_SECURITY_INFORMATION

Indicates that the owner's security identifier (SID) is being retrieved.

SACL_SECURITY_INFORMATION

Indicates that the system access control list (SACL) is being retrieved.

Not Supported

Message Queuing does not support the use of the following bit flags in this parameter.

PROTECTED_DACL_SECURITY_INFORMATION

PROTECTED_SACL_SECURITY_INFORMATION

UNPROTECTED_DACL_SECURITY_INFORMATION

UNPROTECTED_SACL_SECURITY_INFORMATION

pSecurityDescriptor

[out] Pointer to the SECURITY_DESCRIPTOR structure (security descriptor buffer) that receives the components of the queue's security information requested. The SECURITY_DESCRIPTOR structure is returned in the self-relative format. Setting this parameter to NULL is not recommended.

nLength

[in] Specifies the size, in bytes, of the security descriptor buffer (see pSecurityDescriptor).

lpnLengthNeeded

[out] Pointer to a variable that indicates if any additional length is needed for the security descriptor. If the security descriptor fits in the buffer, this variable indicates the actual size of the security descriptor.

If the security descriptor buffer is too small for the security descriptor (the value of lpnLengthNeeded is greater than the value of nLength), this variable indicates the size of the buffer needed to hold the security descriptor. When this happens, the security descriptor is not copied to the buffer and MQ_ERROR_SECURITY_DESCRIPTOR_TOO_SMALL is returned.

Return Values

MQ_OK

Indicates success.

MQ_ERROR_ACCESS_DENIED (0xC00E0025)

The access rights for getting the queue's security descriptor are not allowed for the calling process. For more information on queue access rights, see Access Control.

To change access rights of the queue, call MQSetQueueSecurity.

MQ_ERROR_ILLEGAL_FORMATNAME (0xC00E001E)

The lpwcsFormatName parameter specified an illegal format name.

MQ_ERROR_NO_DS (0xC00E0013)

A connection with the directory service cannot be established. Verify permissions for accessing the directory service.

MQ_ERROR_PRIVILEGE_NOT_HELD (0xC00E0026)

The process does not have the proper privilege to read the queue's system access control list.

MQ_ERROR_SECURITY_DESCRIPTOR_TOO_SMALL (0xC00E0023)

The buffer pointed to by pSecurityDescriptor is too small to hold the security descriptor; the returned value of lpnLengthNeeded is greater than the supplied value of nLength.

MQ_ERROR_UNSUPPORTED_FORMATNAME_OPERATION (0xC00E0020)

The format name specified in the lpwcsFormatName parameter cannot be used. You cannot reference a public queue or a remote private queue in a call to this function using a direct format name, nor can you get the security descriptor of a journal, dead-letter, or connector queue.

Remarks

The queue's security descriptor is initially set when the queue is created (see MQCreateQueue). Access to the following queue operations can be controlled: creating, deleting, and opening the queue for sending messages to and reading messages from the queue; getting and setting the queue's properties; and getting and setting the queue's security descriptor.

The security descriptor of a local or remote public queue can be retrieved, but you can only retrieve the security descriptor of a private queue if it is located on your local computer.

The security descriptor of a journal, dead-letter, connector, and foreign queue cannot be retrieved.

To read the security descriptor of a queue, the calling process must be allowed READ_CONTROL access or be the owner of the queue. Access rights such as READ_CONTROL are set when the queue is created and can be modified by calling MQSetQueueSecurity.

To read the queue's system access control list, the caller must have SE_SECURITY_NAME privileges on the directory service server (for public queues) or on the local computer (for private queues).

A public queue's security descriptor cannot be retrieved if there is no connection to the directory service. This restriction applies to dependent client computers, independent client computers that are working offline, and Message Queuing routing servers (FRS).

Reading the Access Mask of an Access Control Entry

The following flags can be used to interpret access rights in the access mask of an access control entry (ACE) in the security descriptor.

• MQSEC_DELETE_MESSAGE

• MQSEC_PEEK_MESSAGE

• MQSEC_WRITE_MESSAGE

• MQSEC_DELETE_JOURNAL_MESSAGE

• MQSEC_SET_QUEUE_PROPERTIES

• MQSEC_GET_QUEUE_PROPERTIES

• MQSEC_DELETE_QUEUE

• MQSEC_GET_QUEUE_PERMISSONS

• MQSEC_CHANGE_QUEUE_PERMISSIONS

• MQSEC_TAKE_QUEUE_OWNERSHIP

• MQSEC_RECEIVE_MESSAGE

  (MQSEC_DELETE_MESSAGE | MQSEC_PEEK_MESSAGE)

• MQSEC_RECEIVE_JOURNAL_MESSAGE

  (MQSEC_DELETE_JOURNAL_MESSAGE | \

  MQSEC_PEEK_MESSAGE)

• MQSEC_QUEUE_GENERIC_READ

  (MQSEC_GET_QUEUE_PROPERTIES |

  MQSEC_GET_QUEUE_PERMISSIONS |

  MQSEC_GET_RECEIVE_MESSAGE |

  MQSEC_GET_RECEIVE_JOURNAL_MESSAGE)

• MQSEC_QUEUE_GENERIC_WRITE

  (MQSEC_GET_QUEUE_PROPERTIES | \

  MQSEC_GET_QUEUE_PERMISSIONS | \

  MQSEC_GET_WRITE_MESSAGE)

• MQSEC_QUEUE_GENERIC_ALL

  (MQSEC_RECEIVE_MESSAGE | \

  MQSEC_RECEIVE_MESSAGE_JOURNAL | \

  MQSEC_WRITE_MESSAGE |

  MQSEC_SET_QUEUE_PROPERTIES |

  MQSEC_GET_QUEUE_PROPERTIES |

  MQSEC_GET_DELETE_QUEUE |

  MQSEC_GET_QUEUE_PERMISSIONS |

  MQSEC_GET_CHANGE_QUEUE_PERMISSIONS |

  MQSEC_TAKE_QUEUE_OWNERSHIP)

Example Code

The following code examples are included in Using Message Queuing.

Requirements

Windows NT/2000/XP: Included in Windows NT 4.0 SP3 and later.

Windows 95/98/Me: Included in Windows 95 and later.

Header: Declared in Mq.h.

Library: Use Mqrt.lib.

See Also

Message Queuing Functions
MQCreateQueue
MQSetQueueSecurity