<div class="content" name="NetrDfsAdd2" uuid="eff0144e-26d7-485c-aeed-caa737bcd7d2"><p>The NetrDfsAdd2 (Opnum 19) method creates a new <a href="a9bc4403-a862-48b9-b99b-1b44a887d177#gt_0611e93d-f0e7-42ee-a591-d77ebcbb6619" data-linktype="relative-path">DFS link</a> or adds a new
target to an existing link of a <a href="a9bc4403-a862-48b9-b99b-1b44a887d177#gt_6a3f0be9-b9b4-49df-9d1c-a3b89e4e9890" data-linktype="relative-path">DFS namespace</a>.</p><p>The NetrDfsAdd2 method has the following <a href="a9bc4403-a862-48b9-b99b-1b44a887d177#gt_9c5903c1-1477-4181-b451-3ba1e34a0c0c" data-linktype="relative-path">MIDL</a> syntax.</p><dl>
<dd>
<div><pre> 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
 );
</pre></div>
</dd></dl><p><b>DfsEntryPath: </b>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.</p><p><b>DcName: </b>A pointer to a null-terminated <a href="a9bc4403-a862-48b9-b99b-1b44a887d177#gt_c305d0ab-8b94-461a-bd76-13b40cb8c4d8" data-linktype="relative-path">Unicode</a> string. For a <a href="a9bc4403-a862-48b9-b99b-1b44a887d177#gt_133ab305-ad75-4b38-8ec9-40bc0dc3b594" data-linktype="relative-path">domain-based DFS namespace</a>,
this is the <a href="a9bc4403-a862-48b9-b99b-1b44a887d177#gt_fe6fd875-b30a-44bb-850e-10733990f04c" data-linktype="relative-path">host name</a> of
the <a href="a9bc4403-a862-48b9-b99b-1b44a887d177#gt_76a05049-3531-4abd-aec8-30e19954b4bd" data-linktype="relative-path">DC</a> that the <a href="a9bc4403-a862-48b9-b99b-1b44a887d177#gt_ac90b498-3ba4-48d6-bcd6-5495f1654671" data-linktype="relative-path">DFS root target</a> uses to get
or update <a href="a9bc4403-a862-48b9-b99b-1b44a887d177#gt_e8de88fd-d760-46fa-ad77-76961fa20aea" data-linktype="relative-path">DFS metadata</a>
for the DFS namespace. This parameter MAY be a NULL pointer; otherwise, it MUST
be the host name of the <a href="a9bc4403-a862-48b9-b99b-1b44a887d177#gt_663cb13a-8b75-477f-b6e1-bea8f2fba64d" data-linktype="relative-path">PDC</a>
for the <a href="a9bc4403-a862-48b9-b99b-1b44a887d177#gt_b0276eb2-4e65-4cf1-a718-e0920a614aca" data-linktype="relative-path">domain</a> of the
DFS namespace.<a id="Appendix_A_Target_79"></a><a aria-label="Product behavior note 79" href="3a466440-1ef6-4439-b4e2-be9eaddeb511#Appendix_A_79" data-linktype="relative-path">&lt;79&gt;</a></p><p><b>ServerName: </b>A pointer to a null-terminated
Unicode string that specifies the <a href="a9bc4403-a862-48b9-b99b-1b44a887d177#gt_44e2f830-c28b-41e3-8c3c-d0bb576ed9fb" data-linktype="relative-path">DFS link target</a> host name.</p><p><b>ShareName: </b>A pointer to a null-terminated
Unicode DFS link target <a href="a9bc4403-a862-48b9-b99b-1b44a887d177#gt_3c179f10-1793-4268-96eb-de4d85a32060" data-linktype="relative-path">share
name</a> string. This can also be a share name with a path relative to the <a href="a9bc4403-a862-48b9-b99b-1b44a887d177#gt_a49a79ea-dac7-4016-9a84-cf87161db7e3" data-linktype="relative-path">share</a> (for example, <code>share1\mydir1\mydir2</code>). When specified in this manner,
each pathname component MUST be a directory.</p><p><b>Comment: </b>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.</p><p><b>Flags: </b>The flag that indicates the operation
to perform. The following table lists the possible values.</p><dl>
<dd>
<table><thead>
  <tr>
   <th>
   <p>Value</p>
   </th>
   <th>
   <p>Meaning</p>
   </th>
  </tr>
 </thead><tbody><tr>
  <td>0x00000000</td>
  <td>Create a new link or add a new target to an existing link.</td>
 </tr><tr>
  <td>DFS_ADD_VOLUME 0x00000001</td>
  <td>Create a new link in the DFS namespace if one does not already exist or fail if it exists.</td>
 </tr><tr>
  <td>DFS_RESTORE_VOLUME 0x00000002</td>
  <td>Add a target without verifying its existence.</td>
 </tr></tbody></table>
