3.1.4.1.4 NetrDfsRemove (Opnum 2)

The NetrDfsRemove method removes a link or a link target from a DFS namespace. A link can be removed regardless of the number of targets associated with it.

The NetrDfsRemove method has the following MIDL syntax.

 NET_API_STATUS NetrDfsRemove(
   [in, string] WCHAR* DfsEntryPath,
   [in, unique, string] WCHAR* ServerName,
   [in, unique, string] WCHAR* ShareName
 );

DfsEntryPath: The pointer to the DFS link path that contains the name of an existing link.

ServerName: The pointer to a null-terminated Unicode DFS link target host name string. Clients MUST set ServerName to a NULL pointer in requests to remove the link and all its link targets.

ShareName: The pointer to a null-terminated Unicode DFS link target share name string. This can also be a share name with a path relative to the share, for example, "share1\mydir1\mydir2". Clients MUST set ShareName to a NULL pointer in requests to remove the link and all its link targets.

Return Values: This 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 link target was not found as a target of the specified DFS link.
0x00000005 ERROR_ACCESS_DENIED	Permission to perform the operation was denied.
0x00000057 ERROR_INVALID_PARAMETER	An incorrect parameter was specified.
0x00000032 ERROR_NOT_SUPPORTED	The method does not support a domain-based namespace.
0x00000490 ERROR_NOT_FOUND	The specified DFS namespace or DFS link does not exist.

The NetrDfsRemove method SHOULD<49> support a domain-based DFS namespace. If it does not support a domain-based DFS namespace it MUST return ERROR_NOT_SUPPORTED.

The server MUST verify the existence of the DFS namespace that the DfsEntryPath parameter specifies. If the namespace does not exist, the server MUST return ERROR_NOT_FOUND.

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

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

If the ServerName and ShareName parameters are both NULL, the server MUST remove the link and all its link targets. If the ServerName and ShareName are not NULL, the server MUST remove the specified link target. If the specific target is the last target of the link, the server MUST remove the link as well. If only one of ServerName or ShareName is NULL, the server MUST return ERROR_INVALID_PARAMETER.

The server MUST synchronously update the following fields in the DFS metadata for a stand-alone DFS namespace.

Operation	DFS metadata changes required
Remove link	Remove corresponding NamespaceElement from NamespaceElementsList.
Remove link target	Remove Target from the TargetsList of the NamespaceElement, and update the TargetCount.

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

Operation	DFS metadata changes required
Remove link	Remove DFSNamespaceLinkBLOB; update BLOBElementCount.
Remove link target	Update TargetCount in existing DFSTargetListBLOB, remove TargetEntryBLOB. Update DFSTargetListBLOBSize, update BLOBDataSize of DFSNamespaceLinkBLOB.

The server MUST update the following fields in the DFS metadata for a domainv2-based DFS namespace.

Operation	DFS metadata Changes Required
Remove link	Remove the DFS link object.
Remove link target	Update TargetCount and totalStringLengthInBytes attributes in msDFS-TargetListv2; update msDFS-LastModifiedv2.

A remove link operation in a domainv2-based DFS namespace first creates a dynamic object for the entry to be deleted. To create a dynamic object, the server MUST do the following:

• Set the object class to msDFS-DeletedLinkv2; a normal DFS link LDAP entry's object class is msDFS-Linkv2.

• Set the deleted DFS link's identity GUID.

• Set an updated msDFS-LastModifiedv2 time-stamp attribute.

If the dynamic object is created successfully, the original link LDAP entry is then deleted. If the delete is successful, the dynamic object is left intact; otherwise, the dynamic object is itself deleted. The advantage of using a dynamic object is that directory services perform garbage collection.

The server MUST synchronously update the DFS metadata of a domain-based DFS 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 method with the Level parameter 101, and with the State field of DFS_INFO_101 set to DFS_VOLUME_STATE_RESYNCHRONIZE.<50><51>