<div class="content" name="NetrUseAdd" uuid="e4490e47-3dbc-45c4-8995-5c6bd095fdf5"><p>The <b>NetrUseAdd</b> method establishes a connection
between the workstation server and an SMB server. Workstation servers SHOULD
NOT allow this method to be invoked remotely<a id="Appendix_A_Target_45"></a><a aria-label="Product behavior note 45" href="def80006-2495-4571-8a93-1668e0f8af31#Appendix_A_45" data-linktype="relative-path">&lt;45&gt;</a> and
SHOULD return ERROR_CALL_NOT_IMPLEMENTED.</p><dl>
<dd>
<div><pre> unsigned long NetrUseAdd(
   [in, string, unique] WKSSVC_IMPERSONATE_HANDLE ServerName,
   [in] unsigned long Level,
   [in, switch_is(Level)] LPUSE_INFO InfoStruct,
   [in, out, unique] unsigned long* ErrorParameter
 );
</pre></div>
</dd></dl><p><b>ServerName: </b>A <b>WKSSVC_IMPERSONATE_HANDLE</b>
structure (section <a href="2427e140-22b3-45f8-9e12-1b3593308e46" data-linktype="relative-path">2.2.2.2</a>)
that identifies the <a href="3acf0e02-9bbd-4ce0-a7a0-586bc72d3ef4#gt_434b0234-e970-4e8c-bdfa-e16a30d96703" data-linktype="relative-path">server
(2)</a>. The <a href="3acf0e02-9bbd-4ce0-a7a0-586bc72d3ef4#gt_60e0e1fa-66fe-41e1-b5e3-ceab97e53506" data-linktype="relative-path">client</a> MUST
map this structure to an <a href="3acf0e02-9bbd-4ce0-a7a0-586bc72d3ef4#gt_8a7f6700-8311-45bc-af10-82e10accd331" data-linktype="relative-path">RPC</a>
binding handle (<a href="https://go.microsoft.com/fwlink/?LinkId=89824" data-linktype="external">[C706]</a>
sections 4.3.5 and 5.1.5.2). The server MUST ignore this parameter.</p><p><b>Level: </b>A value that specifies the information
level of the data. This parameter MUST be one of the following values;
otherwise, the server MUST fail the call with an ERROR_INVALID_LEVEL code.</p><dl>
<dd>
<table><thead>
  <tr>
   <th>
   <p>Value</p>
   </th>
   <th>
   <p>Meaning</p>
   </th>
  </tr>
 </thead><tbody><tr>
  <td>0x00000000</td>
  <td>The buffer is a USE_INFO_0 structure (section 2.2.5.22).</td>
 </tr><tr>
  <td>0x00000001</td>
  <td>The buffer is a USE_INFO_1 structure (section 2.2.5.23).</td>
 </tr><tr>
  <td>0x00000002</td>
  <td>The buffer is a USE_INFO_2 structure (section 2.2.5.24).</td>
 </tr><tr>
  <td>0x00000003</td>
  <td>The buffer is a USE_INFO_3 structure (section 2.2.5.25).</td>
 </tr></tbody></table>
</dd></dl><p><b>InfoStruct: </b>A pointer to the buffer that
specifies the data. The format of this data depends on the value of the <i>Level</i>
parameter.</p><p><b>ErrorParameter: </b>A pointer to a value that
receives an unsigned 32-bit integer. This parameter is meaningful only if the
method returns ERROR_INVALID_PARAMETER.</p><p><b>Return Values: </b>When the message processing
result meets the description in the right-hand column of the following table,
this method MUST return one of the following values (<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>).</p><dl>
<dd>
<table><thead>
  <tr>
   <th>
   <p>Value/code</p>
   </th>
   <th>
   <p>Meaning</p>
   </th>
  </tr>
 </thead><tbody><tr>
  <td>NERR_Success 0x00000000</td>
  <td>The operation completed successfully.</td>
 </tr><tr>
  <td>ERROR_ACCESS_DENIED 0x00000005</td>
  <td>Access is denied.</td>
 </tr><tr>
  <td>ERROR_INVALID_PARAMETER 0x00000057</td>
  <td>One of the function parameters is not valid.</td>
 </tr><tr>
  <td>ERROR_INVALID_LEVEL 0x0000007C</td>
  <td>The information level is invalid.</td>
 </tr><tr>
  <td>ERROR_CALL_NOT_IMPLEMENTED 0x00000078</td>
  <td>This function is not supported on this system.</td>
 </tr></tbody></table>
