<div class="content" name="NetprPathCanonicalize" uuid="9281f528-e2e7-4113-abd8-6db7255e4387"><p>The NetprPathCanonicalize method converts a path name to the
canonical format.</p><dl>
<dd>
<div><pre> NET_API_STATUS NetprPathCanonicalize(
   [in, string, unique] SRVSVC_HANDLE ServerName,
   [in, string] WCHAR* PathName,
   [out, size_is(OutbufLen)] unsigned char* Outbuf,
   [in, range(0,64000)] DWORD OutbufLen,
   [in, string] WCHAR* Prefix,
   [in, out] DWORD* PathType,
   [in] DWORD Flags
 );
</pre></div>
</dd></dl><p><b>ServerName: </b>An <a href="5f8329ee-1965-4ea1-ad35-3b29fbb63232" data-linktype="relative-path">SRVSVC_HANDLE (section 2.2.1.1)</a>
pointer that identifies the <a href="1709f6a7-efb8-4ded-b7ae-5cee9ee36320#gt_434b0234-e970-4e8c-bdfa-e16a30d96703" data-linktype="relative-path">server</a>.
The <a href="1709f6a7-efb8-4ded-b7ae-5cee9ee36320#gt_60e0e1fa-66fe-41e1-b5e3-ceab97e53506" data-linktype="relative-path">client</a> MUST map this
structure to an <a href="1709f6a7-efb8-4ded-b7ae-5cee9ee36320#gt_8a7f6700-8311-45bc-af10-82e10accd331" data-linktype="relative-path">RPC</a>
binding handle (see <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>PathName: </b>A pointer to a null-terminated
UTF-16 string that specifies the path name to canonicalize.</p><p><b>Outbuf: </b>A pointer to the output buffer where
the canonicalized path name is returned.</p><p><b>OutbufLen: </b>The length, in bytes, of the output
buffer, <i>Outbuf</i>. The value of this field MUST be within the range
0–64,000, inclusive.</p><p><b>Prefix: </b>A pointer to a null-terminated UTF-16
string that specifies an optional prefix to use when canonicalizing a relative
path name.</p><p><b>PathType: </b>A place to store the path type. This
parameter MUST be set by the client either to zero or to one of the values
defined in section <a href="03f17df3-ad31-4aed-a677-30261ac206a5" data-linktype="relative-path">2.2.2.9</a>.
After successful completion of the request, the server MUST set <i>PathType</i>
to one of the values defined in section 2.2.2.9.</p><p><b>Flags: </b>Reserved, MUST be zero.</p><p><b>Return Values: </b>The method returns 0x00000000
(NERR_Success) to indicate success; otherwise, it returns a nonzero error code.
The method can take 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>.
</p><p>If the <i>Flags</i> parameter is not equal to zero, the
server SHOULD fail the call with an implementation-specific error code.<a id="Appendix_A_Target_111"></a><a aria-label="Product behavior note 111" href="ebb74ff2-abb1-4e1b-a76a-563a5cbbea9a#Appendix_A_111" data-linktype="relative-path">&lt;111&gt;</a></p><p>In response to a NetprPathCanonicalize message, the server
MUST compute the canonical version of the specified path name or return an
error code.</p><p>The <i>PathName</i> parameter specifies the path name that
needs to be canonicalized.</p><p>The <i>PathType</i> parameter, if nonzero, MUST specify the
path type of the path that is specified by the <i>PathName</i> parameter by a
previous successful call to the <a href="30cef6ab-fae2-4e18-8ec9-d4714cda0da0" data-linktype="relative-path">NetprPathType</a> method. Even
if it is set to the correct nonzero value by the client, the server can change
it because the canonicalized version of a name can be of a different type than
the original version. If <i>PathType</i> is zero, the server MUST validate and
get the type of <i>PathName</i> (as specified in section 3.1.4.29) first. If
this fails, the server MUST fail the call with an ERROR_INVALID_NAME error
code.</p><p>The <i>Prefix</i> parameter, if it is a nonempty string,
specifies a path component that MUST be prefixed to <i>PathName</i> to get the
full path to canonicalize. The server MUST treat <i>Prefix</i> as a <i>PathName</i>:
it MUST validate and get the type of <i>Prefix</i> in the same way as it does
the <i>PathName</i>. If this fails, the server MUST fail the call with an
ERROR_INVALID_NAME error code. The optional <i>Prefix</i> parameter is a
convenience that this method provides to clients. The client is free to
construct the complete <i>PathName</i> and pass NULL for the <i>Prefix</i>. For
example, this parameter can be used when canonicalizing path names for a list
of files in a directory. In such a scenario, the value for <i>Prefix</i> is the
absolute path for the directory, and the value for <i>PathName</i> specifies
the relative path for a file.</p><p>The <i>OutBufLen</i> parameter specifies the length of the
output buffer <i>OutBuf</i> that is provided by the client. If the length of
the canonicalized path name is greater than <i>OutBufLen</i>, the server MUST
fail the call with an NERR_BufTooSmall error code.</p><p>The server MUST construct the path to canonicalize by
appending the <i>PathName</i> to the <i>Prefix</i>. If the <i>Prefix</i>
parameter does not end with one, the server SHOULD insert an implementation-specific
path separator between the <i>Prefix</i> and <i>PathName</i>.<a id="Appendix_A_Target_112"></a><a aria-label="Product behavior note 112" href="ebb74ff2-abb1-4e1b-a76a-563a5cbbea9a#Appendix_A_112" data-linktype="relative-path">&lt;112&gt;</a> The server MUST then
canonicalize the resultant path. The canonicalization process is
implementation-dependent.<a id="Appendix_A_Target_113"></a><a aria-label="Product behavior note 113" href="ebb74ff2-abb1-4e1b-a76a-563a5cbbea9a#Appendix_A_113" data-linktype="relative-path">&lt;113&gt;</a></p><p>After the canonicalization is successfully finished, the
server MUST determine the path type of the canonicalized path name, as
specified in NetprPathType (section 3.1.4.29), and store the result
in the <i>PathType</i> parameter. Valid return codes for the <i>PathType</i>
parameter are as specified in Path Types (section 2.2.2.9). If this
fails, the server MUST fail the call with an ERROR_INVALID_NAME error code.</p><p>The server MAY<a id="Appendix_A_Target_114"></a><a aria-label="Product behavior note 114" href="ebb74ff2-abb1-4e1b-a76a-563a5cbbea9a#Appendix_A_114" data-linktype="relative-path">&lt;114&gt;</a>
enforce security measures to verify that the caller has the required
permissions to execute this call. If the server enforces these security
measures and the caller does not have the required credentials, the server
SHOULD<a id="Appendix_A_Target_115"></a><a aria-label="Product behavior note 115" href="ebb74ff2-abb1-4e1b-a76a-563a5cbbea9a#Appendix_A_115" data-linktype="relative-path">&lt;115&gt;</a> fail the call.</p></div>