MQGetQueueSecurity

The MQGetQueueSecurity function retrieves the access control security descriptor for 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. Use a public or private format name to specify the queue. You cannot specify a direct format name.

SecurityInformation

[in] Specifies the SECURITY_INFORMATION structure that identifies the access control information being requested. (For information on the SECURITY_INFORMATION structure, see the Microsoft Platform SDK.)

pSecurityDescriptor

[out] Pointer to the security descriptor buffer that receives the queue's security descriptor. The calling process must have the rights to view the specified aspects of the queue's security status. The SECURITY_DESCRIPTOR structure is returned in self-relative format. (For information on the SECURITY_DESCRIPTOR structure, see the Microsoft Platform SDK.)

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_BUFFER_TOO_SMALL is returned.

Return Values

MQ_OK

Indicates success.

MQ_ERROR_ACCESS_DENIED

The process does not have the correct access rights to get the queue's security descriptor. For a complete list of queue access rights, see Access Control.

To change access rights, call MQSetQueueSecurity.

MQ_ERROR_FUNCTION_NOT_SUPPORTED

MQGetQueueSecurity is not supported in Windows 95.

MQ_ERROR_ILLEGAL_FORMATNAME

The lpwcsFormatName parameter specified an illegal format name.

MQ_ERROR_NO_DS

Cannot access Active Directory.

MQ_ERROR_PRIVILEGE_NOT_HELD

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

MQ_ERROR_SECURITY_DESCRIPTOR_BUFFER_TOO_SMALL

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

The lpwcsFormatName parameter contains a public or private queue using a direct format name or 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 format name of the queue (specified by lpwcsFormatName) must be a public or private format name. For public queues, MSMQ must be able to access Active Directory. For private queues, MSMQ must access the local computer.

If the format name of the queue is unknown, see Format Name to find ways to obtain a new format name.

To read the security descriptor of a queue, the calling process must have 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 Active Directory server (for public queues) or on the local computer (for private queues).

MQGetQueueSecurity cannot retrieve the security descriptor of a journal, dead letter, connector, or foreign queue.

A public queue's security descriptor cannot be retrieved if there is no connection to Active Directory. This restriction applies to dependent client computers, independent client computers that are working offline, and MSMQ routing servers (FRS). (For information on offline operations, see MSMQ Offline Support.)

QuickInfo

  Windows NT: Requires version 4.0 SP3 or later.
  Windows: Requires Windows 95 or later.
  Windows CE: Unsupported.
  Header: Declared in mq.h.
  Import Library: Use mqrt.lib.
  Unicode: Defined only as Unicode.

See Also

MQSetQueueSecurity