Share via

3.1.4.1.10 NetrDfsRemoveRootTarget (Opnum 24)

  • Article

The NetrDfsRemoveRootTarget (Opnum 24) method is the unified DFS namespace deletion method. It deletes stand-alone DFS namespaces, domainv1-based DFS namespaces, or domainv2-based DFS namespaces based on parameters specified.<74>

The NetrDfsRemoveRootTarget (Opnum 24) method has the following MIDL syntax.

 NET_API_STATUS NetrDfsRemoveRootTarget(
   [in, unique, string] LPWSTR pDfsPath,
   [in, unique, string] LPWSTR pTargetPath,
   [in] ULONG Flags
 );

pDfsPath: The pointer to a null-terminated Unicode string. This MUST be \\<domain>\<dfsname> for domain-based DFS or \\<server>\<share> for stand-alone DFS.

pTargetPath: The pointer to a null-terminated Unicode string. This MUST be \\<server>\<share>[\<path>] for domain-based DFS or NULL for stand-alone DFS.

Flags: A bit field specifying the type of removal operation. For a standalone namespace, this bit-field parameter MUST be zero. For a domain-based DFS namespace, it can be zero or the following value. Zero indicates a normal removal operation.

Value

Meaning

DFS_FORCE_REMOVE

0x80000000

Specifying this flag for a domain-based DFS namespace removes the root target even if it is not accessible.

All other bits are reserved and MUST NOT be used. If reserved bits are specified, the server SHOULD fail the call with an implementation-dependent failure value.<75>

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 root namespace does not exist.

The server MUST verify the existence of the DFS namespace that the pDfsPath 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 pTargetPath parameter specifies. 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.

The client-side method is responsible for deleting the DFS namespace anchor LDAP entry corresponding to a domainv2-based DFS namespace.

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

If DFS_FORCE_REMOVE is not specified and it is a domain-based DFS namespace, the server MUST verify it is the host specified by the pTargetPath parameter. If it is not, the server MUST return ERROR_FILE_NOT_FOUND.

If DFS_FORCE_REMOVE is not specified, the server SHOULD<77> 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 synchronously update the DFS metadata of a domain-based DFS namespace.

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

If DFS root scalability mode is not enabled for the domain-based DFS namespace, the server MUST 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 following table summarizes the various actions that the NetrDfsRemoveRootTarget method takes based on the parameter values.

pDfsPath parameter

pTargetPath parameter

Explanation

\\<domain>\<dfsname>

\\<server>\<share>

Deletes a domain-based DFS root target. If the DFS root target that is removed is the last one for the DFS namespace, then it removes the DFS namespace itself. This parameter can be used for either a domainv1-based DFS namespace or a domainv2-based DFS namespace.

\\<server>\<dfsname>

NULL

Deletes a stand-alone DFS namespace.