3.1.4.33 NetprNameCanonicalize (Opnum 34)

The NetprNameCanonicalize method converts a name to the canonical format for the specified type.

 NET_API_STATUS NetprNameCanonicalize(
   [in, string, unique] SRVSVC_HANDLE ServerName,
   [in, string] WCHAR* Name,
   [out, size_is(OutbufLen)] WCHAR* Outbuf,
   [in, range(0,64000)] DWORD OutbufLen,
   [in] DWORD NameType,
   [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.

Name: A pointer to a null-terminated UTF-16 string specifying the name to canonicalize.

Outbuf: A pointer to a null-terminated UTF-16 string that is the buffer where the canonicalized name is returned.

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

NameType: The type of Name, as specified in section 2.2.2.8.

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

Value	Meaning
0x80000000	LM2.x compatible name canonicalization.
0x00000001	If set, the method requires the length of the output buffer to be sufficient to hold any name of the specified type. Otherwise, the buffer length only needs to be large enough to hold the canonicalized version of the input name that is specified in this invocation of the method.

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.

In response to a NetprNameCanonicalize message, the server MUST convert the value of the Name parameter to one of the canonical forms that are defined in section 2.2.2.8.

The NameType parameter determines what needs to be done on the name that is specified by the Name parameter to convert it to a canonical format. Valid values for the NameType parameter are as specified in Name Types (section 2.2.2.8). If the NameType parameter does not have a valid value, the server MUST fail the call with an ERROR_INVALID_PARAMETER error code.

The Flags parameter is a bitmask that specifies certain controlling flags that affect how the server processes this message. The valid bits are 0x80000000 and 0x1. If any other bit is set, the server MUST fail the call with an ERROR_INVALID_PARAMETER error code.

If (Flags & 0x80000000) is true, it implies that the server MUST perform an NTLM version 2.x–compatible canonicalization. As the following table specifies, some NameTypes have different rules about how to define a canonical name for those types on NTLM version 2.x.

The server MUST validate the Name (as specified by the NetprNameValidate method) to ensure that it is a valid name of type NameType. If validation fails, the server MUST fail the call with ERROR_INVALID_NAME.

The server MUST use the NameType parameter to determine the maximum length of any name for that type (as specified in the following table). If (Flags & 0x1) is true and the length of the output buffer specified by the OutBufLen parameter is not greater than or equal to the maximum length of any name for that type, the server MUST fail the call with an NERR_BufTooSmall error code.

The canonicalization process then truncates the Name so that the length is no greater than the maximum length for that type, converting the name to uppercase if needed. The following table specifies the maximum length for each NameType and whether the server converts names to uppercase. The second column in the table specifies the behavior when (Flags & 0x80000000) is true, and the third column specifies the behavior when it is false.

The server MAY<123> 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<124> fail the call.