3.1.4.3.2 NetrDfsRemoveFtRoot (Opnum 11)

The NetrDfsRemoveFtRoot (Opnum 11) method removes the specified root target from a domainv1-based DFS namespace.<112> If the target is the last one associated with the DFS namespace, then this method also deletes the DFS namespace. The DFS namespace can be removed without first removing all of the links in it.

If a client tries to use this method on a domainv2-based DFS namespace target, then the server MUST fail with the return value of ERROR_NOT_SUPPORTED.

The NetrDfsRemoveFtRoot method uses the following MIDL syntax.

 NET_API_STATUS NetrDfsRemoveFtRoot(
   [in, string] WCHAR* ServerName,
   [in, string] WCHAR* DcName,
   [in, string] WCHAR* RootShare,
   [in, string] WCHAR* FtDfsName,
   [in] DWORD ApiFlags,
   [in, out, unique] DFSM_ROOT_LIST** ppRootList
 );

ServerName: The pointer to a null-terminated Unicode string. This is the host name DFS root target to be removed.

DcName: The pointer to a null-terminated Unicode string. For a domainv1-based DFS namespace, this string contains the host name of the DC to be used by the DFS root targets being removed for getting or updating DFS metadata for the DFS namespace. This parameter MAY be a NULL pointer; otherwise, it MUST be the PDC for the domain of the DFS namespace.

RootShare: The pointer to a null-terminated Unicode DFS root target share name string. The share is not removed automatically when the method is successful; it MUST be removed explicitly as needed.

FtDfsName: The pointer to a null-terminated Unicode string that contains the DFS namespace in which the operation is to be performed. It MAY be different from the RootShare.

ApiFlags: The only supported bit in the ApiFlags parameter is DFS_FORCE_REMOVE.

Value	Meaning
DFS_FORCE_REMOVE 0x80000000	Removes the named DFS root target from the namespace's directory service metadata only.

All other bits are reserved and MUST NOT be used. If reserved bits are specified, the server SHOULD<113> fail the call.

ppRootList: On success, returns a list of DFS root targets in the domain-based DFS namespace which the client will be responsible for notifying about the change in the DFS namespace. See section 3.2.4.3.2. The list MAY be empty if the server has performed the notification.<114>

Return Values: The method MUST return 0 on success and a nonzero error code on failure. The method can return any specific error code value, as specified in [MS-ERREF] section 2.2.The most common error codes are listed in the following table.

Return value/code	Description
0x00000000 ERROR_SUCCESS	Successful completion.
0x00000002 ERROR_FILE_NOT_FOUND	The specified DFS root target was not found as a target of the specified DFS namespace.
0x00000005 ERROR_ACCESS_DENIED	Permission to perform the operation was denied.
0x00000057 ERROR_INVALID_PARAMETER	An incorrect parameter was specified.
0x00000490 ERROR_NOT_FOUND	The specified DFS rootnamespace does not exist.

The server MUST verify the existence of the DFS namespace that the FtDfsName parameter specifies. If that existence check fails, the server MUST return ERROR_NOT_FOUND.

The server MUST verify the existence of the DFS root target of the DFS namespace that the ServerName and RootShare parameters specify. If that existence check fails, the server MUST return ERROR_FILE_NOT_FOUND.

The server MUST support deleting a DFS namespace without first requiring removal of all the DFS links in it.

If the DcName parameter is not NULL, then it MUST be the PDC for the domain of the DFS namespace.

The server MAY support DFS_FORCE_REMOVE on member servers.<115> If it is not supported and DFS_FORCE_REMOVE is specified, the server MUST return a failure.

If DFS_FORCE_REMOVE is not specified, the server MUST verify it is the host specified by the ServerName and RootShare parameters. If it is not, the server MUST return ERROR_NOT_FOUND.

If DFS_FORCE_REMOVE is not specified, the server SHOULD<116> also remove any local information related to hosting the removed root target. If DFS_FORCE_REMOVE is specified, the server MUST NOT do so.

The effect of DFS_FORCE_REMOVE is to clean up after the named root target has become nonfunctional and is unable to remove itself from the namespace.

The server MUST remove the root target of the domain-based DFS namespace specified by the ServerName and RootShare parameters by updating the remoteServerName attribute of the namespace's object (as specified in section 2.3.3) in the root target. If the last DFS root target is being removed, then the server SHOULD NOT remove the object of the namespace; the client invoking the method MUST do this.<117>

The server SHOULD remove any intermediate directories and reparse points that were part of the namespace.

The server MUST update the following fields in the domainv1-based DFS metadata.

The server MUST synchronously update the DFS metadata of the namespace.

If DFS root scalability mode is not enabled, then the server MUST do one of the following:

• Notify other DFS root targets of the change in DFS metadata by asynchronously issuing a NetrDfsSetInfo (Opnum 3) method with the Level parameter 101 and with the State field of DFS_INFO_101 set to DFS_VOLUME_STATE_RESYNCHRONIZE. The returned ppRootList parameter MUST be empty.

• Perform no notification of the other root targets, returning a list of DFS root targets to the client in the ppRootList parameter.