3.1.6.4 Read Directory Begin

  • Article

This event MUST be generated with the following arguments:

  • iDirectoryObjectType: A string that specifies the name of the sub-type of DirectoryObject ADM element to be read from the directory.

  • iFilter: An array of attribute-filter expressions ([MS-MQDMPR] section 3.1.7.1.20), where the valid attributes comprise 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.

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

  • iAttributeSortOrder (Optional): An array of attribute-sort-order values (as specified following). The elements of this array have a one-to-one correspondence with the elements of iAttributeList array. This array represents the precedence that the corresponding 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 attribute. Attributes that have a higher sort priority are given higher precedence when sorting the result set. A value of 0 indicates that the corresponding attribute is not used when sorting the results.

  • SortAscending: A Boolean value that indicates whether the corresponding attribute will be 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 algorithm MUST perform the following actions to process this event:

  • If iDirectoryObjectType has the value "ConnectedNetwork", rStatus MUST be set to DirectoryOperationResult.GenericError, rQueryHandle is undefined, and processing MUST end.

  • Let ReadIterator be a ReadDirectoryIteratorState (section 3.1.1.2) ADM element instance, which MUST be created. The ReadDirectoryIteratorState ADM element instance referenced by ReadIterator MUST be added to the ReadDirectoryIteratorStateCollection (section 3.1.1.3) ADM element. ReadIterator.Handle MUST be set to a value that is unique within the ReadDirectoryIteratorStateCollection ADM element. The value of iDirectoryObjectType MUST be copied to ReadIterator.DataElementType.

  • Based on iDirectoryObjectType, perform the steps of the read-begin operation for that type of ADM element, as specified in the following sections, and return the rStatus value specified in that section. The directory contents must NOT be modified by this operation.

  • If the value of rStatus is not DirectoryOperationResult.Success, the ReadDirectoryIteratorState ADM element instance referenced by ReadIterator MUST be removed from the ReadDirectoryIteratorStateCollection ADM element and discarded, rQueryHandle is undefined, and processing MUST end.

  • If the value of rStatus is DirectoryOperationResult.Success, rQueryHandle MUST be set to the value of ReadIterator.Handle, and processing MUST end.