ParseURLW function (shlwapi.h)

Article
02/22/2024

Performs rudimentary parsing of a URL.

Syntax

LWSTDAPI ParseURLW(
  [in]      LPCWSTR    pcszURL,
  [in, out] PARSEDURLW *ppu
);

Parameters

[in] pcszURL

Type: LPCTSTR

A pointer to a null-terminated string containing the URL to be parsed.

[in, out] ppu

Type: PARSEDURL*

A pointer to a PARSEDURL structure that receives the parsed results. The calling application must set the structure's cbSize member to the size of the structure before calling ParseURL.

Return value

Type: HRESULT

Returns S_OK on success, or a COM error code otherwise. The function returns URL_E_INVALID_SYNTAX (defined in Intshcut.h) if the string could not be parsed as a URL.

Remarks

The parsing performed by ParseURL is fairly rudimentary. For more sophisticated URL parsing, use InternetCrackUrl.

Examples

This sample console application uses ParseURL to parse several simple URLs.

#include <windows.h>
#include <shlwapi.h>
#include <stdio.h>
#include <tchar.h>

void sample(LPCTSTR pcszUrl)
{
    PARSEDURL pu;
    pu.cbSize = sizeof(pu);
    HRESULT hr = ParseURL(pcszUrl, &pu);
    _tprintf(TEXT("ParseURL(%s) returned 0x%08x\n"), pcszUrl, hr);
    if (SUCCEEDED(hr)) {
        _tprintf(TEXT("Protocol = %.*s\n"), pu.cchProtocol, pu.pszProtocol);
        _tprintf(TEXT("Suffix   = %.*s\n"), pu.cchSuffix, pu.pszSuffix);
        _tprintf(TEXT("Scheme   = %d\n"), pu.nScheme);
        _tprintf(TEXT("\n"));
    }
}

int __cdecl main()
{
    sample(TEXT("http://msdn.microsoft.com/vstudio/"));
    sample(TEXT("mailto:someone@example.com"));
    sample(TEXT("file://C:\\AUTOEXEC.BAT"));
    sample(TEXT("C:\\AUTOEXEC.BAT"));
    return 0;
}

Output:

ParseURL(http://msdn.microsoft.com/vstudio/) returned 0x00000000
Protocol = http
Suffix   = //msdn.microsoft.com/vstudio/
Scheme   = 2

ParseURL(mailto:someone@example.com) returned 0x00000000
Protocol = mailto
Suffix   = someone@example.com
Scheme   = 4

ParseURL(file://C:\AUTOEXEC.BAT) returned 0x00000000
Protocol = file
Suffix   = C:\AUTOEXEC.BAT
Scheme   = 9

ParseURL(C:\AUTOEXEC.BAT) returned 0x80041001

Note

The shlwapi.h header defines ParseURL as an alias that automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that is not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement	Value
Minimum supported client	Windows Vista [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	shlwapi.h
DLL	Shlwapi.dll (version 6.0.1 or later)

Share via