CoInternetParseUrl function
Transforms and identifies parts of URLs. Compare to CoInternetParseIUri.
Syntax
STDAPI CoInternetParseUrl(
LPCWSTR pwzUrl,
PARSEACTION ParseAction,
DWORD dwFlags,
LPWSTR pszResult,
DWORD cchResult,
DWORD *pcchResult,
_Reserved_ DWORD dwReserved
);
Parameters
pwzUrl
String value that contains the URL to parse.
ParseAction
One of the following PARSEACTION values:
(PARSE_CANONICALIZE)
Canonicalize the URL.
(PARSE_ROOTDOCUMENT)
Retrieve the scheme and hostname of the URL; for example, https://www.microsoft.com.
(PARSE_ENCODE or PARSE_ESCAPE)
Percent-encode reserved characters in the URL.
(PARSE_DECODE or PARSE_UNESCAPE)
Decode percent-encoded character sequences in the URL.
(PARSE_PATH_FROM_URL)
Convert a file:// URL scheme into a DOS file path.
(PARSE_URL_FROM_PATH)
Convert a DOS path into a file:// URL.
(PARSE_SCHEMA)
Retrieve the URL scheme; for example, http.
(PARSE_DOMAIN)
Retrieve the hostname; for example, www.microsoft.com.
(PARSE_LOCATION)
Retrieve the URL fragment (named anchor); for example, #top.
dwFlags
Unsigned long integer value that controls the parsing operation, based on the value passed as the ParseAction parameter. For valid flags, see Remarks section.
pszResult
String value that contains the information parsed from the URL.
cchResult
Unsigned long integer value that contains the size of the buffer.
pcchResult
Pointer to an unsigned long integer value that contains the size of the information stored in the buffer.
dwReserved
Reserved. Must be set to 0.
Return value
Returns one of the following values.
| Return code | Description |
|---|---|
| S_OK | Success. |
| S_FALSE | The buffer was too small to contain the resulting URL. |
| E_POINTER | The buffer was too small to contain the resulting URL. See Remarks. |
| INET_E_DEFAULT_ACTION | Use the default action. |
Remarks
When ParseAction is PARSE_UNESCAPE, PARSE_ENCODE, PARSE_ESCAPE, or PARSE_DECODE, CoInternetParseUrl will return E_POINTER if pszResult is too small to hold the result. When ParseAction is PARSE_URL_FROM_PATH, this function will return S_FALSE if pwzUrl does not contain a DOS file path.
The possible values for dwFlags are determined by ParseAction. For example, if PARSE_CANONICALIZE is passed as the ParseAction parameter, the flags that are valid for the UrlCanonicalize function can also be passed to this function to control the parsing operation. The following table lists the parsing actions and related flags.
| ParseAction | Related dwFlags |
|---|---|
| PARSE_CANONICALIZE | UrlCanonicalize |
| PARSE_UNESCAPE, PARSE_ENCODE | UrlUnescape |
| PARSE_ESCAPE, PARSE_DECODE | UrlEscape |
Examples
The following example first canonicalizes the URL, then parses and displays the scheme and fully qualified domain name.
#include <wininet.h>
WCHAR szDecodedUrl[INTERNET_MAX_URL_LENGTH];
DWORD cchDecodedUrl = INTERNET_MAX_URL_LENGTH;
WCHAR szOut[INTERNET_MAX_URL_LENGTH];
HRESULT hr = CoInternetParseUrl(szUrl, PARSE_CANONICALIZE, URL_UNESCAPE, szDecodedUrl,
INTERNET_MAX_URL_LENGTH, &cchDecodedUrl, 0);
if (hr == S_OK)
{
printf("CANONICALIZE: %S\n",szDecodedUrl);
hr = CoInternetParseUrl(szDecodedUrl, PARSE_SCHEMA, 0, szOut,
INTERNET_MAX_URL_LENGTH, &cchDecodedUrl, 0);
if (hr == S_OK)
printf("SCHEME: %S\n", szOut);
else
printf("SCHEME: Error %08x\n", hr);
hr = CoInternetParseUrl(szDecodedUrl, PARSE_DOMAIN, 0, szOut,
INTERNET_MAX_URL_LENGTH, &cchDecodedUrl, 0);
if (hr == S_OK)
printf("DOMAIN: %S\n", szOut);
else
printf("DOMAIN: Error %08x\n", hr);
}
else
printf("CANONICALIZE: Error %08x\n", hr);
Requirements
Minimum supported client |
Windows XP |
Minimum supported server |
Windows 2000 Server |
Product |
Internet Explorer 3.0 |
Header |
Urlmon.h |
Library |
Urlmon.lib |
DLL |
Urlmon.dll |