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.

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.

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

See also

CoInternetParseIUri