3.1.4.3.1 NetrDfsAddFtRoot (Opnum 10)

The NetrDfsAddFtRoot (Opnum 10) method creates a new domainv1-based DFS namespace or adds a root target to an existing namespace.

The NetrDfsAddFtRoot method uses the following MIDL syntax.

 NET_API_STATUS NetrDfsAddFtRoot(
   [in, string] WCHAR* ServerName,
   [in, string] WCHAR* DcName,
   [in, string] WCHAR* RootShare,
   [in, string] WCHAR* FtDfsName,
   [in, string] WCHAR* Comment,
   [in, string] WCHAR* ConfigDN,
   [in] BOOLEAN NewFtDfs,
   [in] DWORD ApiFlags,
   [in, out, unique] DFSM_ROOT_LIST** ppRootList
 );

ServerName: The pointer to a null-terminated Unicode string. This MUST be used as the host name of the new DFS root target in the metadata.<108>

DcName: The pointer to a null-terminated Unicode string. For a domainv1-based DFS namespace, this string contains the host name of the DC that the new DFS root target is to use to get or update DFS metadata for the DFS namespace. This parameter MAY be a NULL pointer, otherwise, it MUST be the PDC for the domain of the DFS namespace.

RootShare: The pointer to a null-terminated Unicode string. This is the new DFS root target share name. This can be different from the FtDfsName parameter. The share MUST already exist.

FtDfsName: The pointer to a null-terminated Unicode string. This is the name of the new or existing domain-based DFS namespace.

Comment: The pointer to a null-terminated Unicode string that contains a comment associated with the DFS namespace. Used for informational purposes, this string has no protocol-specified restrictions on length or content. The comment is meant for human consumption and does not affect server functionality. This parameter MAY be NULL.

ConfigDN: The pointer to a null-terminated Unicode string. This string MUST be the path of the DFS namespace object entry in the DFS Configuration Container (see section 2.3.3).<109>

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

ApiFlags: This parameter MUST be 0.

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.3.1. The list MAY be empty if the server has performed the notification.<110>

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.
0x00000057 ERROR_INVALID_PARAMETER	An incorrect parameter was specified.
0x000000B7 ERROR_ALREADY_EXISTS	A namespace of the specified name already exists on the server.
0x00000906 NERR_NetNameNotFound	The share that the RootShare parameter specifies does not already exist.

The share that the RootShare parameter specifies MUST already exist on the server.

If the DcName parameter is not NULL, the server assumes that this is the PDC for the domain in which the DFS namespace is to be created.

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 RootShare parameter specifies does not already exist, the RPC method MUST fail with NERR_NetNameNotFound (0x00000906).

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

The server MUST synchronously update the DFS metadata.

The server MUST return a list of DFS root targets to the client in the ppRootList parameter.<111>