Share via

3.1.4.5 R_QMCreateObjectInternal (Opnum 6)

  • Article

A client calls the R_QMCreateObjectInternal method to create a new private queue located on the supporting server.

 HRESULT R_QMCreateObjectInternal(
   [in] handle_t hBind,
   [in] DWORD dwObjectType,
   [in, string] const WCHAR* lpwcsPathName,
   [in, range(0, 524288)] DWORD SDSize,
   [in, unique, size_is(SDSize)] unsigned char* pSecurityDescriptor,
   [in, range(1, 128)] DWORD cp,
   [in, size_is(cp)] DWORD aProp[],
   [in, size_is(cp)] PROPVARIANT apVar[]
 );

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

dwObjectType:  MUST be 0x00000001 in order to specify a queue.

lpwcsPathName:  MUST be a pointer to a null-terminated string containing a path name for the queue to be created. The path name MUST identify a private queue local to the supporting server by including "." as the computer name or by using the supporting server computer name.

SDSize:  MUST be set to the byte length of the SECURITY_DESCRIPTOR buffer pointed to by pSecurityDescriptor. If pSecurityDescriptor is NULL, this parameter MUST be 0x00000000.

pSecurityDescriptor:  Must be a pointer to an array of bytes containing a SECURITY_DESCRIPTOR structure. The SECURITY_DESCRIPTOR specifies the initial security configuration for the queue to be created. This value can be NULL, in which case the server MUST provide a default security configuration for the new queue. The SECURITY_DESCRIPTOR structure is defined in [MS-DTYP] section 2.4.6.

cp:  MUST be set to the size (in elements) of the arrays aProp and apVar. The arrays aProp and apVar MUST have an identical number of elements and MUST contain at least one element.

aProp:  MUST be an array of queue property identifiers that, together with the apVar array, specify the initial queue property values for the new queue. Each element MUST specify a value from the queue property identifiers table defined in [MS-MQMQ] section 2.3.1. Each element MUST specify the property identifier for the corresponding property value at the same element index in apVar and MUST contain at least one element. Each element MUST contain a queue property identifier; identifiers for other properties are not permitted.

If the queue identified by lpwcsPathName already exists, the server MUST NOT alter the existing queue.

apVar:  MUST be an array that specifies the property values to associate with the new queue. Each element MUST specify the property value for the corresponding property identifier at the same element index in aProp and MUST contain at least one element.

Return Values:  On success, this method MUST return MQ_OK (0x00000000); otherwise, the server MUST return a failure HRESULT.<30><31> If the returned HRESULT value is MQ_ERROR_QUEUE_EXISTS (0xc00e0005), the client can treat it as a success and continue with other operations. The client MUST treat all other 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 the constraints specified above. If an invalid parameter is detected, the server MUST take no further action and return a failure HRESULT other than MQ_ERROR_QUEUE_EXISTS (0xc00e0005).

  • 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 where the value of the Pathname attribute of the Queue ADM element instance matches the lpwcsPathName parameter.

  • If found, take no further action, and return MQ_ERROR_QUEUE_EXISTS (0xc00e0005).

  • Let newQueue be a new Queue ADM element instance.

  • Generate a Set Queue Defaults ([MS-MQDMPR] section 3.1.7.1.33) event with the following argument value:

    • iQueue := newQueue

  • Set newQueue.Pathname to lpwcsPathName.

  • Set newQueue.Security to the value contained in the pSecurityDescriptor parameter.

  • Initialize the remaining attribute values of newQueue using the aProp parameter and the apVar parameter property arrays described preceding. The queue property identifiers and their relationships to the Queue ADM element are specified in section 3.1.1.12.

  • Generate a Create Queue ([MS-MQDMPR] section 3.1.7.1.3) event with the following argument value:

    • iQueue := newQueue

  • Return the rStatus of the Create Queue event.