Share via

InternetCanonicalizeUrl (Windows Embedded CE 6.0)

  • Article

1/6/2010

This function converts a URL to a canonical form, including the conversion of unsafe characters into escape sequences.

Syntax

BOOL WINAPI InternetCanonicalizeUrl(
  LPCTSTR lpszUrl, 
  LPWSTR lpszBuffer, 
  LPDWORD lpdwBufferLength, 
  DWORD dwFlags 
);

Parameters

  • lpszUrl
    [in] Pointer to the input URL to canonicalize.
  • lpszBuffer
    [out] Pointer to the buffer containing the canonicalized URL.
  • lpdwBufferLength
    [in, out] Pointer to the length, in characters, of the lpszBuffer buffer. If the function succeeds, this parameter indicates the length, in characters, of the lpszBuffer buffer, excluding the terminating null. If the function fails, this parameter indicates the required length, in characters, of the lpszBuffer buffer. The required length includes the terminating null.

  • dwFlags
    [in] Flags specifying the control canonicalization. The following table shows the possible values. If no flags are specified (dwFlags = 0), the function converts all unsafe characters and meta-sequences (such as \.,\ .., and \...) to escape sequences.

    Value Description

    ICU_DECODE

    Converts all %XX sequences to characters, including escape sequences, before the URL is parsed.

    ICU_ENCODE_SPACES_ONLY

    Encodes spaces only.

    ICU_NO_ENCODE

    Does not convert unsafe characters to escape sequences.

    ICU_NO_META

    Does not remove meta sequences (such as . and ..) from the URL.

Return Value

Returns TRUE to indicate success, and FALSE to indicate failure. To get extended error information, the application should call GetLastError. The following table describes the possible error values for GetLastError.

Value Description

ERROR_BAD_PATHNAME

The URL could not be canonicalized.

ERROR_INSUFFICIENT_BUFFER

The canonicalized URL is too large to fit in the buffer provided. The lpdwBufferLength parameter is set to the size, in bytes, of the buffer required to hold the resultant, canonicalized URL.

ERROR_INTERNET_INVALID_URL

The format of the URL is invalid.

ERROR_INVALID_PARAMETER

A bad string, buffer, buffer size, or flags parameter.

Remarks

This function always encodes by default, even if the ICU_DECODE flag is specified. To decode without re-encoding, the application should use ICU_DECODE | ICU_NO_ENCODE. If the ICU_DECODE flag is used without ICU_NO_ENCODE, the function decodes the URL before parsing, and then re-encodes unsafe characters after parsing.

This function will handle arbitrary protocol schemes. However, to do so, it must make inferences from the unsafe character set.

The application should track the use of this function on a particular URL. If unsafe characters in a URL have been converted to escape sequences, using InternetCanonicalizeUrl again on the URL (with no flags) will convert the the escape sequences to another escape sequence. For example, a blank space in a URL will be converted to the escape sequence %20. Calling InternetCanonicalizeUrl again on the URL will convert the escape sequence %20 to the escape sequence %2520. The reason for this conversion is that the function replaces the percent (%) sign, an unsafe character reserved for escape sequences, with the escape sequence %25.

Requirements

Header wininet.h
Library secur32.lib
Windows Embedded CE Windows CE 2.0 and later

See Also

Reference

Authentication Services Functions

Other Resources

Windows Internet Services (WinInet)