3.1.4.2.1 NetrDfsAdd2 (Opnum 19)

  • Article

The NetrDfsAdd2 (Opnum 19) method creates a new DFS link or adds a new target to an existing link of a DFS namespace.

The NetrDfsAdd2 method has the following MIDL syntax.

 NET_API_STATUS NetrDfsAdd2(
   [in, string] WCHAR* DfsEntryPath,
   [in, string] WCHAR* DcName,
   [in, string] WCHAR* ServerName,
   [in, unique, string] WCHAR* ShareName,
   [in, unique, string] WCHAR* Comment,
   [in] DWORD Flags,
   [in, out, unique] DFSM_ROOT_LIST** ppRootList
 );

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

DcName: A pointer to a null-terminated Unicode string. For a domain-based DFS namespace, this is the host name of the DC that the DFS root target uses to get or update DFS metadata for the DFS namespace. This parameter MAY be a NULL pointer; otherwise, it MUST be the host name of the PDC for the domain of the DFS namespace.<79>

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

ShareName: A 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 in this manner, each pathname component MUST be a directory.

Comment: A pointer to a null-terminated, human-readable Unicode string description associated with this root or link. This string is not subject to protocol-specified restrictions on length or content and does not affect server functionality. The description MUST be ignored when adding a target to an existing link.

Flags: The flag that indicates the operation to perform. The following table lists the possible values.

Value

Meaning

0x00000000

Create a new link or add 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 fail if it exists.

DFS_RESTORE_VOLUME

0x00000002

Add a target without verifying its existence.

If the Flags value is not a bitwise OR of the values above, the server MUST return ERROR_INVALID_PARAMETER (0x00000057).

ppRootList: On success, returns a list of DFS root targets in the domain-based DFS namespace that the client will be responsible for notifying of the change in the DFS namespace. See section 3.2.4.2.1. This list MAY be empty if the server performs the notification.<80>

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

The operation completed successfully.

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

0x00000906

NERR_NetNameNotFound

The DFS link target does not exist.

A server MAY<81> implement this method.

If the NetrDfsAdd (Opnum 1) method on a server does not support a domain-based namespace, the server SHOULD support a domain-based namespace in the NetrDfsAdd2 (Opnum 19) method. <82><83>

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<84> 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,<85> for example, be implemented with the expectation that all link targets are administered through [MS-SRVS] section 3.1.4.10 and use NetShareGetInfo level 1005 to perform the test. Reasons not to implement this test include:

  • 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 adding a target to an existing link.

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

The server MUST update the same fields in the DFS metadata for a domain-based DFS namespace as in the NetrDfsAdd method, as specified in section 3.1.4.1.3.

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 do one of the following:

  • 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. 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.