3.1.4.14 NetrShareDelStart (Opnum 37)

  • Article

The NetrShareDelStart method performs the initial phase of a two-phase share delete.

 NET_API_STATUS NetrShareDelStart(
   [in, string, unique] SRVSVC_HANDLE ServerName,
   [in, string] WCHAR* NetName,
   [in] DWORD Reserved,
   [out] PSHARE_DEL_HANDLE ContextHandle
 );

ServerName: An SRVSVC_HANDLE (section 2.2.1.1) pointer that identifies the server. The client MUST map this structure to an RPC binding handle (see [C706] sections 4.3.5 and 5.1.5.2). If this parameter is NULL, the local computer is used.

NetName: A pointer to a null-terminated UTF-16 string that specifies the name of the share to delete.

Reserved: Reserved; SHOULD be set to zero when sent and MUST be ignored on receipt.

ContextHandle: A handle for the second phase of the two-phase share delete, in the form of a PSHARE_DEL_HANDLE (section 2.2.1.3) data type.

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, as specified in [MS-ERREF] section 2.2.

In response to a NetrShareDelStart request, the server MUST mark a share for deletion and return to the client an RPC context handle that the client can use to actually perform the deletion by calling the NetrShareDelCommit method.

This two-phase deletion MUST be used to delete IPC$, which is the share that is used for named pipes. Deleting IPC$ results in the closing of the pipe on which the RPC is being executed. Thus, the client never receives the response to the RPC. The two-phase delete offers a positive response in phase 1 and then an expected error in phase 2.

If ServerName does not match any Transport.ServerName in TransportList with the SVTI2_SCOPED_NAME bit set in Transport.Flags, the server MUST reset ServerName as "*".

The server MUST remove any preceding "\\" from the ServerName parameter and normalize the ServerName parameter as specified in section 3.1.6.8, passing in the updated ServerName parameter as the ServerName, and an empty string as the ShareName.

The server MUST search through ShareList and locate a Share where Share.ShareName matches NetName and Share.ServerName matches ServerName. If a match is not found, the server MUST fail the call with an NERR_NetNameNotFound error code.

If a match is found, the server MUST mark the share for deletion by setting the IsMarkedForDeletion member of the Share element in ShareList. The share MUST remain available until the client calls the NetrShareDelCommit method.

The server MUST return a handle to the share being deleted in the ContextHandle parameter. The client is expected to use the handle to actually delete the share by calling the NetrShareDelCommit method.

The server SHOULD<76> enforce security measures to verify that the caller has the required permissions to execute this routine. If the caller does not have the required credentials, the server SHOULD<77> fail the call.