3.1.4.8.1 LsarEnumeratePrivileges (Opnum 2)

The LsarEnumeratePrivileges method is invoked to enumerate all privileges known to the system. This method can be called multiple times to return its output in fragments.

 NTSTATUS LsarEnumeratePrivileges(
   [in] LSAPR_HANDLE PolicyHandle,
   [in, out] unsigned long* EnumerationContext,
   [out] PLSAPR_PRIVILEGE_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 be returned.

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.
0xC000000D STATUS_INVALID_PARAMETER	One of the parameters supplied was invalid. This can happen if EnumerationBuffer is NULL or EnumerationContext is NULL.
0xC0000008 STATUS_INVALID_HANDLE	PolicyHandle is not a valid handle.

Processing:

This method takes four arguments:

PolicyHandle: 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.

EnumerationContext: A number that indicates a starting index at which to begin the enumeration. The server MUST always return all privileges 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 privilege 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 privilege 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.