Transforms and identifies parts of URLs. Compare to CoInternetParseIUri.

Syntax

STDAPI CoInternetParseUrl(      
    LPCWSTR pwzUrl,
    PARSEACTION ParseAction,
    DWORD dwFlags,
    LPWSTR pszResult,
    DWORD cchResult,
    DWORD *pcchResult,
    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, http://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 disk operating system (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.

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

Example

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);

Function Information

Stock Implementation	urlmon.dll
Custom Implementation	No
Header	Urlmon.h
Import library	Urlmon.lib
Minimum availability	Internet Explorer 3.0
Minimum operating systems	Windows NT 4.0, Windows 95, Windows CE 2.12

See Also

CoInternetParseIUri