Important: |
---|
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist. |
This function converts a URL to a canonical form, including conversion of unsafe characters into escape sequences.
BOOL WINAPI InternetCanonicalizeUrl( LPCTSTR lpszUrl, LPTSTR lpszBuffer, LPDWORD lpdwBufferLength, DWORD dwFlags );
Parameters
Value | Description |
---|---|
ICU_BROWSER_MODE | Does not encode or decode characters after "#" or "?", and does not remove trailing white space after "?". If this value is not specified, the entire URL is encoded, and trailing white space is removed. |
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. |
If no flags are specified ( dwFlags= 0), the function converts all unsafe characters and meta sequences (such as \.,\ .., and \...) to escape sequences.
Return Values
TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. Possible error values for GetLastErrorare described in the following table.
Value | Description |
---|---|
ERROR_BAD_PATHNAME | The URL could not be canonicalized. |
ERROR_INSUFFICIENT_BUFFER | Canonicalized URL is too large to fit in the buffer provided. The *lpdwBufferLengthparameter 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 | Bad string, buffer, buffer size, or flags parameter. |
Windows CE Remarks
The lpdwBufferLengthparameter refers to count of characters. If the function succeeds, this parameter receives the length, in characters, of the lpszBufferbuffer excluding the terminating null. If the function fails, this parameter receives the required length, in characters, of the lpszBufferbuffer, including the terminating null.
Remarks
InternetCanonicalizeUrlalways encodes by default, even if the ICU_DECODE flag has been specified. To decode without re-encoding, use ICU_DECODE | ICU_NO_ENCODE. If the ICU_DECODE flag is used without ICU_NO_ENCODE, the URL is decoded before being parsed; unsafe characters then are re-encoded after parsing. This function will handle arbitrary protocol schemes, but to do so it must make inferences from the unsafe character set.
The application calling InternetCanonicalizeUrlshould track the usage of this function on a particular URL. If unsafe characters in a URL have been converted to escape sequences, using InternetCanonicalizeUrlagain on the URL (with no flags) will cause the escape sequences to be converted to another escape sequence. For example, a blank space in a URL would be converted to the escape sequence "%20". Calling InternetCanonicalizeUrlagain on the URL would cause the escape sequence "%20" to be converted to the escape sequence "%2520", because the "%" sign is an unsafe character that is reserved for escape sequences and is replaced by the function with the escape sequence "%25".
Requirements
Runs on | Versions | Defined in | Include | Link to |
---|---|---|---|---|
Windows CE OS | 2.0 and later | Wininet.h | Schannel.lib |
Note This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.
See Also