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 |