3.1.4.30 NetprPathCanonicalize (Opnum 31)

  • Article

The NetprPathCanonicalize method converts a path name to the canonical format.

 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
 );

ServerName: An SRVSVC_HANDLE (section 2.2.1.1) pointer that identifies the server. The client MUST map this structure to an RPC binding handle (see [C706] sections 4.3.5 and 5.1.5.2). The server MUST ignore this parameter.

PathName: A pointer to a null-terminated UTF-16 string that specifies the path name to canonicalize.

Outbuf: A pointer to the output buffer where the canonicalized path name is returned.

OutbufLen: The length, in bytes, of the output buffer, Outbuf. The value of this field MUST be within the range 0–64,000, inclusive.

Prefix: A pointer to a null-terminated UTF-16 string that specifies an optional prefix to use when canonicalizing a relative path name.

PathType: 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 2.2.2.9. After successful completion of the request, the server MUST set PathType to one of the values defined in section 2.2.2.9.

Flags: Reserved, MUST be zero.

Return Values: 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 [MS-ERREF] section 2.2.

If the Flags parameter is not equal to zero, the server SHOULD fail the call with an implementation-specific error code.<111>

In response to a NetprPathCanonicalize message, the server MUST compute the canonical version of the specified path name or return an error code.

The PathName parameter specifies the path name that needs to be canonicalized.

The PathType parameter, if nonzero, MUST specify the path type of the path that is specified by the PathName parameter by a previous successful call to the NetprPathType 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 PathType is zero, the server MUST validate and get the type of PathName (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.

The Prefix parameter, if it is a nonempty string, specifies a path component that MUST be prefixed to PathName to get the full path to canonicalize. The server MUST treat Prefix as a PathName: it MUST validate and get the type of Prefix in the same way as it does the PathName. If this fails, the server MUST fail the call with an ERROR_INVALID_NAME error code. The optional Prefix parameter is a convenience that this method provides to clients. The client is free to construct the complete PathName and pass NULL for the Prefix. 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 Prefix is the absolute path for the directory, and the value for PathName specifies the relative path for a file.

The OutBufLen parameter specifies the length of the output buffer OutBuf that is provided by the client. If the length of the canonicalized path name is greater than OutBufLen, the server MUST fail the call with an NERR_BufTooSmall error code.

The server MUST construct the path to canonicalize by appending the PathName to the Prefix. If the Prefix parameter does not end with one, the server SHOULD insert an implementation-specific path separator between the Prefix and PathName.<112> The server MUST then canonicalize the resultant path. The canonicalization process is implementation-dependent.<113>

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 PathType parameter. Valid return codes for the PathType 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.

The server MAY<114> 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<115> fail the call.