UrlApplySchemeA function (shlwapi.h)

Determines a scheme for a specified URL string, and returns a string with an appropriate prefix.


LWSTDAPI UrlApplySchemeA(
  [in]      PCSTR pszIn,
  [out]     PSTR  pszOut,
  [in, out] DWORD *pcchOut,
            DWORD dwFlags


[in] pszIn


A null-terminated string of maximum length INTERNET_MAX_URL_LENGTH that contains a URL.

[out] pszOut


A pointer to a buffer that, when this function returns successfully, receives a null-terminated string set to the URL specified by pszIn and converted to the standard scheme://URL_string format.

[in, out] pcchOut

Type: DWORD*

The address of a value set to the number of characters in the pszOut buffer. When the function returns, the value depends on whether the function is successful or returns E_POINTER. For other return values, the value of this parameter is meaningless.



The flags that specify how to determine the scheme. The following flags can be combined.


Apply the default scheme if UrlApplyScheme can't determine one. The default prefix is stored in the registry but is typically "http".


Attempt to determine the scheme by examining pszIn.


Attempt to determine a file URL from pszIn.


Force UrlApplyScheme to determine a scheme for pszIn.

Return value


Returns a standard COM return value, including the following.

Return code Description
A scheme was determined. pszOut points to a string containing the URL with the scheme's prefix. The value of pcchOut is set to the number of characters in the string, not counting the terminating NULL character.
There were no errors, but no prefix was prepended.
The buffer was too small. The value of pcchOut is set to the minimum number of characters that the buffer must be able to contain, including the terminating NULL character.


If the URL has a valid scheme, the string will not be modified. However, almost any combination of two or more characters followed by a colon will be parsed as a scheme. Valid characters include some common punctuation marks, such as ".". If your input string fits this description, UrlApplyScheme may treat it as valid and not apply a scheme. To force the function to apply a scheme to a URL, set the URL_APPLY_FORCEAPPLY and URL_APPLY_DEFAULT flags in dwFlags. This combination of flags forces the function to apply a scheme to the URL. Typically, the function will not be able to determine a valid scheme. The second flag guarantees that, if no valid scheme can be determined, the function will apply the default scheme to the URL.


The shlwapi.h header defines UrlApplyScheme as an alias which 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 not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.


Requirement Value
Minimum supported client Windows 2000 Professional, Windows XP [desktop apps only]
Minimum supported server Windows 2000 Server [desktop apps only]
Target Platform Windows
Header shlwapi.h
Library Shlwapi.lib
DLL Shlwapi.dll (version 5.0 or later)