3.1.7.1.21 Read Directory Begin

  • Article

This event MUST be generated with the following arguments:

  • iDirectoryObjectType: A string that specifies the name of the subtype of DirectoryObject ADM element instance to be read from the directory.

  • iFilter: An array of attribute-filter expressions (as defined in section 3.1.7.1.20) where the valid ADM attributes are the set of directory attributes associated with a DirectoryObject ADM element instance of type iDirectoryObjectType. Each object that is returned by the read operation MUST satisfy all attribute-filter expressions in this array. If this argument is set to NULL, all DirectoryObject ADM element instances of type iDirectoryObjectType MUST be returned.

  • iAttributeList (Optional): An array of strings containing the names of the directory attributes associated with a DirectoryObject ADM element instance of type iDirectoryObjectType to be read from the directory and included in the rDirectoryObject return value. If this argument is not supplied, all directory attributes will be read. If this argument is supplied, the values of all ADM attributes that were not specified in this list will be undefined and MUST NOT be used.

  • iAttributeSortOrder (Optional): An array of attribute-sort-order values as defined following. The elements of this array have a one-to-one correspondence with the elements of the iAttributeList array. This array represents the precedence that the corresponding ADM attributes in the iAttributeList take when ordering the returned results.

An attribute-sort-order value consists of the following:

  • SortPriority: A numeric value that indicates the order in which results would be sorted with respect to the corresponding ADM attribute. ADM attributes that have higher sort priorities are given higher precedence when sorting the result set. A value of zero indicates that the corresponding ADM attribute is not used when sorting the results.

  • SortAscending: A Boolean value that indicates whether the corresponding ADM attribute is sorted in ascending order.

Return Values:

  • rStatus: A DirectoryOperationResult that indicates the result of this directory operation.

  • rQueryHandle: A HANDLE ([MS-DTYP] section 2.2.16) that the invoker can use to iterate through the result set. This value is undefined if rStatus does not equal DirectoryOperationResult.Success.

The queue manager MUST delegate the processing of this event to the Read Directory Begin ([MS-MQDSSM] section 3.1.6.4) event.<26>