CoInternetParseIUri function

Transforms and identifies parts of URLs. Compare to CoInternetParseUrl.

Syntax

STDAPI CoInternetParseIUri(
  _In_       IUri        *pIUri,
  _In_       PARSEACTION ParseAction,
  _In_       DWORD       dwFlags,
  _In_       LPWSTR      pwzResult,
  _In_       DWORD       cchResult,
  _Out_      DWORD       *pcchResult,
  _Reserved_ DWORD_PTR   dwReserved
);

Parameters

pIUri [in]

The address of an IUri interface to be parsed.

ParseAction [in]

One of the following PARSEACTION values:

(PARSE_CANONICALIZE)

Canonicalize the URL.

(PARSE_FRIENDLY)

Retrieve a URL suitable for display.

(PARSE_ROOTDOCUMENT)

Retrieve the scheme and authority (including user name, password, and port if available) of the URL; for example, https://www.microsoft.com:80/.

(PARSE_DOCUMENT)

Retrieve the portion of the URL prior to the fragment; for example, https://www.microsoft.com:80/path/file.ext.

(PARSE_ENCODE or PARSE_UNESCAPE)

Percent-encode reserved characters in the URL.

(PARSE_DECODE or PARSE_ESCAPE)

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

Retrieve the hostname; for example, www.microsoft.com.

(PARSE_DOMAIN)

Retrieve the top-level domain; for example, microsoft.com.

(PARSE_LOCATION or PARSE_ANCHOR)

Retrieve the URL fragment (named anchor); for example, #top.

dwFlags [in]

A DWORD value that controls the parsing operation, based on the value passed as the ParseAction parameter. For valid flags, see Remarks section.

pwzResult [in]

A pointer to a Unicode string buffer that receives the result of the parsing operation.

cchResult [in]

An unsigned long integer value that contains the size of the buffer in pwzResult, including the terminating NULL character.

pcchResult [out]

The address of a DWORD value that receives the number of characters returned in pwzResult. Count does not include the terminating NULL character.

dwReserved [in]

Reserved. Must be set to 0.

Return value

Returns one of the following values.

Return code Description
S_OK

Success.

S_FALSE

The buffer is too small to contain the resulting URL.

INET_E_DEFAULT_ACTION

Use the default action.

E_INVALID_ARG

Missing input arguments or incompatible dwFlags and ParseAction.

E_FAIL

Used for compatibility with CoInternetParseUrl behavior for some ParseAction requests.

 

Remarks

Much of the functionality of the string-based CoInternetParseUrl function is not necessary with a preparsed IUri object. Encode operations and decode operations are discouraged because an IUri stores its data in a normalized (canonical) form.

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

 

Requirements

Minimum supported client

Windows XP with SP2

Minimum supported server

Windows Server 2003 with SP1

Product

Internet Explorer 7

Header

Urlmon.h

Library

Urlmon.lib

DLL

Urlmon.dll

See also

CoInternetParseUrl