</dd>
<dd>
<p>If the <i>Flags</i> value is not a bitwise OR of the
values above, the server MUST return ERROR_INVALID_PARAMETER (0x00000057).</p>
</dd></dl><p><b>ppRootList: </b>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 <a href="c218c3ae-4470-4b1d-a063-799a417e65b7" data-linktype="relative-path">3.2.4.2.1</a>. This list MAY
be empty if the server performs the notification.<a id="Appendix_A_Target_80"></a><a aria-label="Product behavior note 80" href="3a466440-1ef6-4439-b4e2-be9eaddeb511#Appendix_A_80" data-linktype="relative-path">&lt;80&gt;</a></p><p><b>Return Values: </b>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 <a href="../ms-erref/1bc92ddf-b79e-413c-bbaa-99a5281a6c90" data-linktype="relative-path">[MS-ERREF]</a>
section <a href="../ms-erref/18d8fbe8-a967-4f1c-ae50-99ca8e491d2d" data-linktype="relative-path">2.2</a>.
The most common error codes are listed in the following table.</p><dl>
<dd>
<table><thead>
  <tr>
   <th>
   <p>Return value/code</p>
   </th>
   <th>
   <p>Description</p>
   </th>
  </tr>
 </thead><tbody><tr>
  <td>0x00000000 ERROR_SUCCESS</td>
  <td>The operation completed successfully.</td>
 </tr><tr>
  <td>0x00000005 ERROR_ACCESS_DENIED</td>
  <td>Permission to perform the operation was denied.</td>
 </tr><tr>
  <td>0x00000050 ERROR_FILE_EXISTS</td>
  <td>The specified DFS link target already exists.</td>
 </tr><tr>
  <td>0x00000057 ERROR_INVALID_PARAMETER</td>
  <td>An incorrect parameter was specified.</td>
 </tr><tr>
  <td>0x00000490 ERROR_NOT_FOUND</td>
  <td>The specified DFS namespace does not exist.</td>
 </tr><tr>
  <td>0x00000906 NERR_NetNameNotFound</td>
  <td>The DFS link target does not exist.</td>
 </tr></tbody></table>
