A client calls the R_QMGetObjectSecurityInternal method to retrieve the security configuration of a private queue located on the supporting server.

 HRESULT R_QMGetObjectSecurityInternal(
   [in] handle_t hBind,
   [in] struct OBJECT_FORMAT* pObjectFormat,
   [in] DWORD RequestedInformation,
   [out, size_is(nLength)] unsigned char* pSecurityDescriptor,
   [in, range(0, 524288)] DWORD nLength,
   [out] DWORD* lpnLengthNeeded
 );

hBind:  MUST be set to an RPC binding handle as described in [MS-RPCE] section 2.

pObjectFormat:  MUST point to an OBJECT_FORMAT structure which identifies an existing local private queue on the supporting server for which the security configuration is to be retrieved. It MUST NOT be NULL. The ObjType member of the structure MUST be 0x00000001, and the pQueueFormat member MUST NOT be NULL.

RequestedInformation:  MUST contain a value from the SECURITY_INFORMATION enumeration which indicates the portions of the SECURITY_DESCRIPTOR ([MS-DTYP] section 2.4.6) to be retrieved from the queue identified by pObjectFormat. The SECURITY_INFORMATION enumeration is defined in [MS-MQMQ] section 2.2.3.

pSecurityDescriptor:  MUST be a pointer to an array of bytes into which the server MUST write a self-relative SECURITY_DESCRIPTOR structure. The server MUST NOT write more than nLength bytes to the buffer. If the buffer provided by the client is too small (as indicated by the nLength parameter) to contain the SECURITY_DESCRIPTOR for the queue identified by pObjectFormat, the server MUST return MQ_ERROR_SECURITY_DESCRIPTOR_TOO_SMALL (0xc00e0023). This parameter can be NULL if nLength is 0x00000000.

The SECURITY_DESCRIPTOR structure is defined in [MS-DTYP] section 2.4.6.

nLength:  MUST indicate the byte length of the buffer pointed to by pSecurityDescriptor. This value can be 0x00000000.

lpnLengthNeeded: MUST NOT be NULL. The server MUST set this DWORD to the byte length of the SECURITY_DESCRIPTOR structure for the queue identified by pObjectFormat.

Return Values: On success, this method MUST return MQ_OK (0x00000000); otherwise, the server MUST return a failure HRESULT,<33> and the client MUST treat all failure HRESULTs identically. Additionally, if a failure HRESULT is returned, the client MUST disregard all out-parameter values with the following exception:

If nLength is less than the byte length of the buffer required to contain the SECURITY_DESCRIPTOR for the queue identified by pObjectFormat, the server MUST return the byte length of the buffer required to contain the SECURITY_DESCRIPTOR in the lpnLengthNeeded parameter and MUST return MQ_ERROR_SECURITY_DESCRIPTOR_TOO_SMALL (0xc00e0023).

Exceptions Thrown: No exceptions are thrown beyond those thrown by the underlying RPC protocol, as specified in [MS-RPCE].

This method is invoked at the dynamically assigned endpoint returned by the R_QMGetRTQMServerPort method when IP_HANDSHAKE (0x00000000) or IPX_HANDSHAKE (0x00000002) is the interface specified by the fIP parameter.

When processing this call, the server MUST:

• Determine if input parameter values violate constraints specified preceding. If an invalid parameter is detected, the server MUST take no further action and return a failure HRESULT.

• Raise a Get Queue Path event ([MS-MQDMPR] section 3.1.7.1.26) with the following argument:

  • iFormatName: pObjectFormat.pQueueFormat.m_qft

• If the rStatus return argument value is not MQ_OK (0x00000000) or the rPathName return argument is empty, take no further action and return a failure HRESULT.

• Locate a Queue ([MS-MQDMPR] section 3.1.1.2) ADM element instance in the QueueCollection attribute of the server's LocalQueueManager ([MS-MQDMPR] section 3.1.1) ADM element instance identified by the rPathName return argument value.

• If no entry is resolved, return a failure HRESULT.

• Let ReturnedDescriptor be a SECURITY_DESCRIPTOR initialized to be empty.

• If the OWNER_SECURITY_INFORMATION bit is set in RequestedInformation:

  • Copy the contents of the Queue.Security.OwnerSid field ([MS-DTYP] section 2.4.6) to ReturnedDescriptor.OwnerSid.

• Else If the GROUP_SECURITY_INFORMATION bit is set in RequestedInformation:

  • Copy the contents of the Queue.Security.GroupSid field ([MS-DTYP] section 2.4.6) to ReturnedDescriptor.GroupSid.

• Else If the DACL_SECURITY_INFORMATION bit is set in RequestedInformation:

  • Copy the contents of the Queue.Security.Dacl field ([MS-DTYP] section 2.4.6) to ReturnedDescriptor.Dacl.

• Else If the SACL_SECURITY_INFORMATION bit is set in RequestedInformation:

  • Copy the contents of the Queue.Security.Sacl field ([MS-DTYP] section 2.4.6) to ReturnedDescriptor.Sacl.

• Set lpnLengthNeeded to the size in bytes of ReturnedDescriptor.

• If lpnLengthNeeded is greater than nLength, return MQ_ERROR_SECURITY_DESCRIPTOR_TOO_SMALL(0xc00e0023).

• Else copy ReturnedDescriptor into the pSecurityDescriptor buffer.

• Return MQ_OK (0x00000000).