3.1.4.5.2 LsarEnumerateAccounts (Opnum 11)

The LsarEnumerateAccounts method is invoked to request a list of account objects in the server's database. The method can be called multiple times to return its output in fragments.

 NTSTATUS LsarEnumerateAccounts(
   [in] LSAPR_HANDLE PolicyHandle,
   [in] [out] unsigned long *EnumerationContext,
   [out] PLSAPR_ACCOUNT_ENUM_BUFFER EnumerationBuffer,
   [in] unsigned long PreferedMaximumLength
 );

PolicyHandle: An RPC context handle obtained from either LsarOpenPolicy or LsarOpenPolicy2.

EnumerationContext: A pointer to a context value that is used to resume enumeration, if necessary.

EnumerationBuffer: A pointer to a structure that will contain the results of the enumeration.

PreferedMaximumLength: A value that indicates the approximate size of the data to return.

Return Values: The following is a summary of the return values that an implementation MUST return, as specified by the message processing that follows.

Return value/code	Description
0x00000000 STATUS_SUCCESS	The request was successfully completed.
0xC0000022 STATUS_ACCESS_DENIED	The caller does not have the permissions to perform this operation.
0x00000105 STATUS_MORE_ENTRIES	More information is available to successive calls.
0x8000001A STATUS_NO_MORE_ENTRIES	No more entries are available from the enumeration.
0xC0000008 STATUS_INVALID_HANDLE	PolicyHandle is not a valid handle.

Processing:

This message takes four arguments:

PolicyHandle: An open handle to the policy object. If the handle is not a valid context handle to the policy object or PolicyHandle.HandleType does not equal "Policy", the server MUST return STATUS_INVALID_HANDLE. The server MUST verify that PolicyHandle grants access as specified in section 3.1.4.2.2 with RequiredAccess set to POLICY_VIEW_LOCAL_INFORMATION. If IsRequestorAnonymous() returns TRUE (section 3.1.4.2.3) and LsaRestrictAnonymous is set to TRUE, the call MUST fail with STATUS_ACCESS_DENIED.

EnumerationContext: A number that indicates a starting index at which to begin the enumeration. The server MUST always return all account objects in the same order, starting at the object whose index is EnumerationContext. To initiate a new enumeration, the client sets EnumerationContext to zero; otherwise, the client sets EnumerationContext to a value returned by a previous call to the method.

The server MUST return STATUS_INVALID_PARAMETER if the EnumerationContext parameter is NULL.

EnumerationBuffer: Used to return the results of enumeration. The server MUST fill EnumerationBuffer with as many account objects as possible, as determined by PreferedMaximumLength. If the size of all remaining objects is less than or equal to PreferedMaximumLength, the server MUST fill EnumerationBuffer with all objects. If the size of all remaining objects is greater than PreferedMaximumLength, the server MUST fill EnumerationBuffer with objects such that the size of the account objects returned is greater than or equal to PreferedMaximumLength, but would be less than PreferedMaximumLength if the last object had not been added to EnumerationBuffer. If there are no more objects than are returned in EnumerationBuffer, the server MUST return STATUS_NO_MORE_ENTRIES. If there are more database objects than are returned in EnumerationBuffer, the server MUST set the EnumerationContext value to the index value that would allow it to resume enumeration correctly when this method is called again, and the server MUST return STATUS_MORE_ENTRIES. Note that this return value is not an error status.

PreferedMaximumLength: An indication about the approximate size, in bytes, of the data to return. Any unsigned 32-bit value is valid for the PreferedMaximumLength parameter.