Export (0) Print
Expand All
This topic has not yet been rated - Rate this topic

UrlApplyScheme function

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

Syntax


HRESULT UrlApplyScheme(
  _In_     PCTSTR pszIn,
  _Out_    PTSTR pszOut,
  _Inout_  DWORD *pcchOut,
  DWORD dwFlags
);

Parameters

pszIn [in]

Type: PCTSTR

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

pszOut [out]

Type: PTSTR

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.

pcchOut [in, out]

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.

dwFlags

Type: DWORD

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

URL_APPLY_DEFAULT

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

URL_APPLY_GUESSSCHEME

Attempt to determine the scheme by examining pszIn.

URL_APPLY_GUESSFILE

Attempt to determine a file URL from pszIn.

URL_APPLY_FORCEAPPLY

Force UrlApplyScheme to determine a scheme for pszIn.

Return value

Type: HRESULT

Returns a standard COM return value, including the following.

Return codeDescription
S_OK

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.

S_FALSE

There were no errors, but no prefix was prepended.

E_POINTER

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.

 

Remarks

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.

Requirements

Minimum supported client

Windows 2000 Professional, Windows XP [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

Shlwapi.h

Library

Shlwapi.lib

DLL

Shlwapi.dll (version 5.0 or later)

Unicode and ANSI names

UrlApplySchemeW (Unicode) and UrlApplySchemeA (ANSI)

 

 

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.