3.1.4.38 NetrDfsSetLocalVolumeState (Opnum 46)

  • Article

The NetrDfsSetLocalVolumeState method sets a local DFS share online or offline. An implementation MAY<142> choose to support this method.

 NET_API_STATUS NetrDfsSetLocalVolumeState(
   [in, string, unique] SRVSVC_HANDLE ServerName,
   [in] GUID* Uid,
   [in, string] WCHAR* Prefix,
   [in] unsigned long State
 );

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). The server MUST ignore this parameter.

Uid: Specifies the GUID of the DFS share. This GUID MUST be obtained by using the NetrDfsGetInfo (Opnum 4) method, as specified in [MS-DFSNM] section 3.1.4.1.6.

Prefix: A pointer to a null-terminated UTF-16 string that specifies the path to the DFS share.

State: A DWORD that specifies the new state for the DFS share. To set the share to offline, the State parameter MUST be (0x80). The State parameter MUST be set to any other value to take the share online.

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 NetrDfsSetLocalVolumeState message, the server SHOULD<143> choose to perform no processing and return an implementation-specific error code when this method is called. If the server supports DFS, the server MAY set the state of a local DFS share to online or offline. Marking a share state offline makes the share inaccessible over DFS.

The Uid parameter specifies the GUID of the share whose state needs to be set.

The Prefix parameter specifies the path of the DFS share whose state needs to be set. This parameter MUST refer to a local DFS share. If the server does not find a DFS share whose path starts with the value of the Prefix parameter and whose GUID matches the value of the Uid parameter, the server MUST fail the call and return an implementation-specific error code.

The State parameter specifies whether the share state MUST be set to online or offline. If the value of State is 0x80, the share state MUST be set to offline. For any other value, the share state MUST be set to online.

The server MAY<144> enforce security measures to verify that the caller has the required permissions to execute this call. If the server enforces these security measures and the caller does not have the required credentials, the server SHOULD<145> fail the call.