3.1.4.1.3 NetrDfsAdd (Opnum 1)

Article
06/24/2021

The NetrDfsAdd method creates a new DFS link or adds a new target to an existing link of a DFS namespace.

The NetrDfsAdd (Opnum 1) method has the following MIDL syntax.

 NET_API_STATUS NetrDfsAdd(
   [in, string] WCHAR* DfsEntryPath,
   [in, string] WCHAR* ServerName,
   [in, unique, string] WCHAR* ShareName,
   [in, unique, string] WCHAR* Comment,
   [in] DWORD Flags
 );

DfsEntryPath: The pointer to a DFS link path that contains the name of an existing link when additional link targets are being added or the name of a new link is being created.

ServerName: The pointer to a null-terminated Unicode string that specifies the DFS link target host name.

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". When specified this way, each pathname component MUST be a directory.

Comment: The pointer to a null-terminated Unicode string that contains a comment associated with this root or link. This string has no protocol-specified restrictions on length or content. The comment is meant for human consumption and does not affect server functionality. The comment MUST be ignored when adding a target to an existing link.

Flags: A value indicating the operation to perform. The following table lists such flags.

Value	Meaning
0x00000000	Create a new link or adds a new target to an existing link.
DFS_ADD_VOLUME 0x00000001	Create a new link in the DFS namespace if one does not already exist or fails if a link already exists.
DFS_RESTORE_VOLUME 0x00000002	Add a target without verifying its existence.

Value

Meaning

0x00000000

Create a new link or adds a new target to an existing link.

DFS_ADD_VOLUME

0x00000001

Create a new link in the DFS namespace if one does not already exist or fails if a link already exists.

DFS_RESTORE_VOLUME

0x00000002

Add a target without verifying its existence.

If a Flags value other than the bitwise-OR of the above values is provided, the server MUST return 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.
0x00000050 ERROR_FILE_EXISTS	The specified DFS link target already exists.
0x00000057 ERROR_INVALID_PARAMETER	An incorrect parameter was specified.
0x00000490 ERROR_NOT_FOUND	The specified DFS root namespace does not exist.
0x00000032 ERROR_NOT_SUPPORTED	The method does not support a domain-based namespace.
0x00000906 NERR_NetNameNotFound	The DFS link target does not exist.

The NetrDfsAdd method SHOULD <42> 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 whether the link to be added overlaps an existing link. If there is a link for which the specified DfsEntryPath parameter is a prefix, the server MUST return ERROR_FILE_EXISTS.

If the link to be added already exists, and DFS_ADD_VOLUME is set in the Flags field of the request, the server MUST return ERROR_FILE_EXISTS.

If the link to be added already exists, and DFS_ADD_VOLUME is not set in the Flags field of the request, the server MUST attempt to add a new link target to the link. If a target with the path specified by ServerName and ShareName was already added to the link, the server MUST return ERROR_FILE_EXISTS.

If DFS_RESTORE_VOLUME is not specified on the Flags parameter, the server MAY <43> choose to verify whether the link target exists. If DFS_RESTORE_VOLUME is specified, the server MUST NOT perform this test. If it performs the test and the link target does not exist, the server MUST fail the call with NERR_NetNameNotFound.

The exact test the server performs to verify link target existence is implementation-defined. A server MAY,<44> for example, assume all link targets are administered through [MS-SRVS] section 3.1.4.10 and use NetShareGetInfo level 1005 to perform the test. Three reasons not to implement this test are that

It might not be practical to determine the correct administration interface to query to perform the test.
A link target server can export a share with a network protocol and administration interface that this server does not understand.
A secured link target server might not permit this server to contact it.

The Comment parameter MUST be ignored when a target is added to an existing link.

The server SHOULD <45> create a new link without requiring the DFS_ADD_VOLUME Flags parameter.

The server MUST determine whether the specified link target refers to a domain-based namespace. If it does, this request is creating a DFS interlink. If it is creating an interlink and the link already exists, the server MUST return an implementation-defined failure value. For domain-based namespaces, the server MUST set the DFS interlink property as appropriate for the link for each type of domain-based namespace. See sections 2.3.3.1.1.2 and 2.3.4.3.

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

Operation	DFS metadata changes required
Adding a new link	New NamespaceElement in NamespaceElementsList.
Adding a new target to an existing link	New Target in the TargetsList of the NamespaceElement and an update to the TargetCount.

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

Operation	DFS metadata changes required
Adding a new link	New DFSNamespaceLinkBLOB and BLOBElementCount.
Adding a new target to an existing link	New TargetEntryBLOB and updated TargetCount in existing DFSTargetListBLOB, updated DFSTargetListBLOBSize and 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
Adding a new link	The following mandatory attributes MUST be updated: msDFS-NamespaceIdentityGUIDv2, msDFS-LinkIdentityGUIDv2, msDFS-GenerationGUIDv2, msDFS-LinkPathv2, msDFS-LastModifiedv2, msDFS-TargetListv2, msDFS-Propertiesv2, and msDFS-Ttlv2. The following optional attribute MAY be updated: msDFS-Commentv2.<46>
Adding a new target to an existing link	Update targetCount, totalStringLengthInBytes, priority, and state attributes in msDFS-TargetListv2. Update msDFS-LastModifiedv2.

Operation

DFS metadata changes required

Adding a new link

The following mandatory attributes MUST be updated: msDFS-NamespaceIdentityGUIDv2, msDFS-LinkIdentityGUIDv2, msDFS-GenerationGUIDv2, msDFS-LinkPathv2, msDFS-LastModifiedv2, msDFS-TargetListv2, msDFS-Propertiesv2, and msDFS-Ttlv2.

The following optional attribute MAY be updated: msDFS-Commentv2.<46>

Adding a new target to an existing link

Update targetCount, totalStringLengthInBytes, priority, and state attributes in msDFS-TargetListv2. Update msDFS-LastModifiedv2.

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.<47><48>

Share via

3.1.4.1.3 NetrDfsAdd (Opnum 1)

Additional resources