3.2.4.9 NetrUseDel (Opnum 10)

The NetrUseDel function terminates a connection from the workstation server to a shared resource on an SMB server. The server SHOULD NOT<49> allow this method to be invoked remotely and SHOULD return ERROR_CALL_NOT_IMPLEMENTED.

 unsigned long NetrUseDel(
   [in, string, unique] WKSSVC_IMPERSONATE_HANDLE ServerName,
   [in, string] wchar_t* UseName,
   [in] unsigned long ForceLevel
 );

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.

ForceLevel: The level of force to use in deleting the connection. This parameter MUST be one of the following values; otherwise, the server MUST fail the call with an ERROR_INVALID_LEVEL error code.

Value/code	Meaning
USE_NOFORCE 0x00000000	Do not disconnect the connection if open files exist on the connection.
USE_FORCE 0x00000001	Same as 0x00000000 (USE_NOFORCE); do not disconnect the connection if open files exist on the connection.
USE_LOTS_OF_FORCE 0x00000002	Close any open files and disconnect the connection.

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 force level is invalid.
ERROR_DEVICE_IN_USE 0x00002404	The connection handle is in use and cannot be disconnected.
ERROR_REDIR_PAUSED 0x00000048	Remote access to the specified printer or serial communications device has been paused.

The server SHOULD<50> 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 delete a tree connection. 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 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 UseTable for the user 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 a UseEntry.ConnectionTable where UseName matches Connection.remote. If UseName is a local device name, the server MUST locate a UseEntry.ConnectionTable table 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 and IsWorkstationPaused is TRUE, the server MUST verify the format of Connection.local. If Connection.local is prefixed with "PRN" or "COM", the server MUST fail the call with an ERROR_REDIR_PAUSED error code. If a matching connection is found and IsWorkstationPaused is FALSE, the server MUST disconnect the connection with the server by invoking the event specified in [MS-CIFS] section 3.4.4.11, providing the Connection context handle and ForceLevel as input parameters.

If the CIFS server returns a failure, the server MUST fail the call with the status code ERROR_DEVICE_IN_USE.

If the CIFS server returns STATUS_SUCCESS, the server MUST delete the connection in UseEntry.ConnectionTable where UseName matches Connection.remote and return NERR_Success to the caller.

If UseEntry.ConnectionTable is empty, the server MUST remove the UseEntry for the user, where UseEntry.UserToken matches UserToken.

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