Share via

3.1.4.16 S_DSQMSetMachineProperties (Opnum 19)

  • Article

This method sets properties associated with a machine object specified by a directory service pathname. This method is intended for use by a queue manager to manipulate its own directory service object of type MQDS_MACHINE. Client applications SHOULD NOT use this method.<76>

 HRESULT S_DSQMSetMachineProperties(
   [in] handle_t hBind,
   [in] const wchar_t* pwcsPathName,
   [in, range(1,128)] unsigned long cp,
   [in, size_is(cp)] unsigned long aProp[],
   [in, size_is(cp)] PROPVARIANT apVar[],
   [in] unsigned long dwContext
 );

hBind: MUST specify an RPC binding handle, as specified in [MS-RPCE] section 2.

pwcsPathName: Pointer to a NULL-terminated 16-bit Unicode string that MUST contain the directory service pathname, as specified in section 2.2.9, of a machine object in the directory service.

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:  An array of identifiers of properties to associate with the machine object. Each element MUST specify a value from the property identifiers table, as specified in section 2.2.10.1. Each element MUST specify the property identifier for the corresponding property value at the same element index in apVar. The array MUST contain at least one element.

apVar:  An array that specifies the property values to associate with the machine object. Each element MUST specify the property value for the corresponding property identifier at the same element index in aProp. The array MUST contain at least one element.

dwContext:  MUST be set by the client to a value that the client can use to correlate callbacks with the initial call to S_DSQMSetMachineProperties. The server MUST supply this value in the dwContext parameter in the related calls of the S_DSQMSetMachinePropertiesSignProc (section 3.2.4.1) callback method.

Return Values:  If the method succeeds, the return value is 0. If the method fails, the return value is an implementation-specific error code.

MQ_OK (0x00000000)

MQ_ERROR_ILLEGAL_PROPID (0xC00E0039)

MQ_ERROR (0xC00E0001)

MQ_ERROR_DS_ERROR (0xC00E0043)

MQDS_OBJECT_NOT_FOUND (0xC00E050F)

E_ADS_PROPERTY_NOT_FOUND (0x8000500D)

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

When processing this call, the server MUST:

  • The server MAY invoke the S_DSQMSetMachinePropertiesSignProc callback method to authenticate the client.<77>

  • Verify that the arrays aProp and apVar contain at least one element. If not, the server SHOULD<78> return an error.

  • The server MUST return an error code if the property identifier is not valid for an object of type MQDS_MACHINE.<79>

  • The server MAY<80> forward the update to another server.

  • Determine if each element of apVar specifies the property value for the corresponding property identifier at the same element index in aProp.

  • Generate the Get Directory Object for Update (section 3.1.6.14) event with the following arguments:

    • iObjectType := MQDS_MACHINE

    • iPathName := pwcsPathName

    • iGuid := NULL

  • If rStatus returned by the event is not 0x00000000, return rStatus and take no further action; otherwise, save rObject, referred to as dirObject.

  • For each element in the aProp array, populate the corresponding element of the apVar array according to the rules specified in section 3.1.4.21.8.1.1 and add the ADM element attribute name to a list, referred to as attrList. If any of the aProp elements is not present in the rules in section 3.1.4.21.8.1.1, return error HRESULT.<81>

  • Generate the Commit Directory Object Update (section 3.1.6.15) event with the arguments set to dirObject and attrList respectively. If the event returns DirectoryOperationResult.Success, set rStatus to 0x00000000; otherwise, set rStatus to a failure HRESULT and take no further action.

  • `The server MAY<82> contact other servers to propagate the changes.

  • If the dirObject.Identifier is different from the LocalQueueManager.Identifier, the server MAY<83> do the following:

  • iDirectoryObject := dirObject