3.1.4.9 S_DSSetProps (Opnum 3)

  • Article

This method sets the specified properties for a directory object specified by a directory service pathname.

 HRESULT S_DSSetProps(
   [in] handle_t hBind,
   [in, range(1,58)] unsigned long dwObjectType,
   [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[]
 );

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

dwObjectType:  MUST specify the type of object for which properties are to be set. For supported object types, see the table of object types specified in section 2.2.8.

pwcsPathName:  Pointer to a NULL-terminated 16-bit Unicode string that MUST contain the directory service pathname, as specified in section 2.2.9, to the 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 object identified by pwcsPathName. Each element MUST specify a value from the property identifiers table defined in section 2.2.10.1 for the object type specified in dwObjectType. 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 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.

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 protocol, as specified in [MS-RPCE].

 When processing this call, the server MUST:

  • Verify that the arrays aProp and apVar contain at least one element. If not, the server SHOULD<44> take no further action and return an error HRESULT.

  • If the value of dwObjectType is not one of the values listed in the table in section 2.2.8 or is MQDS_DELETEDOBJECT, MQDS_USER, or MQDS_ROUTINGLINK, the server MUST take no further action and return a failure HRESULT.

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

  • Verify for each property identifier in aProp that the property identifier is valid for an object of type dwObjectType and that the corresponding variant in apVar is of the type defined for the property identifier, using the rules in the following table. If the object type is not in the table or any invalid property identifier or type is found, the server MUST take no further action and return a failure HRESULT.

    Value of dwObjectType

    Rules

    MQDS_QUEUE

    See [MS-MQMQ] section 2.3.1

    MQDS_MACHINE

    See [MS-MQMQ] section 2.3.2

    MQDS_SITE

    See [MS-MQMQ] section 2.3.3

    MQDS_ENTERPRISE

    See [MS-MQMQ] section 2.3.5

    MQDS_CN<46>

    See [MS-MQMQ] section 2.3.4

  • Let dirObject be a directory object and initialized to NULL.

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

    • iObjectType := dwObjectType

    • iPathName := pwcsPathName

    • iGuid := NULL

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

  • Map the values contained in aProp and apVar to dirObject attributes according to the rules specified in the following table. If any property identifier is not listed in those rules, or if the rules indicate that the property identifier is invalid, the server MUST take no further action and return a failure HRESULT.

    Value of dwObjectType

    Rules

    MQDS_QUEUE

    See section 3.1.4.21.8.2.4

    MQDS_MACHINE

    See section 3.1.4.21.8.2.1

    MQDS_SITE

    See section 3.1.4.21.8.2.8

    MQDS_ENTERPRISE

    See section 3.1.4.21.8.2.6

    MQDS_CN

    See section 3.1.4.21.8.2.10

  • Update the attributes of dirObject using the mapping from the preceding step. For each updated attribute, add the ADM element attribute name to a list, referred to as attrList.

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

  • If dwObjectType equals MQDS_QUEUE:

    • If the Computer portion of the dirObject.PathName (as described in [MS-MQMQ] section 2.1.1) is different from the LocalQueueManager.ComputerName, the server MAY do the following:<47>

      • Generate a Send Change Notification event as specified in [MS-MQCN] section 3.3.4.1 with the following arguments:

        • iOperation := QueueUpdate

        • iDirectoryObject := dirObject

  • If dwObjectType equals MQDS_MACHINE:

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

      • Generate a Send Change Notification event as specified in [MS-MQCN] section 3.3.4.1 with the following arguments:

        • iOperation := QueueManagerUpdate

        • iDirectoryObject := dirObject