</dd></dl><p>A server MAY<a id="Appendix_A_Target_81"></a><a aria-label="Product behavior note 81" href="3a466440-1ef6-4439-b4e2-be9eaddeb511#Appendix_A_81" data-linktype="relative-path">&lt;81&gt;</a> implement
this method.</p><p>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. <a id="Appendix_A_Target_82"></a><a aria-label="Product behavior note 82" href="3a466440-1ef6-4439-b4e2-be9eaddeb511#Appendix_A_82" data-linktype="relative-path">&lt;82&gt;</a><a id="Appendix_A_Target_83"></a><a aria-label="Product behavior note 83" href="3a466440-1ef6-4439-b4e2-be9eaddeb511#Appendix_A_83" data-linktype="relative-path">&lt;83&gt;</a></p><p>The server MUST verify the existence of the DFS namespace
that the <i>DfsEntryPath</i> parameter specifies. If the namespace does not
exist, the server MUST return ERROR_NOT_FOUND.</p><p>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.</p><p>If the link to be added already exists, and DFS_ADD_VOLUME
is set in the <b>Flags</b> field of the request, the server MUST return
ERROR_FILE_EXISTS.</p><p>If the link to be added already exists, and DFS_ADD_VOLUME
is not set in the <b>Flags</b> 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 <i>ServerName</i>
and <i>ShareName</i> was already added to the link, the server MUST return
ERROR_FILE_EXISTS.</p><p>If DFS_RESTORE_VOLUME is not specified on the Flags
parameter, the server MAY<a id="Appendix_A_Target_84"></a><a aria-label="Product behavior note 84" href="3a466440-1ef6-4439-b4e2-be9eaddeb511#Appendix_A_84" data-linktype="relative-path">&lt;84&gt;</a> 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.</p><p>The exact test the server performs to verify link target
existence is implementation-defined. A server MAY,<a id="Appendix_A_Target_85"></a><a aria-label="Product behavior note 85" href="3a466440-1ef6-4439-b4e2-be9eaddeb511#Appendix_A_85" data-linktype="relative-path">&lt;85&gt;</a> for example,
be implemented with the expectation that all link targets are administered
through <a href="../ms-srvs/accf23b0-0f57-441c-9185-43041f1b0ee9" data-linktype="relative-path">[MS-SRVS]</a>
section <a href="../ms-srvs/b2c2b995-8c42-4502-b7d7-646d1b295c5b" data-linktype="relative-path">3.1.4.10</a>
and use NetShareGetInfo level 1005 to perform the test. Reasons not to
implement this test include:</p><ul><li><p><span><span> 
</span></span>It might not be practical to determine the correct administration
interface to query to perform the test.</p>
</li><li><p><span><span> 
</span></span>A link target server can export a share with a network protocol
and administration interface that this server does not understand.</p>
</li><li><p><span><span> 
</span></span>A secured link target server might not permit this server to
contact it.</p>
</li></ul><p>The <i>Comment</i> parameter MUST be ignored when adding a
target to an existing link.</p><p>The server SHOULD<a id="Appendix_A_Target_86"></a><a aria-label="Product behavior note 86" href="3a466440-1ef6-4439-b4e2-be9eaddeb511#Appendix_A_86" data-linktype="relative-path">&lt;86&gt;</a> create a
new link without requiring the DFS_ADD_VOLUME <i>Flags</i> parameter.</p><p>The server MUST update the same fields in the DFS metadata
for a domain-based DFS namespace as in the <a href="25938398-c070-4db1-a779-fc78212f3fd8" data-linktype="relative-path">NetrDfsAdd</a> method, as
specified in section 3.1.4.1.3.</p><p>The server MUST synchronously update the DFS metadata of a
domain-based DFS namespace.</p><p>If <a href="a9bc4403-a862-48b9-b99b-1b44a887d177#gt_cf94d206-f71c-4ca1-891a-24c83f533e45" data-linktype="relative-path">DFS
root scalability mode</a> is not enabled for the domain-based DFS namespace,
the server MUST do one of the following:</p><ul><li><p><span><span> 
</span></span>Notify other DFS root targets of the change in DFS metadata by
asynchronously issuing a <a href="7b033d5b-8d26-4931-8b3d-7aa35e441fb0" data-linktype="relative-path">NetrDfsSetInfo</a>
method with the <i>Level</i> parameter 101 and with the <b>State</b> field of <a href="af9d607e-04e5-4722-8d00-76cf9c7b69f9" data-linktype="relative-path">DFS_INFO_101</a> set to
DFS_VOLUME_STATE_RESYNCHRONIZE. The returned <i>ppRootList</i> parameter MUST
be empty.</p>
</li><li><p><span><span> 
</span></span>Perform no notification of the other root targets, returning a
list of DFS root targets to the client in the <i>ppRootList</i> parameter.</p>
</li></ul></div>