3.1.4.31 NetprPathCompare (Opnum 32)

The NetprPathCompare method performs comparison of two paths.

 long NetprPathCompare(
   [in, string, unique] SRVSVC_HANDLE ServerName,
   [in, string] WCHAR* PathName1,
   [in, string] WCHAR* PathName2,
   [in] 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.

PathName1: A pointer to a null-terminated UTF-16 string that contains the first PathName to compare.

PathName2: A pointer to a null-terminated UTF-16 string that contains the second PathName to compare.

PathType: The type of PathName, as specified in section 2.2.2.9.

Flags: A bitmask that MUST contain the bitwise OR of zero or more of the following values that specify controlling flags.

Value	Meaning
0x00000001	SHOULD be set if both of the paths have already been canonicalized.

Return Values: Upon successful processing, the server MUST return 0 if both paths are the same, –1 if the first is less than the second, and 1 otherwise. If the method fails, it can return any specific error code value as specified in [MS-ERREF] section 2.2.

In response to a NetprPathCompare message, the server MUST compare the two paths that are specified as parameters to see if they match and return this result or return an error code. If the supplied names are not canonicalized, the server MUST do the canonicalization of the path names before a comparison can occur. This does not modify the input path names. The clients SHOULD call this method with canonicalized path names only, because the canonicalization operation can be expensive. If uncanonicalized path names are passed in, the caller SHOULD be aware that a nonzero result could be due to an error that occurred during canonicalization.

The PathName1 and PathName2 parameters specify the two path names to be compared.

The Flags parameter MUST be either 0 or 1. If the Flags parameter has any other value, the server MUST fail the call with ERROR_INVALID_PARAMETER. If the Flags parameter is 1, it implies that the specified path names are already canonicalized and the server MUST not try to canonicalize them.

Any combination of Name1 (canonicalized or not), Name2 (canonicalized or not), and Flags (0 or 1) is valid.

If Flags is set to 0, the server MUST first attempt to canonicalize both Name1 and Name2 (and MUST respond with an error if canonicalization fails) before comparing the names.

If Flags is set to 1, the server MUST compare the names without first attempting canonicalization. Using Flags=1 could optimize performance because it eliminates the need for the server to repeatedly canonicalize a path name if it is being compared multiple times. If the Flags parameter does not have a valid value, the server MUST fail the call with an ERROR_INVALID_PARAMETER error code.

If the Flags parameter is 1, the PathType parameter MUST specify the path type for the two path names. Valid values for the PathType parameter are as specified in section 2.2.2.9. If the PathType parameter does not have a valid value, the server MAY<116> fail the call.

If the Flags parameter is 0, the server MUST canonicalize the specified path names and obtain their PathTypes first, as specified in section 3.1.4.30. If this fails, the server MUST fail the call with ERROR_INVALID_NAME. If the PathTypes for the two path names thus obtained are different, the server MUST return 1.

The server then compares the canonicalized path names by using an implementation-specific<117> comparison and MUST return 0 to the caller if the paths match, –1 if PathName1 is less than PathName2, and 1 if PathName1 is greater than PathName2.

The server MAY<118> 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<119> fail the call.