CoInternetParseUrl function

Article
07/13/2016

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

Share via