Share via

3.1.4.1.9 NetrDfsAddRootTarget (Opnum 23)

  • Article

The NetrDfsAddRootTarget method is used to create a stand-alone DFS namespace, a domainv1-based DFS namespace, or a domainv2-based DFS namespace.<73>

The NetrDfsAddRootTarget method uses the following MIDL syntax.

 NET_API_STATUS NetrDfsAddRootTarget(
   [in, unique, string] LPWSTR pDfsPath,
   [in, unique, string] LPWSTR pTargetPath,
   [in] ULONG MajorVersion,
   [in, unique, string] LPWSTR pComment,
   [in] BOOLEAN NewNamespace,
   [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. The latter restriction is required to ensure that a typographic error in the domain name, while attempting to create a domain-based DFS, does not result in a stand-alone DFS namespace being created on the DFS root target server, if the first pathname component of the pDfsPath parameter is used to detect whether a domain-based DFS namespace or stand-alone DFS namespace is being created. When pTargetPath is not NULL, the <server> MUST be used as the host name of the new DFS root target in the metadata.

MajorVersion: The DFS metadata version to use to create the DFS namespace. When adding a DFS root target to an existing DFS namespace, MajorVersion MUST be either 0 or the major version number of the existing DFS namespace. Otherwise, the call MUST fail.

pComment: 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.

NewNamespace: A Boolean value that, if TRUE, indicates a request to create a new root. If FALSE, this value indicates a request to add a new root target to an existing root.

Flags: This parameter MUST be zero for a domain-based DFS namespace and MUST be ignored for a stand-alone DFS namespace.

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.

0x000000B7

ERROR_ALREADY_EXISTS

The specified namespace already exists on this server.

0x00000906

NERR_NetNameNotFound

The share that the TargetPath parameter specifies does not already exist.

The following table summarizes the various actions that the NetrDfsAddRootTarget method takes based on the parameter values.

pDfsPath parameter

pTargetPath parameter

MajorVersion parameter

Explanation

\\<domain>\<dfsname>

\\<server>\<share>

1

Creates a new domainv1-based DFS namespace or adds a new root target to an existing domainv1-based DFS namespace. If a DFS namespace already exists, the version specified MUST match the DFS namespace; otherwise, the call fails.

\\<domain>\<dfsname>

\\<server>\<share>

2

Creates a new domainv2-based DFS namespace or adds a new root target to an existing domainv2-based DFS namespace. If a DFS namespace already exists, the version specified MUST match the DFS namespace; otherwise, the call fails.

\\<domain>\<dfsname>

\\<server>\<share>

0

Adds a new root target to an existing domain-based DFS namespace or a domainv2-based DFS namespace. If a DFS namespace does not already exist, the call fails.

\\<server>\<share>

NULL

1

Creates a new stand-alone DFS namespace.

The following scheme is used to create a new domainv2-based DFS namespace:

  • NetrDfsGetSupportedNamespaceVersion is called to determine an appropriate version number to pass to the NetrDfsAddRootTarget() method.

  • The client-side method creates a DFS metadata, format-independent LDAP entry called the DFS namespace anchor. It contains only the DFS metadata major version number.

  • Updates the access control list (ACL) on the object of the DFS namespace to permit read/write access by the DFS root target server.

  • The client-side method then issues an RPC call to the DFS root target server.

  • The DFS server creates a new DFS namespace LDAP entry with the DFS namespace anchor LDAP entry as its parent.

  • All DFS links are created with the DFS namespace LDAP entry as the parent. For more information, see section 2.3.2.

This results in two LDAP entries in domainv2 corresponding to the single LDAP entry in domainv1.

If the domain-based DFS namespace already exists, and the ServerName and RootShare parameters are a root target, the server MUST fail with ERROR_ALREADY_EXISTS.

If the share that the pTargetPath parameter specifies does not already exist, the RPC method MUST fail with NERR_NetNameNotFound (0x00000906).

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

Operation

DFS metadata changes required.

Adding a new namespace

Creates a new Namespace object for the namespace, and inserts the object into NamespaceList.

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

Operation

DFS metadata changes required

Adding a new namespace

Creates new DFS metadata.

Adding a new root target

Updates the TargetCount field of the DFSTargetListBLOB, creates a new TargetEntryBLOB, updates the DFSTargetListBLOBSize, updates the BLOBDataSize of the DFSNamespaceRootBLOB, and adds the DFSRootTarget to the remoteServerName attribute in the object.

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

Operation

DFS metadata changes required

Adding a new namespace

Creates new DFS namespace LDAP entry with the DFS namespace anchor LDAP as its parent.

Adding a new root target

Updates the msDFS-TargetListv2 attribute, which is stored as an XML document, by adding *server* into the list of root targets.

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.