3.2.4.10 NetrUseEnum (Opnum 11)

  • Article

The NetrUseEnum method lists open connections between a workstation server and a remote SMB server. The server SHOULD NOT allow this method to be invoked remotely<51> and SHOULD return ERROR_CALL_NOT_IMPLEMENTED.

 unsigned long NetrUseEnum(
   [in, string, unique] WKSSVC_IDENTIFY_HANDLE ServerName,
   [in, out] LPUSE_ENUM_STRUCT InfoStruct,
   [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.

InfoStruct: The USE_ENUM_STRUCT structure (section 2.2.5.29) contains a Level parameter that indicates the type of structure to return.

Value

Meaning

0x00000000

Specifies a local device name and the share name of a remote resource.

0x00000001

Specifies details about the connection between a local device and a shared resource, including connection status and connection type.

0x00000002

Specifies details about the connection between a local device and a shared resource, including connection status, connection type, user name, and domain name.

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 that can be passed in subsequent calls to this method in order 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: The method returns 0x00000000 (NERR_Success) to indicate success; otherwise, it returns a nonzero error code. The method can take any specific error code value ([MS-ERREF] section 2.2). The most common error codes are listed in the following table.

Value/code

Meaning

NERR_Success

0x00000000

The client request succeeded.

ERROR_INVALID_LEVEL

0x0000007C

The system call level is not correct.

ERROR_MORE_DATA

0x000000EA

The client request succeeded. More entries are available. Not all entries could be returned in the buffer size that is specified by PreferredMaximumLength.

ERROR_NOT_ENOUGH_MEMORY

0x00000008

Not enough storage is available to process this command.

NERR_BufTooSmall

0x0000084B

The client request succeeded. More entries are available. The buffer size that is specified by PreferredMaximumLength was too small to fit even a single entry.

The server SHOULD<52> 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.

The InfoStruct parameter has a Level member. The value of Level MUST be 0, 1, or 2. If the Level member is not equal to one of the valid values, the server MUST fail the call with an ERROR_INVALID_LEVEL error code.

The server MUST invoke the event to impersonate the client ([MS-RPCE] section 3.3.3.4.3.1), passing in NULL as input parameter. If this event fails, the server MUST return an error. If the event returns UserToken, the server MUST look in the UseTable for the user where UseEntry.UserToken matches UserToken. If no match is found, the server MUST set the value of TotalEntries to 0 and return a NERR_Success.

If a matching UserToken is found for the user in UseTable, the server MUST enumerate connections in UseEntry.ConnectionTable and fill the return structures as follows:

  • If the Level member is 0, the server MUST return details about the connection by filling the USE_INFO_0_CONTAINER structure (section 2.2.5.26) in the Buffer field of the InfoStruct parameter as follows. USE_INFO_0_CONTAINER contains an array of USE_INFO_0 structures (section 2.2.5.22).

    • ui0_local set to Connection.local

    • ui0_remote set to Connection.remote

  • If the Level member is 1, the server MUST return details about the connection by filling the USE_INFO_1_CONTAINER structure (section 2.2.5.27) in the Buffer field of the InfoStruct parameter as follows. The USE_INFO_1_CONTAINER structure contains an array of USE_INFO_1 structures (section 2.2.5.23).

    • ui1_local set to Connection.local

    • ui1_remote set to Connection.remote

    • ui1_password set to NULL

    • ui1_status set to Connection.status

    • ui1_asg_type set to Connection.asgtype

    • ui1_refcount set to Connection.refcount

    • ui1_usecount set to Connection.useCount

  • If the Level member is 2, the server MUST return details about the connection by filling the USE_INFO_2_CONTAINER structure (section 2.2.5.28) in the Buffer field of the InfoStruct parameter as follows. USE_INFO_2_CONTAINER contains an array of USE_INFO_2 structures (section 2.2.5.24).

    • ui2_local set to Connection.local

    • ui2_remote set to Connection.remote

    • ui2_password set to NULL

    • ui2_status set to Connection.status

    • ui2_asg_type set to Connection.asgtype

    • ui2_refcount set to Connection.refcount

    • ui2_usecount set to Connection.useCount

    • ui2_domainname set to Connection.domain

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

The following rules specify processing of the ResumeHandle parameter:

  • If the ResumeHandle parameter either is NULL or points to 0x00000000, the enumeration MUST start from the beginning of the list of the currently established connections.

  • If the ResumeHandle parameter is nonzero, the server MUST begin enumeration based on the value of ResumeHandle. The server is not required to maintain any state between calls invoking the NetrUseEnum method.

  • If the client specified ResumeHandle and if the server returns NERR_BufTooSmall, the server MUST set ResumeHandle to an implementation-specific value<53> that allow the server to continue with this enumeration on a subsequent call to this method, using the same value for ResumeHandle.

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

The server MUST invoke the event to end the client impersonation ([MS-RPCE] section 3.3.3.4.3.3).