3.2.4.3 NetrWkstaUserEnum (Opnum 2)

  • Article

The NetrWkstaUserEnum method returns details about users who are currently active on a remote computer.

 unsigned long NetrWkstaUserEnum(
   [in, string, unique] WKSSVC_IDENTIFY_HANDLE ServerName,
   [in, out] LPWKSTA_USER_ENUM_STRUCT UserInfo,
   [in] unsigned long PreferredMaximumLength,
   [out] unsigned long* TotalEntries,
   [in, out, unique] unsigned long* ResumeHandle
 );

ServerName: A WKSSVC_IDENTIFY_HANDLE structure (section 2.2.2.1) that identifies the server (2). The client MUST map this structure to an RPC binding handle ([C706] sections 4.3.5 and 5.1.5.2). The server MUST ignore this parameter.

UserInfo: A pointer to the buffer to receive the data. The data MUST be returned as a WKSTA_USER_ENUM_STRUCT structure (section 2.2.5.14) that contains a Level member that specifies the type of structure to return.

PreferredMaximumLength: The number of bytes to allocate for the return data.

TotalEntries: The total number of entries that could have been enumerated if the buffer were big enough to hold all the entries.

ResumeHandle: A pointer that, if specified, and if this method returns ERROR_MORE_DATA, MUST receive an implementation-specific value<34> that can be passed in subsequent calls to this method, to continue with the enumeration of currently logged-on users.

If this parameter is NULL or points to zero, the enumeration MUST start from the beginning of the list of currently logged-on users.

Return Values: When the message processing result matches the description in column two of the following table, this method MUST return one of the following values ([MS-ERREF] section 2.2). The most common error codes are listed in the following table.

Value/code

Meaning

NERR_Success

0x00000000

The operation completed successfully.

ERROR_ACCESS_DENIED

0x00000005

Access is denied.

ERROR_INVALID_LEVEL

0x0000007C

The information level is invalid.

ERROR_MORE_DATA

0x000000EA

More entries are available. The UserInfo buffer was not large enough to contain all the entries.

Any other return value MUST conform to the error code requirements in Protocol Details (section 3).

The server (2) SHOULD<35> enforce security measures to verify that the caller has the required permissions to execute this routine. If the server enforces security measures, and the caller does not have the required credentials, the server MUST fail the call with ERROR_ACCESS_DENIED. Specifications for determining the identity of the caller for the purpose of performing an access check are in [MS-RPCE] section 3.3.3.1.3.

If the Level member of the WKSTA_USER_ENUM_STRUCT structure passed in the UserInfo parameter does not equal 0x00000000 or 0x00000001, the server MUST fail the call.

If the Level member equals 0x00000000, the server MUST return an array of the names of users currently logged on the computer by filling the WKSTA_USER_INFO_0_CONTAINER structure (section 2.2.5.14) in the WkstaUserInfo field of the UserInfo parameter.

If the Level member equals 0x00000001, the server MUST return an array of the names and domain details of each user currently logged on the computer, and a list of OtherDomains (section 3.2.1.3) in the computer.

If the PreferredMaximumLength parameter equals MAX_PREFERRED_LENGTH (section 2.2.1.3), the server MUST return all the requested data. Otherwise, if the PreferredMaximumLength is insufficient to hold all the entries, then the server MUST return the maximum number of entries that fit in the UserInfo buffer and return ERROR_MORE_DATA.

The following rules specify processing of the ResumeHandle parameter:

  • If the ResumeHandle parameter is either NULL or points to 0x00000000, the enumeration MUST start from the beginning of the list of the currently logged on users.<36>

  • If the ResumeHandle parameter points to a non-zero value, the server MUST continue enumeration based on the value of ResumeHandle. The server is not required to maintain any state between calls to the NetrWkstaUserEnum method.

  • If the client specifies a ResumeHandle, and if the server returns ERROR_MORE_DATA, the server MUST set the value to which ResumeHandle points to an implementation-specific value that allow the server to continue with this enumeration on a subsequent call to this method, with the same value for ResumeHandle.

The server is not required to maintain any state between calls to the NetrWkstaUserEnum method. If the server returns NERR_Success or ERROR_MORE_DATA, it MUST set the TotalEntries parameter to equal the total number of entries that could have been enumerated from the current resume position.