Share via

3.1.4.6 R_QMSetObjectSecurityInternal (Opnum 7)

  • Article

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

 HRESULT R_QMSetObjectSecurityInternal(
   [in] handle_t hBind,
   [in] struct OBJECT_FORMAT* pObjectFormat,
   [in] DWORD SecurityInformation,
   [in, range(0, 524288)] DWORD SDSize,
   [in, unique, size_is(SDSize)] unsigned char* pSecurityDescriptor
 );

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

pObjectFormat:  MUST point to an OBJECT_FORMAT structure that identifies an existing local private queue on the supporting server for which the security configuration will be updated. This MUST NOT be NULL. The ObjType member of the structure MUST be 0x00000001. The pQueueFormat member MUST NOT be NULL.

SecurityInformation:  MUST contain a value from the SECURITY_INFORMATION enumeration which indicates the portions of the provided SECURITY_DESCRIPTOR to be applied to the queue identified by pObjectFormat. The SECURITY_INFORMATION enumeration is defined in [MS-MQMQ] section 2.2.3.

SDSize:  MUST be set to the byte length of the buffer pointed to by pSecurityDescriptor.

pSecurityDescriptor:  MUST be a pointer to an array of bytes containing a SECURITY_DESCRIPTOR structure (see [MS-DTYP] section 2.4.6).

Return Values:  On success, this method MUST return MQ_OK (0x00000000); otherwise, the server MUST return a failure HRESULT,<32> and the client MUST treat all failure HRESULTs identically.

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 above. If an invalid parameter is detected, the server MUST take no further action and return a failure HRESULT.

  • Locate a Queue in the QueueCollection of the server's QueueManager identified by pObjectFormat.

  • 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 pObjectFormat parameter.

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

  • Update the Security attribute of the Queue ADM element instance resolved preceding with the information provided by SecurityInformation, SDSize, and pSecurityDescriptor.

  • Return MQ_OK (0x00000000).