3.2.4.8 NetrUseGetInfo (Opnum 9)

  • Article

The NetrUseGetInfo method retrieves details from a remote workstation about a connection to a shared resource on an SMB server. The server SHOULD NOT allow this method to be invoked remotely<47> and SHOULD return ERROR_CALL_NOT_IMPLEMENTED.

 unsigned long NetrUseGetInfo(
   [in, string, unique] WKSSVC_IMPERSONATE_HANDLE ServerName,
   [in, string] wchar_t* UseName,
   [in] unsigned long Level,
   [out, switch_is(Level)] LPUSE_INFO InfoStruct
 );

ServerName: A WKSSVC_IMPERSONATE_HANDLE structure (section 2.2.2.2) 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.

UseName: A pointer to a string that specifies the local device name or shared resource name for which to return information.

Level: A value that specifies the information level of the data. This parameter MUST be one of the following values; otherwise, the server MUST fail the call with an ERROR_INVALID_LEVEL code.

Value

Meaning

0x00000000

The buffer is a USE_INFO_0 structure (section 2.2.5.22).

0x00000001

The buffer is a USE_INFO_1 structure (section 2.2.5.23).

0x00000002

The buffer is a USE_INFO_2 structure (section 2.2.5.24).

0x00000003

The buffer is a USE_INFO_3 structure (section 2.2.5.25).

InfoStruct: A pointer to the buffer that specifies the data. The format of this data depends on the value of the Level parameter.

Return Values: When the message processing result meets the description in the right-hand column of the following table, this method MUST return one of the following values ([MS-ERREF] section 2.2).

Value/code

Meaning

NERR_Success

0x00000000

The operation completed successfully.

ERROR_ACCESS_DENIED

0x00000005

Access is denied.

ERROR_INVALID_PARAMETER

0x00000057

One of the function parameters is not valid.

ERROR_INVALID_LEVEL

0x0000007C

The information level is invalid.

NERR_UseNotFound

0x000008CA

The network connection could not be found.

The server SHOULD<48> 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 UseName parameter specifies the local device name or shared resource name for which to return information. The server MUST canonicalize UseName ([MS-SRVS] section 3.1.4.33). This MUST be a nonempty, null-terminated UTF-16 string; otherwise, the server MUST fail the call with an ERROR_INVALID_PARAMETER error code.

The server MUST ensure that the remaining steps are executed atomically with respect to other callers performing queries or updates to the UseTable and Connection tables.

The server invokes 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 UseTable for an entry where UseEntry.UserToken matches UserToken. If no match is found, the server MUST fail the call with a NERR_UseNotFound error code.

If a match is found and UseName is a UNC path type, the server MUST locate the connection where UseName matches Connection.remote. If UseName is a local device name, the server MUST locate a UseEntry.ConnectionTable where UseName matches Connection.local. If no match is found, the server MUST fail the call with a NERR_UseNotFound error code. If a matching connection is found, the server MUST return details about the connection on the remote workstation.

The server MUST 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.

    • 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. USE_INFO_1_CONTAINER contains an array of USE_INFO_1 structures.

    • 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 or 3, 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.

    • 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_username set to Connection.username

    • ui2_domainname set to Connection.domain

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