</dd></dl><p>The server SHOULD<a id="Appendix_A_Target_46"></a><a aria-label="Product behavior note 46" href="def80006-2495-4571-8a93-1668e0f8af31#Appendix_A_46" data-linktype="relative-path">&lt;46&gt;</a> enforce
security measures to verify that the caller has the required permissions to
execute this routine. If the server enforces security measures and the caller
does not have the required credentials, the server SHOULD fail the call with
ERROR_ACCESS_DENIED. Specifications for determining the identity of the caller
for the purpose of performing an access check are in <a href="../ms-rpce/290c38b1-92fe-4229-91e6-4fc376610c15" data-linktype="relative-path">[MS-RPCE]</a>
section <a href="../ms-rpce/0e5b0e1c-0ba5-4342-bc36-30c66a9d07fd" data-linktype="relative-path">3.3.3.1.3</a>.</p><p>The <i>Level</i> parameter determines the type of structure
that the client has used to specify details about the new connection. The value
MUST be 0, 1, 2, or 3. If the <i>Level</i> parameter is not equal to one of the
valid values, the server MUST fail the call with an ERROR_INVALID_LEVEL error
code.</p><ul><li><p><span><span> 
</span></span>If the <i>Level</i> parameter is 0x00000000, the Buffer parameter
points to a <b>USE_INFO_0</b> structure.</p>
</li><li><p><span><span> 
</span></span>If the <i>Level</i> parameter is 0x00000001, the Buffer parameter
points to a <b>USE_INFO_1</b> structure.</p>
</li><li><p><span><span> 
</span></span>If the <i>Level</i> parameter is 0x00000002, the Buffer parameter
points to a <b>USE_INFO_2</b> structure.</p>
</li><li><p><span><span> 
</span></span>If the <i>Level</i> parameter is 0x00000003, the Buffer parameter
points to a <b>USE_INFO_3</b> structure.</p>
</li></ul><p>The server MUST verify the <b>InfoStruct</b> elements as
follows:</p><ul><li><p><span><span> 
</span></span>If ui*_remote is not a UNC path format, the server MUST fail the
call with ERROR_INVALID_PARAMETER. If ui*_remote is a UNC path format, it MUST
canonicalize the ui*_remote path (<a href="../ms-srvs/accf23b0-0f57-441c-9185-43041f1b0ee9" data-linktype="relative-path">[MS-SRVS]</a>
section <a href="../ms-srvs/e79aaff9-ba49-4548-8cc6-7041a7fcf907" data-linktype="relative-path">3.1.4.33</a>).</p>
</li><li><p><span><span> 
</span></span>If ui*_local is not NULL, the server MUST canonicalize ui*_local
and verify the device name format based on ui*_asg_type.</p>
<ul><li><p><span><span>  </span></span>If
ui*_asg_type is USE_WILDCARD or USE_IPC, the server MUST fail the call with
ERROR_INVALID_PARAMETER.</p>
</li><li><p><span><span>  </span></span>If
ui*_asg_type is USE_DISKDEV, ui*_local MUST be in the form &#34;&lt;drive
name&gt;:&#34;. Otherwise, the server MUST fail the call with
ERROR_INVALID_PARAMETER.</p>
</li><li><p><span><span>  </span></span>If
ui*_asg_type is USE_SPOOLDEV, ui*_local MUST be in the form &#34;LPTn:&#34;
or &#34;PRN:&#34;. Otherwise, the server MUST fail the call with
ERROR_INVALID_PARAMETER.</p>
</li><li><p><span><span>  </span></span>If
ui*_asg_type is USE_CHARDEV, ui*_local MUST be in the form &#34;COMn:&#34; or
&#34;AUX:&#34;. Otherwise, the server MUST fail the call with
ERROR_INVALID_PARAMETER.</p>
</li></ul></li><li><p><span><span> 
</span></span>If the <i>Level</i> parameter value is greater than or equal to 2
and ui*_username, ui*_password, and ui*_domainname are NULL, the server MUST
attempt to establish a null session (<a href="../ms-cifs/d416ff7c-c536-406e-a951-4f04b2fd1d2b" data-linktype="relative-path">[MS-CIFS]</a>
section <a href="../ms-cifs/3a3cdd47-5b43-4276-91f5-645b82b0938f" data-linktype="relative-path">3.2.4.2.4</a>).
If the <i>Level</i> parameter value is greater than or equal to 2 and
ui*_username, ui*_password, and ui*_domainname are not NULL, the server MUST
canonicalize the user name, password, and domain name ([MS-SRVS] section
3.1.4.33).</p>
</li><li><p><span><span> 
</span></span>If the length of ui*_password is greater than 65, the server MUST
fail the call with ERROR_INVALID_PARAMETER.</p>
</li></ul><p>The server MUST ensure that the remaining steps are executed
atomically with respect to other callers performing queries or updates to the <b>UseTable</b>
and <b>Connection</b> tables.</p><p>If <b>IsWorkstationPaused</b> is TRUE, the server MUST
verify the format of ui*_local. If ui*_local is prefixed with &#34;PRN&#34;
or &#34;COM&#34;, the server MUST fail the call with an ERROR_REDIR_PAUSED
error code. Otherwise, the server MUST invoke the events specified in [MS-CIFS]
section <a href="../ms-cifs/6d776ad6-fd99-40b5-8655-3fcef6cb7a02" data-linktype="relative-path">3.4.4.10</a>,
passing the following as the parameters: name of the server in the ui*_remote
field, name of the share in ui*_remote, and user credentials associated with
ui*_username constructed from ui*_username, ui*_domainname, and ui*_password.</p><p>If the CIFS server returns STATUS_SUCCESS, the server MUST
verify the remote resource type and local device type.</p><p>If the CIFS server returns the remote resource type
&#34;unknown&#34; and ui*_remote is in the form &#34;\\server\IPC$&#34; or
&#34;\\server\pipe&#34;, the server MUST treat the remote resource type as a
&#34;named pipe&#34;. If the CIFS server returns the remote resource type
&#34;unknown&#34; and ui*_remote is NOT of the form &#34;\\server\IPC$&#34;
or &#34;\\server\pipe&#34;, the server MUST treat the remote resource type as
a &#34;disk share&#34;.</p><p>If the remote resource type does not match a local device
type, the server MUST fail the call with ERROR_INVALID_PARAMETER. If the remote
resource type matches a local device type, the server MUST initialize a new
connection and add it to the <b>Connection</b> table. The connection MUST be
initialized as follows:</p><ul><li><p><span><span> 
</span></span><b>Connection.local</b> is set to the canonicalized ui*_local
name.</p>
</li><li><p><span><span> 
</span></span><b>Connection.remote</b> is set to the canonicalized ui*_remote
path name.</p>
</li><li><p><span><span> 
</span></span><b>Connection.status</b> is set to the caller-supplied
ui*_status.</p>
</li><li><p><span><span> 
</span></span><b>Connection.asgtype</b> is set to the caller-supplied
ui*_asg_type.</p>
</li><li><p><span><span> 
</span></span><b>Connection.refcount</b> is set to the caller-supplied
ui*_refcount.</p>
</li><li><p><span><span> 
</span></span><b>Connection.username</b> is set to ui*_username.</p>
</li><li><p><span><span> 
</span></span><b>Connection.usecount</b> is set to ui*_usecount.</p>
</li><li><p><span><span> 
</span></span><b>Connection.domain</b> is set to ui*_domainname.</p>
</li><li><p><span><span> 
</span></span><b>Connection.context</b> is set to the <b>ClientGenericContext</b>
structure returned by the CIFS server ([MS-CIFS] section 3.4.4.10).</p>
</li></ul><p>The server MUST invoke the event to impersonate the client
([MS-RPCE] section <a href="../ms-rpce/a996aa17-8e04-4a25-806a-a3c724230e12" data-linktype="relative-path">3.3.3.4.3.1</a>),
passing NULL as input parameter. If this event fails, the server MUST return an
error. If the event returns UserToken, the server MUST look in <b>UseTable</b>
for an entry where UserToken matches <b>UseEntry.UserToken</b>. If no entry is
found, the server MUST create a new entry in <b>UseTable</b> and insert a new
connection entry in <b>UseEntry.ConnectionTable</b>. The server MUST invoke the
event to end the client impersonation ([MS-RPCE] section <a href="../ms-rpce/53d8f057-4e3a-4bc4-9355-a1cd781de901" data-linktype="relative-path">3.3.3.4.3.3</a>)
and return NERR_Success to the caller.</p><p>If the CIFS server returns a failure, the server MUST invoke
the event to end the client impersonation ([MS-RPCE] section 3.3.3.4.3.3) and
fail the call with the status code received from the event.</p></div>