Share via


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

See also

CoInternetParseIUri