3.1.4.1.8 NetrDfsMove (Opnum 6)

  • Article

The NetrDfsMove (Opnum 6) method renames or moves a DFS link. This method has the following MIDL syntax.

 NET_API_STATUS NetrDfsMove(
   [in, string] WCHAR* DfsEntryPath,
   [in, string] WCHAR* NewDfsEntryPath,
   [in] unsigned long Flags
 );

DfsEntryPath: The pointer to a DFS path, this parameter specifies the source path for the move operation. This MUST be a DFS link or the path prefix of any DFS link in the DFS namespace.

NewDfsEntryPath: The pointer to a DFS path, this parameter specifies the destination DFS path for the move operation. This MUST be a path or a DFS link in the same DFS namespace.

Flags: A bit field specifying additional actions to take.

Value

Meaning

DFS_MOVE_FLAG_REPLACE_IF_EXISTS

0x00000001

If the destination path is an existing link, replace it as part of the move operation.

All other bits are reserved and MUST NOT be used. If reserved bits are specified, the server SHOULD fail the call with ERROR_INVALID_PARAMETER (0x00000057) .

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.

0x00000005

ERROR_ACCESS_DENIED

Permission to perform the operation was denied.

0x00000032

ERROR_NOT_SUPPORTED

The specified operation is not supported.

0x00000050

ERROR_FILE_EXISTS

The destination path specifies an existing link.

0x00000057

ERROR_INVALID_PARAMETER

An incorrect parameter was specified.

0x00000490

ERROR_NOT_FOUND

A specified DFS root namespace does not exist, or no links were matched.

The server MUST verify the existence of the DFS namespaces that the DfsEntryPath and NewDfsEntryPath parameters specify. If the existence check fails, the server MUST return ERROR_NOT_FOUND.

The server MUST validate that the source and destination paths are

  1. In the same DFS namespace.

  2. Below the root of the namespace.

Otherwise, the server MUST return ERROR_NOT_SUPPORTED.

The server MUST return ERROR_NOT_FOUND if the DfsEntryPath parameter does not match any DFS links in the namespace, as specified below.

The server MUST validate that the source and destination paths do not specify illegal characters or path elements. If either path is illegal, the server MUST return ERROR_INVALID_NAME.<68>

The server SHOULD perform DFS link move operations atomically. That is, either all of the constituent operations are performed as part of the move and the call succeeds, or no changes are made to the DFS namespace and the call fails.<69>

When the source and destination are both paths in the DFS namespace and not links themselves, all DFS links in the DFS namespace that have the source path as their prefix MUST be converted to DFS links with the destination path as the prefix. In effect, each DFS link that has the prefix specified by the source path is removed, and new DFS links that have exactly the same targets and target properties are added, but with the prefix specified by the destination path. For example, with a source path of "\\MyServer\MyDfs\dir1" and a destination path of "\\MyServer\MyDfs\dir2", the DFS link "\\MyServer\MyDfs\dir1\link1" becomes "\\MyServer\MyDfs\dir2\link1", while the DFS link "\\MyServer\MyDfs\link2" is unaffected by the move operation.

If a DFS link already exists at the destination path, unless the Flags parameter is DFS_MOVE_FLAG_REPLACE_IF_EXISTS, the server MUST fail the call with ERROR_FILE_EXISTS. This MUST be enforced only if the destination is an existing link, not if the destination is an existing file or directory. In the preceding example, if a DFS link "\\MyServer\MyDfs\dir2\link1" already exists, the move operation will fail unless the DFS_MOVE_FLAG_REPLACE_IF_EXISTS flags parameter is specified. If the DFS_MOVE_FLAG_REPLACE_IF_EXISTS flags parameter is specified, the DFS link at the destination path is removed and replaced by the moved DFS link. If "\\MySever\MyDfs\dir2\link1" is an existing directory and not a link, the operation does not require the DFS_MOVE_FLAG_REPLACE_IF_EXISTS flags parameter to be specified.

DFS servers SHOULD support the case in which intermediate or leaf pathname components in the destination path are files; for example, the case of a source path being "\\MyServer\MyDfs\dir1\link1", a destination path being "\\MyServer\MyDfs\comp1\link1", and "\\MyServer\MyDfs\comp1" being a file.<70>

If intermediate directories in the pathname of a source DFS link are empty, they SHOULD be removed, as required, after a move operation. For example, if "\\MyServer\MyDfs\dir1\dir2\link1" is moved to "\\MyServer\MyDfs\link1", the dir1 and dir2 directories are removed if they are empty.<71>

If the move operation results in a source DFS link becoming the prefix of an existing destination DFS link, the move operation MUST be failed. For example, if the source is a DFS link "\\MyServer\MyDfs\dir1\link1", the destination DFS link specified is "\\MyServer\MyDfs\dir2", and if a DFS link "\\MyServer\MyDfs\dir2\link2" already exists, the server MUST fail the call with ERROR_FILE_EXISTS.

For a domainv1-based DFS namespace and stand-alone DFS namespaces, the link's identity is changed. Thus, to another DFS root target of the same domainv1-based DFS namespace, one link is deleted and then another link is created instead of an existing link being moved.

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 NamespaceElement from NamespaceElementsList.

Add link

Add NamespaceElement in NamespaceElementsList.

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 and update BLOBElementCount.

Add link

Add DFSNamespaceLinkBLOB and update BLOBElementCount.

In contrast, for a domainv2-based DFS namespace, the link's identity is not changed. Instead, the msDFS-LinkPathv2, msDFS-LastModifiedv2, and msDFS-GenerationGUIDv2 attributes of a DFS link's LDAP entry are updated during a move operation. When a destination link is deleted, the required local state changes (on-disk, in-memory) are performed on the DFS root target server performing the move operation as well.

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

Operation

DFS metadata changes required

Remove link

Update msDFS-LinkPathv2, msDFS-LastModifiedv2, and msDFS-GenerationGUIDv2.

Add link

Update msDFS-LinkPathv2, msDFS-LastModifiedv2, and msDFS-GenerationGUIDv2.

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 (Opnum 3) method with the Level parameter 101 and with the State field of DFS_INFO_101 set to DFS_VOLUME_STATE_RESYNCHRONIZE.<72>

The move operation on a stand-alone DFS namespace or a domainv2-based DFS namespace also correctly applies to any security descriptor that is associated with the DFS link, to the new reparse point created after the move operation.