using System;
using System.Runtime.InteropServices;
using System.Text;
namespace Vanara.PInvoke
{
public static partial class ShlwApi
{
/// The flags that specify how to determine the scheme.
[PInvokeData("shlwapi.h", MSDNShortId = "af60643e-b1a4-4013-b116-dd9fad4e90bf")]
[Flags]
public enum URL_APPLY
{
///
/// Apply the default scheme if UrlApplyScheme can't determine one. The default prefix is stored in the registry but is
/// typically "http".
///
URL_APPLY_DEFAULT = 0x01,
/// Attempt to determine the scheme by examining pszIn.
URL_APPLY_GUESSSCHEME = 0x02,
/// Attempt to determine a file URL from pszIn.
URL_APPLY_GUESSFILE = 0x04,
/// Force UrlApplyScheme to determine a scheme for pszIn.
URL_APPLY_FORCEAPPLY = 0x08,
}
///
/// Used to specify URL schemes.
///
// https://docs.microsoft.com/en-us/windows/desktop/api/shlwapi/ne-shlwapi-url_scheme typedef enum URL_SCHEME { URL_SCHEME_INVALID ,
// URL_SCHEME_UNKNOWN , URL_SCHEME_FTP , URL_SCHEME_HTTP , URL_SCHEME_GOPHER , URL_SCHEME_MAILTO , URL_SCHEME_NEWS , URL_SCHEME_NNTP
// , URL_SCHEME_TELNET , URL_SCHEME_WAIS , URL_SCHEME_FILE , URL_SCHEME_MK , URL_SCHEME_HTTPS , URL_SCHEME_SHELL , URL_SCHEME_SNEWS ,
// URL_SCHEME_LOCAL , URL_SCHEME_JAVASCRIPT , URL_SCHEME_VBSCRIPT , URL_SCHEME_ABOUT , URL_SCHEME_RES , URL_SCHEME_MSSHELLROOTED ,
// URL_SCHEME_MSSHELLIDLIST , URL_SCHEME_MSHELP , URL_SCHEME_MSSHELLDEVICE , URL_SCHEME_WILDCARD , URL_SCHEME_SEARCH_MS ,
// URL_SCHEME_SEARCH , URL_SCHEME_KNOWNFOLDER , URL_SCHEME_MAXVALUE } ;
[PInvokeData("shlwapi.h", MSDNShortId = "45686920-356d-4dd7-8482-2427854a92ed")]
public enum URL_SCHEME
{
/// An invalid scheme.
URL_SCHEME_INVALID = -1,
/// An unknown scheme.
URL_SCHEME_UNKNOWN = 0,
/// FTP (ftp:).
URL_SCHEME_FTP,
/// HTTP (http:).
URL_SCHEME_HTTP,
/// Gopher (gopher:).
URL_SCHEME_GOPHER,
/// Mail-to (mailto:).
URL_SCHEME_MAILTO,
/// Usenet news (news:).
URL_SCHEME_NEWS,
/// Usenet news with NNTP (nntp:).
URL_SCHEME_NNTP,
/// Telnet (telnet:).
URL_SCHEME_TELNET,
/// Wide Area Information Server (wais:).
URL_SCHEME_WAIS,
/// File (file:).
URL_SCHEME_FILE,
/// URL moniker (mk:).
URL_SCHEME_MK,
/// URL HTTPS (https:).
URL_SCHEME_HTTPS,
/// Shell (shell:).
URL_SCHEME_SHELL,
/// NNTP news postings with SSL (snews:).
URL_SCHEME_SNEWS,
/// Local (local:).
URL_SCHEME_LOCAL,
/// JavaScript (javascript:).
URL_SCHEME_JAVASCRIPT,
/// VBScript (vbscript:).
URL_SCHEME_VBSCRIPT,
/// About (about:).
URL_SCHEME_ABOUT,
/// Res (res:).
URL_SCHEME_RES,
/// Internet Explorer 6 and later only. Shell-rooted (ms-shell-rooted:)
URL_SCHEME_MSSHELLROOTED,
/// Internet Explorer 6 and later only. Shell ID-list (ms-shell-idlist:).
URL_SCHEME_MSSHELLIDLIST,
/// Internet Explorer 6 and later only. MSHelp (hcp:).
URL_SCHEME_MSHELP,
/// Not supported.
URL_SCHEME_MSSHELLDEVICE,
/// Internet Explorer 7 and later only. Wildcard (*:).
URL_SCHEME_WILDCARD,
/// Windows Vista and later only. Search-MS (search-ms:).
URL_SCHEME_SEARCH_MS,
/// Windows Vista with SP1 and later only. Search (search:).
URL_SCHEME_SEARCH,
/// Windows 7 and later. Known folder (knownfolder:).
URL_SCHEME_KNOWNFOLDER,
/// The highest legitimate value in the enumeration, used for validation purposes.
URL_SCHEME_MAXVALUE,
}
/// The flags that specify how the URL is converted to canonical form.
[PInvokeData("shlwapi.h", MSDNShortId = "70802745-0611-4d37-800e-b50d5ea23426")]
[Flags]
public enum URLFLAGS : uint
{
///
/// Un-escape any escape sequences that the URLs contain, with two exceptions. The escape sequences for "?" and "#" are not
/// un-escaped. If one of the URL_ESCAPE_XXX flags is also set, the two URLs are first un-escaped, then combined, then escaped.
///
URL_UNESCAPE = 0x10000000,
///
/// Replace unsafe characters with their escape sequences. Unsafe characters are those characters that may be altered
/// during transport across the Internet, and include the (<, >, ", #, {, }, |, , ^, [, ], and ') characters. This flag applies
/// to all URLs, including opaque URLs.
///
URL_ESCAPE_UNSAFE = 0x20000000,
///
/// Combine URLs with client-defined pluggable protocols, according to the W3C specification. This flag does not apply to
/// standard protocols such as ftp, http, gopher, and so on. If this flag is set, UrlCombine does not simplify URLs, so there is
/// no need to also set URL_DONT_SIMPLIFY.
///
URL_PLUGGABLE_PROTOCOL = 0x40000000,
/// Undocumented.
URL_WININET_COMPATIBILITY = 0x80000000,
///
/// Used only in conjunction with URL_ESCAPE_SPACES_ONLY to prevent the conversion of characters in the query (the portion of the
/// URL following the first # or ? character encountered in the string). This flag should not be used alone, nor combined with URL_ESCAPE_SEGMENT_ONLY.
///
URL_DONT_ESCAPE_EXTRA_INFO = 0x02000000,
/// Defined to be the same as URL_DONT_ESCAPE_EXTRA_INFO.
URL_DONT_UNESCAPE_EXTRA_INFO = URL_DONT_ESCAPE_EXTRA_INFO,
/// Defined to be the same as URL_DONT_ESCAPE_EXTRA_INFO.
URL_BROWSER_MODE = URL_DONT_ESCAPE_EXTRA_INFO,
///
/// Convert only space characters to their escape sequences, including those space characters in the query portion of the URL.
/// Other unsafe characters are not converted to their escape sequences. This flag assumes that pszURL does not contain a full
/// URL. It expects only the portions following the server specification.
///
/// Combine this flag with URL_DONT_ESCAPE_EXTRA_INFO to prevent the conversion of space characters in the query portion of the URL.
///
/// This flag cannot be combined with URL_ESCAPE_PERCENT or URL_ESCAPE_SEGMENT_ONLY.
///
URL_ESCAPE_SPACES_ONLY = 0x04000000,
///
/// Treat "/./" and "/../" in a URL string as literal characters, not as shorthand for navigation. See Remarks for further discussion.
///
URL_DONT_SIMPLIFY = 0x08000000,
/// Defined to be the same as URL_DONT_SIMPLIFY.
URL_NO_META = URL_DONT_SIMPLIFY,
/// Converts escape sequences back into ordinary characters and overwrites the original string.
URL_UNESCAPE_INPLACE = 0x00100000,
/// Undocumented.
URL_CONVERT_IF_DOSPATH = 0x00200000,
/// Undocumented.
URL_UNESCAPE_HIGH_ANSI_ONLY = 0x00400000,
/// Undocumented.
URL_INTERNAL_PATH = 0x00800000,
/// Use DOS path compatibility mode to create "file" URIs.
URL_FILE_USE_PATHURL = 0x00010000,
/// Undocumented.
URL_DONT_UNESCAPE = 0x00020000,
/// Windows 7 and later. Percent-encode all non-ASCII characters as their UTF-8 equivalents.
URL_ESCAPE_AS_UTF8 = 0x00040000,
/// Windows 7 and later. Percent-unencode all non-ASCII characters as their UTF-8 equivalents.
URL_UNESCAPE_AS_UTF8 = URL_ESCAPE_AS_UTF8,
/// Windows 8 and later. Percent-encode all ASCII characters outside of the unreserved set from URI RFC 3986 (a-zA-Z0-9-.~_).
URL_ESCAPE_ASCII_URI_COMPONENT = 0x00080000,
/// Undocumented.
URL_ESCAPE_URI_COMPONENT = (URL_ESCAPE_ASCII_URI_COMPONENT | URL_ESCAPE_AS_UTF8),
/// Undocumented.
URL_UNESCAPE_URI_COMPONENT = URL_UNESCAPE_AS_UTF8,
///
/// Convert any % character found in the segment section of the URL (that section falling between the server specification and
/// the first # or ? character). By default, the % character is not converted to its escape sequence. Other unsafe characters in
/// the segment are also converted normally.
///
/// Combining this flag with URL_ESCAPE_SEGMENT_ONLY includes those % characters in the query portion of the URL. However, as the
/// URL_ESCAPE_SEGMENT_ONLY flag causes the entire string to be considered the segment, any # or ? characters are also converted.
///
/// This flag cannot be combined with URL_ESCAPE_SPACES_ONLY.
///
URL_ESCAPE_PERCENT = 0x00001000,
///
/// Indicates that pszURL contains only that section of the URL following the server component but preceding the query. All
/// unsafe characters in the string are converted. If a full URL is provided when this flag is set, all unsafe characters in the
/// entire string are converted, including # and ? characters.
/// Combine this flag with URL_ESCAPE_PERCENT to include that character in the conversion.
/// This flag cannot be combined with URL_ESCAPE_SPACES_ONLY or URL_DONT_ESCAPE_EXTRA_INFO.
///
URL_ESCAPE_SEGMENT_ONLY = 0x00002000,
}
/// The type of URL to be tested for. This parameter can take one of the following values.
[PInvokeData("shlwapi.h", MSDNShortId = "2e83c953-b4c5-4411-90ca-49ffb94ee374")]
public enum URLIS
{
/// Is the URL valid?
URLIS_URL,
/// Is the URL opaque?
URLIS_OPAQUE,
/// Is the URL a URL that is not typically tracked in navigation history?
URLIS_NOHISTORY,
/// Is the URL a file URL?
URLIS_FILEURL,
/// Attempt to determine a valid scheme for the URL.
URLIS_APPLIABLE,
/// Does the URL string end with a directory?
URLIS_DIRECTORY,
/// Does the URL have an appended query string?
URLIS_HASQUERY,
}
///
/// Performs rudimentary parsing of a URL.
///
///
/// TBD
///
///
/// 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.
///
///
///
/// 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.
///
///
///
/// 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.
///
// https://docs.microsoft.com/en-us/windows/desktop/api/shlwapi/nf-shlwapi-parseurla LWSTDAPI ParseURLA( LPCSTR pcszURL, PARSEDURLA
// *ppu );
[DllImport(Lib.Shlwapi, SetLastError = false, CharSet = CharSet.Auto)]
[PInvokeData("shlwapi.h", MSDNShortId = "3d42dad0-b9eb-4e40-afc8-68cb85b27504")]
public static extern HRESULT ParseURL(string pcszURL, ref PARSEDURL ppu);
///
/// Determines a scheme for a specified URL string, and returns a string with an appropriate prefix.
///
///
/// Type: PCTSTR
/// A null-terminated string of maximum length INTERNET_MAX_URL_LENGTH that contains a URL.
///
///
/// 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.
///
///
///
/// 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.
///
///
///
/// 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.
///
///
/// Type: HRESULT
/// Returns a standard COM return value, including the following.
///
///
/// Return code
/// Description
///
/// -
/// 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.
///
///
///
///
///
///
/// 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.
///
///
// https://docs.microsoft.com/en-us/windows/desktop/api/shlwapi/nf-shlwapi-urlapplyschemea LWSTDAPI UrlApplySchemeA( PCSTR pszIn,
// PSTR pszOut, DWORD *pcchOut, DWORD dwFlags );
[DllImport(Lib.Shlwapi, SetLastError = false, CharSet = CharSet.Auto)]
[PInvokeData("shlwapi.h", MSDNShortId = "af60643e-b1a4-4013-b116-dd9fad4e90bf")]
public static extern HRESULT UrlApplyScheme(string pszIn, StringBuilder pszOut, ref uint pcchOut, URL_APPLY dwFlags);
///
/// Converts a URL string into canonical form.
///
///
/// Type: PCTSTR
///
/// A pointer to a null-terminated string of maximum length INTERNET_MAX_URL_LENGTH that contains a URL string. If the string does
/// not refer to a file, it must include a valid scheme such as "http://".
///
///
///
/// Type: PTSTR
/// A pointer to a buffer that, when this function returns successfully, receives the converted URL as a null-terminated string.
///
///
/// Type: DWORD*
/// A pointer to a value that, on entry, is set to the number of characters in the pszCanonicalized buffer.
///
///
/// Type: DWORD
/// The flags that specify how the URL is converted to canonical form. The following flags can be combined.
/// URL_UNESCAPE (0x10000000)
///
/// Un-escape any escape sequences that the URLs contain, with two exceptions. The escape sequences for "?" and "#" are not
/// un-escaped. If one of the URL_ESCAPE_XXX flags is also set, the two URLs are first un-escaped, then combined, then escaped.
///
/// URL_ESCAPE_UNSAFE (0x20000000)
///
/// Replace unsafe characters with their escape sequences. Unsafe characters are those characters that may be altered during
/// transport across the Internet, and include the (<, >, ", #, {, }, |, , ^, [, ], and ') characters. This flag applies to all
/// URLs, including opaque URLs.
///
/// URL_PLUGGABLE_PROTOCOL (0x40000000)
///
/// Combine URLs with client-defined pluggable protocols, according to the W3C specification. This flag does not apply to standard
/// protocols such as ftp, http, gopher, and so on. If this flag is set, UrlCombine does not simplify URLs, so there is no need to
/// also set URL_DONT_SIMPLIFY.
///
/// URL_ESCAPE_SPACES_ONLY (0x04000000)
///
/// Replace only spaces with escape sequences. This flag takes precedence over URL_ESCAPE_UNSAFE, but does not apply to opaque URLs.
///
/// URL_DONT_SIMPLIFY (0x08000000)
///
/// Treat "/./" and "/../" in a URL string as literal characters, not as shorthand for navigation. See Remarks for further discussion.
///
/// URL_NO_META (0x08000000)
/// Defined to be the same as URL_DONT_SIMPLIFY.
/// URL_ESCAPE_PERCENT (0x00001000)
/// Convert any occurrence of "%" to its escape sequence.
/// URL_ESCAPE_AS_UTF8 (0x00040000)
/// Windows 7 and later. Percent-encode all non-ASCII characters as their UTF-8 equivalents.
///
///
/// Type: HRESULT
/// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.
///
///
///
/// This function performs such tasks as replacing unsafe characters with their escape sequences and collapsing sequences like ".....".
///
///
/// If a URL string contains "/../" or "/./", UrlCanonicalize treats the characters as indicating navigation in the URL
/// hierarchy. The function simplifies the URLs before combining them. For instance "/hello/cruel/../world" is simplified to
/// "/hello/world". Exceptions to this default behavior occur in these cases:
///
///
/// -
///
/// If the URL_DONT_SIMPLIFY flag is set in dwFlags, the function does not simplify URLs. In this case,
/// "/hello/cruel/../world" is left as it is.
///
///
/// -
///
/// If "/../" or "/./" is the first segment in the path (for example, "http://domain/../path1/path2/file.htm"),
/// UrlCanonicalize outputs the path exactly as it was input.
///
///
///
///
// https://docs.microsoft.com/en-us/windows/desktop/api/shlwapi/nf-shlwapi-urlcanonicalizea LWSTDAPI UrlCanonicalizeA( PCSTR pszUrl,
// PSTR pszCanonicalized, DWORD *pcchCanonicalized, DWORD dwFlags );
[DllImport(Lib.Shlwapi, SetLastError = false, CharSet = CharSet.Auto)]
[PInvokeData("shlwapi.h", MSDNShortId = "70802745-0611-4d37-800e-b50d5ea23426")]
public static extern HRESULT UrlCanonicalize(string pszUrl, StringBuilder pszCanonicalized, ref uint pcchCanonicalized, URLFLAGS dwFlags);
///
/// When provided with a relative URL and its base, returns a URL in canonical form.
///
///
/// Type: PCTSTR
/// A pointer to a null-terminated string of maximum length INTERNET_MAX_URL_LENGTH that contains the base URL.
///
///
/// Type: PCTSTR
/// A pointer to a null-terminated string of maximum length INTERNET_MAX_URL_LENGTH that contains the relative URL.
///
///
/// Type: PTSTR
///
/// A pointer to a buffer that, when this function returns successfully, receives a null-terminated string that contains the combined URL.
///
///
///
/// Type: DWORD*
///
/// A pointer to a value that, on entry, is set to the number of characters in the pszCombined buffer. When the function returns
/// successfully, the value depends on whether the function is successful or returns E_POINTER. For other return values, the value of
/// this parameter is meaningless.
///
///
///
/// Type: DWORD
/// Flags that specify how the URL is converted to canonical form. The following flags can be combined.
/// URL_DONT_SIMPLIFY (0x08000000)
///
/// Treat '/./' and '/../' in a URL string as literal characters, not as shorthand for navigation. See Remarks for further discussion.
///
/// URL_ESCAPE_PERCENT (0x00001000)
/// Convert any occurrence of '%' to its escape sequence.
/// URL_ESCAPE_SPACES_ONLY (0x04000000)
///
/// Replace only spaces with escape sequences. This flag takes precedence over URL_ESCAPE_UNSAFE, but does not apply to opaque URLs.
///
/// URL_ESCAPE_UNSAFE (0x20000000)
///
/// Replace unsafe characters with their escape sequences. Unsafe characters are those characters that may be altered during
/// transport across the Internet, and include the (<, >, ", #, {, }, |, , ^, ~, [, ], and ') characters. This flag applies to
/// all URLs, including opaque URLs.
///
/// URL_NO_META
/// Defined to be the same as URL_DONT_SIMPLIFY.
/// URL_PLUGGABLE_PROTOCOL (0x40000000)
///
/// Combine URLs with client-defined pluggable protocols, according to the W3C specification. This flag does not apply to standard
/// protocols such as ftp, http, gopher, and so on. If this flag is set, UrlCombine does not simplify URLs, so there is no
/// need to also set URL_DONT_SIMPLIFY.
///
/// URL_UNESCAPE (0x10000000)
///
/// Un-escape any escape sequences that the URLs contain, with two exceptions. The escape sequences for '?' and '#' are not
/// un-escaped. If one of the URL_ESCAPE_XXX flags is also set, the two URLs are first un-escaped, then combined, then escaped.
///
/// URL_ESCAPE_AS_UTF8 (0x00040000)
/// Windows 7 and later. Percent-encode all non-ASCII characters as their UTF-8 equivalents.
///
///
/// Type: HRESULT
/// Returns standard COM error codes, including the following.
///
///
/// Return code
/// Description
///
/// -
/// S_OK
///
/// pszCombined points to a string that contains the combined URLs. The value of pcchCombined is set to the number of characters in
/// the string, not counting the terminating NULL character.
///
///
/// -
/// E_POINTER
///
/// The buffer was too small. The value of pcchCombined is set to the minimum number of characters that the buffer must be able to
/// contain, including the terminating NULL character.
///
///
///
///
///
///
/// Items between slashes are treated as hierarchical identifiers; the last item specifies the document itself. You must enter a
/// slash (/) after the document name to append more items; otherwise, UrlCombine exchanges one document for another. For example:
///
///
/// The preceding code returns the URL http://xyz/test/bar. If you want the combined URL to be http://xyz/test/abc/bar, use the
/// following call to UrlCombine.
///
///
/// If a URL string contains '/../' or '/./', UrlCombine usually treats the characters as if they indicated navigation in the
/// URL hierarchy. The function simplifies the URLs before combining them. For instance, "/hello/cruel/../world" is simplified to
/// "/hello/world". If the URL_DONT_SIMPLIFY flag is set in dwFlags, the function does not simplify URLs. In this case,
/// "/hello/cruel/../world" is left as it is.
///
///
// https://docs.microsoft.com/en-us/windows/desktop/api/shlwapi/nf-shlwapi-urlcombinea LWSTDAPI UrlCombineA( PCSTR pszBase, PCSTR
// pszRelative, PSTR pszCombined, DWORD *pcchCombined, DWORD dwFlags );
[DllImport(Lib.Shlwapi, SetLastError = false, CharSet = CharSet.Auto)]
[PInvokeData("shlwapi.h", MSDNShortId = "f574d365-1ab9-4de4-84fe-17820c327ccf")]
public static extern HRESULT UrlCombine(string pszBase, string pszRelative, StringBuilder pszCombined, ref uint pcchCombined, URLFLAGS dwFlags);
///
/// Makes a case-sensitive comparison of two URL strings.
///
///
/// Type: PCTSTR
/// A null-terminated string of maximum length INTERNET_MAX_URL_LENGTH that contains the first URL.
///
///
/// Type: PCTSTR
/// A null-terminated string of maximum length INTERNET_MAX_URL_LENGTH that contains the second URL.
///
///
/// Type: BOOL
/// A value that is set to TRUE to have UrlCompare ignore a trailing '/' character on either or both URLs.
///
///
/// Type: int
///
/// Returns zero if the two strings are equal. The function will also return zero if fIgnoreSlash is set to TRUE and one of
/// the strings has a trailing '' character. The function returns a negative integer if the string pointed to by psz1 is less than
/// the string pointed to by psz2. Otherwise, it returns a positive integer.
///
///
///
///
/// For best results, you should first canonicalize the URLs with UrlCanonicalize. Then, compare the canonicalized URLs with UrlCompare.
///
///
// https://docs.microsoft.com/en-us/windows/desktop/api/shlwapi/nf-shlwapi-urlcomparea int UrlCompareA( PCSTR psz1, PCSTR psz2, BOOL
// fIgnoreSlash );
[DllImport(Lib.Shlwapi, SetLastError = false, CharSet = CharSet.Auto)]
[PInvokeData("shlwapi.h", MSDNShortId = "d5c9e003-b85b-4f9f-b231-e3e4b71d4ce6")]
public static extern int UrlCompare(string psz1, string psz2, [MarshalAs(UnmanagedType.Bool)] bool fIgnoreSlash);
///
/// Converts a Microsoft MS-DOS path to a canonicalized URL.
///
///
/// Type: PCTSTR
/// A null-terminated string of maximum length INTERNET_MAX_URL_LENGTH that contains the MS-DOS path.
///
///
/// Type: PTSTR
/// A pointer to a buffer that, when this function returns successfully, receives the URL.
///
///
/// Type: DWORD*
/// The number of characters in pszUrl.
///
///
/// Type: DWORD
/// Reserved. Set this parameter to NULL.
///
///
/// Type: HRESULT
///
/// Returns S_FALSE if pszPath is already in URL format. In this case, pszPath will simply be copied to pszUrl. Otherwise, it returns
/// S_OK if successful or a standard COM error value if not.
///
///
///
///
/// NoteUrlCreateFromPath does not support extended paths. These are paths that include the extended-length path prefix "\\?\".
///
///
// https://docs.microsoft.com/en-us/windows/desktop/api/shlwapi/nf-shlwapi-urlcreatefrompatha LWSTDAPI UrlCreateFromPathA( PCSTR
// pszPath, PSTR pszUrl, DWORD *pcchUrl, DWORD dwFlags );
[DllImport(Lib.Shlwapi, SetLastError = false, CharSet = CharSet.Auto)]
[PInvokeData("shlwapi.h", MSDNShortId = "b69ab203-daab-4951-b3b9-c5ca37c532b3")]
public static extern HRESULT UrlCreateFromPath(string pszPath, StringBuilder pszUrl, ref uint pcchUrl, uint dwFlags = 0);
///
///
/// Converts characters or surrogate pairs in a URL that might be altered during transport across the Internet ("unsafe" characters)
/// into their corresponding escape sequences. Surrogate pairs are characters between U+10000 to U+10FFFF (in UTF-32) or between DC00
/// to DFFF (in UTF-16).
///
///
///
/// Type: PCTSTR
///
/// A null-terminated string of maximum length INTERNET_MAX_URL_LENGTH that contains a full or partial URL, as appropriate for
/// the value in dwFlags.
///
///
///
/// Type: PTSTR
/// The buffer that receives the converted string, with the unsafe characters converted to their escape sequences.
///
///
/// Type: DWORD*
///
/// A pointer to a DWORD value that, on entry, contains the number of characters in the pszEscaped buffer. Before calling
/// UrlEscape, the calling application must set the value referenced by pcchEscaped to the size of the buffer. When this
/// function returns successfully, the value receives the number of characters written to the buffer, not including the terminating
/// NULL character.
///
///
/// If an E_POINTER error code is returned, the buffer was too small to hold the result, and the value referenced by pcchEscaped is
/// set to the required number of characters in the buffer. If any other errors are returned, the value referenced by pcchEscaped is undefined.
///
///
///
/// Type: DWORD
///
/// The flags that indicate which portion of the URL is being provided in pszURL and which characters in that string should be
/// converted to their escape sequences. The following flags are defined.
///
/// URL_DONT_ESCAPE_EXTRA_INFO (0x02000000)
///
/// Used only in conjunction with URL_ESCAPE_SPACES_ONLY to prevent the conversion of characters in the query (the portion of
/// the URL following the first # or ? character encountered in the string). This flag should not be used alone, nor combined with URL_ESCAPE_SEGMENT_ONLY.
///
/// URL_BROWSER_MODE
/// Defined to be the same as URL_DONT_ESCAPE_EXTRA_INFO.
/// URL_ESCAPE_SPACES_ONLY (0x04000000)
///
/// Convert only space characters to their escape sequences, including those space characters in the query portion of the URL. Other
/// unsafe characters are not converted to their escape sequences. This flag assumes that pszURL does not contain a full URL. It
/// expects only the portions following the server specification.
///
///
/// Combine this flag with URL_DONT_ESCAPE_EXTRA_INFO to prevent the conversion of space characters in the query portion of
/// the URL.
///
/// This flag cannot be combined with URL_ESCAPE_PERCENT or URL_ESCAPE_SEGMENT_ONLY.
/// URL_ESCAPE_PERCENT (0x00001000)
///
/// Convert any % character found in the segment section of the URL (that section falling between the server specification and the
/// first # or ? character). By default, the % character is not converted to its escape sequence. Other unsafe characters in the
/// segment are also converted normally.
///
///
/// Combining this flag with URL_ESCAPE_SEGMENT_ONLY includes those % characters in the query portion of the URL. However, as
/// the URL_ESCAPE_SEGMENT_ONLY flag causes the entire string to be considered the segment, any # or ? characters are also converted.
///
/// This flag cannot be combined with URL_ESCAPE_SPACES_ONLY.
/// URL_ESCAPE_SEGMENT_ONLY (0x00002000)
///
/// Indicates that pszURL contains only that section of the URL following the server component but preceding the query. All unsafe
/// characters in the string are converted. If a full URL is provided when this flag is set, all unsafe characters in the entire
/// string are converted, including # and ? characters.
///
/// Combine this flag with URL_ESCAPE_PERCENT to include that character in the conversion.
/// This flag cannot be combined with URL_ESCAPE_SPACES_ONLY or URL_DONT_ESCAPE_EXTRA_INFO.
/// URL_ESCAPE_AS_UTF8 (0x00040000)
/// Windows 7 and later. Percent-encode all non-ASCII characters as their UTF-8 equivalents.
/// URL_ESCAPE_ASCII_URI_COMPONENT (0x00080000)
/// Windows 8 and later. Percent-encode all ASCII characters outside of the unreserved set from URI RFC 3986 (a-zA-Z0-9-.~_).
///
///
/// Type: HRESULT
///
/// Returns S_OK if successful. If the pcchEscaped buffer was too small to contain the result, E_POINTER is returned, and the value
/// pointed to by pcchEscaped is set to the required buffer size. Otherwise, a standard error value is returned.
///
///
///
///
/// For the purposes of this document, a typical URL is divided into three sections: the server, the segment, and the query. For example:
///
/// The server portion is "http://microsoft.com/". The trailing forward slash is considered part of the server portion.
///
/// The segment portion is any part of the path found following the server portion, but before the first # or ? character, in this
/// case simply "test.asp".
///
///
/// The query portion is the remainder of the path from the first # or ? character (inclusive) to the end. In the example, it is "?url=/example/abc.asp?frame=true#fragment".
///
///
/// Unsafe characters are those characters that might be altered during transport across the Internet. This function converts unsafe
/// characters into their equivalent "%xy" escape sequences. The following table shows unsafe characters and their escape sequences.
///
///
///
/// Character
/// Escape Sequence
///
/// -
/// ^
/// %5E
///
/// -
/// &
/// %26
///
/// -
/// `
/// %60
///
/// -
/// {
/// %7B
///
/// -
/// }
/// %7D
///
/// -
/// |
/// %7C
///
/// -
/// ]
/// %5D
///
/// -
/// [
/// %5B
///
/// -
/// "
/// %22
///
/// -
/// <
/// %3C
///
/// -
/// >
/// %3E
///
/// -
/// \
/// %5C
///
///
/// Use of the URL_ESCAPE_SEGMENT_ONLY flag also causes the conversion of the # (%23), ? (%3F), and / (%2F) characters.
///
/// By default, UrlEscape ignores any text following a # or ? character. The URL_ESCAPE_SEGMENT_ONLY flag overrides
/// this behavior by regarding the entire string as the segment. The URL_ESCAPE_SPACES_ONLY flag overrides this behavior, but
/// only for space characters.
///
/// Examples
///
/// The following examples show the effect of the various flags on a URL. The example URL is not valid but is exaggerated for
/// demonstration purposes.
///
///
// https://docs.microsoft.com/en-us/windows/desktop/api/shlwapi/nf-shlwapi-urlescapea LWSTDAPI UrlEscapeA( PCSTR pszUrl, PSTR
// pszEscaped, DWORD *pcchEscaped, DWORD dwFlags );
[DllImport(Lib.Shlwapi, SetLastError = false, CharSet = CharSet.Auto)]
[PInvokeData("shlwapi.h", MSDNShortId = "52ee1501-2cd4-4193-8363-0af91673ec88")]
public static extern HRESULT UrlEscape(string pszUrl, StringBuilder pszEscaped, ref uint pcchEscaped, URLFLAGS dwFlags);
///
///
/// [ UrlFixupW is available for use in the operating systems specified in the Requirements section. It may be altered or
/// unavailable in subsequent versions.]
///
/// Attempts to correct a URL whose protocol identifier is incorrect. For example, will be changed to .
///
///
/// Type: PCWSTR
///
/// A pointer to a null-terminated string that contains the URL to be corrected. This string must not exceed
/// INTERNET_MAX_PATH_LENGTH characters in length, including the terminating NULL character.
///
///
///
/// Type: PWSTR
///
/// A pointer to a buffer that, when this function returns successfully, receives the copied characters. The buffer must be large
/// enough to contain the number of WCHAR characters specified by the cchMax parameter, including the terminating NULL
/// character. This parameter can be equal to the pcszUrl parameter to correct a URL in place. If pszTranslatedUrl is not equal to
/// pcszUrl, the buffer pointed to by pszTranslatedUrl must not overlap the buffer pointed to by pcszUrl.
///
///
///
/// Type: DWORD
///
/// The number of WCHAR characters that can be contained in the buffer pointed to by pszTranslatedUrl. This parameter must be
/// greater than zero.
///
///
///
/// Type: HRESULT
///
/// Returns S_OK if the proposed URL was already acceptable or was successfully corrected. The pszTranslatedUrl buffer contains the
/// corrected URL, or the original URL if no correction was needed. Returns S_FALSE if the proposed URL could not be recognized
/// sufficiently to be corrected. Otherwise, returns a standard COM error code.
///
///
///
/// The UrlFixup function recognizes the schemes specified by the URL_SCHEME enumeration.
/// Priority is given to the first character in the protocol identifier section so will be converted to instead of .
///
/// Note Do not use this function for deterministic data transformation. The heuristics used by UrlFixupW can change
/// from one release to the next. The function should only be used to correct possibly invalid user input.
///
/// This function is available only in a Unicode version.
/// Examples
///
/// This example shows how to use UrlFixupW. Notice that the last four autocorrections were probably not what the user
/// intended and demonstrate limitations of the heuristic used by the function.
///
///
// https://docs.microsoft.com/en-us/windows/desktop/api/shlwapi/nf-shlwapi-urlfixupw LWSTDAPI UrlFixupW( PCWSTR pcszUrl, PWSTR
// pszTranslatedUrl, DWORD cchMax );
[DllImport(Lib.Shlwapi, SetLastError = false, ExactSpelling = true, CharSet = CharSet.Unicode)]
[PInvokeData("shlwapi.h", MSDNShortId = "3750d027-847f-4f33-851d-a10be7562bcb")]
public static extern HRESULT UrlFixupW(string pcszUrl, StringBuilder pszTranslatedUrl, uint cchMax);
///
/// Retrieves the location from a URL.
///
///
/// Type: PCTSTR
/// A null-terminated string of maximum length INTERNET_MAX_URL_LENGTH that contains the location.
///
///
/// Type: LPCTSTR
/// Returns a pointer to a null-terminated string with the location, or NULL otherwise.
///
///
///
/// The location is the segment of the URL starting with a ? or # character. If a file URL has a query string, the returned string
/// includes the query string.
///
///
// https://docs.microsoft.com/en-us/windows/desktop/api/shlwapi/nf-shlwapi-urlgetlocationa LPCSTR UrlGetLocationA( PCSTR pszURL );
[DllImport(Lib.Shlwapi, SetLastError = false, CharSet = CharSet.Auto)]
[PInvokeData("shlwapi.h", MSDNShortId = "e75bde92-2ca0-4d34-a276-50b4eeceda1c")]
public static extern IntPtr UrlGetLocation(string pszURL);
///
/// Accepts a URL string and returns a specified part of that URL.
///
///
/// Type: PCTSTR
/// A null-terminated string of maximum length INTERNET_MAX_URL_LENGTH that contains the URL.
///
///
/// Type: PTSTR
///
/// A pointer to a buffer that, when this function returns successfully, receives a null-terminated string with the specified part of
/// the URL.
///
///
///
/// Type: DWORD*
///
/// A pointer to a value that, on entry, is set to the number of characters in the pszOut buffer. When this function returns
/// successfully, the value depends on whether the function is successful or returns E_POINTER. For other return values, the value of
/// this parameter is meaningless.
///
///
///
/// Type: DWORD
/// The flags that specify which part of the URL to retrieve. It can have one of the following values.
/// URL_PART_HOSTNAME
/// The host name.
/// URL_PART_PASSWORD
/// The password.
/// URL_PART_PORT
/// The port number.
/// URL_PART_QUERY
/// The query portion of the URL.
/// URL_PART_SCHEME
/// The URL scheme.
/// URL_PART_USERNAME
/// The username.
///
///
/// Type: DWORD
/// A flag that can be set to keep the URL scheme, in addition to the part that is specified by dwPart.
/// URL_PARTFLAG_KEEPSCHEME (0x01)
/// Keep the URL scheme.
///
///
/// Type: HRESULT
///
/// Returns S_OK if successful. The value pointed to by pcchOut will be set to the number of characters written to the output buffer,
/// excluding the terminating NULL. If the buffer was too small, E_POINTER is returned, and the value pointed to by pcchOut
/// will be set to the minimum number of characters that the buffer must be able to contain, including the terminating NULL
/// character. Otherwise, a COM error value is returned.
///
///
// https://docs.microsoft.com/en-us/windows/desktop/api/shlwapi/nf-shlwapi-urlgetparta LWSTDAPI UrlGetPartA( PCSTR pszIn, PSTR
// pszOut, DWORD *pcchOut, DWORD dwPart, DWORD dwFlags );
[DllImport(Lib.Shlwapi, SetLastError = false, CharSet = CharSet.Auto)]
[PInvokeData("shlwapi.h", MSDNShortId = "5f43dedd-c543-46b2-b90e-f0af576d2605")]
public static extern HRESULT UrlGetPart(string pszIn, StringBuilder pszOut, ref uint pcchOut, uint dwPart, uint dwFlags);
///
/// Hashes a URL string.
///
///
/// Type: PCTSTR
/// A null-terminated string of maximum length INTERNET_MAX_URL_LENGTH that contains the URL.
///
///
/// Type: BYTE*
/// A pointere to a buffer that, when this function returns successfully, receives the hashed array.
///
///
/// Type: DWORD
/// The number of elements in the array at pbHash. It should be no larger than 256.
///
///
/// Type: HRESULT
/// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.
///
///
///
/// To hash a URL into a single byte, set cbHash = sizeof(BYTE) and pbHash = (LPBYTE)&bHashedValue, where bHashedValue is a
/// one-byte buffer. To hash a URL into a DWORD, set cbHash = sizeof(DWORD) and pbHash = (LPBYTE)&dwHashedValue, where
/// dwHashedValue is a DWORD buffer.
///
///
// https://docs.microsoft.com/en-us/windows/desktop/api/shlwapi/nf-shlwapi-urlhasha LWSTDAPI UrlHashA( PCSTR pszUrl, BYTE *pbHash,
// DWORD cbHash );
[DllImport(Lib.Shlwapi, SetLastError = false, CharSet = CharSet.Auto)]
[PInvokeData("shlwapi.h", MSDNShortId = "9c0ce709-e097-4501-bee1-b24df9d4828d")]
public static extern HRESULT UrlHash(string pszUrl, IntPtr pbHash, uint cbHash);
///
/// Tests whether a URL is a specified type.
///
///
/// Type: PCTSTR
/// A null-terminated string of maximum length INTERNET_MAX_URL_LENGTH that contains the URL.
///
///
/// Type: URLIS
/// The type of URL to be tested for. This parameter can take one of the following values.
/// URLIS_APPLIABLE
/// Attempt to determine a valid scheme for the URL.
/// URLIS_DIRECTORY
/// Does the URL string end with a directory?
/// URLIS_FILEURL
/// Is the URL a file URL?
/// URLIS_HASQUERY
/// Does the URL have an appended query string?
/// URLIS_NOHISTORY
/// Is the URL a URL that is not typically tracked in navigation history?
/// URLIS_OPAQUE
/// Is the URL opaque?
/// URLIS_URL
/// Is the URL valid?
///
///
/// Type: BOOL
///
/// For all but one of the URL types, UrlIs returns TRUE if the URL is the specified type, or FALSE if not.
///
///
/// If UrlIs is set to URLIS_APPLIABLE, UrlIs will attempt to determine the URL scheme. If the function is able to
/// determine a scheme, it returns TRUE, or FALSE otherwise.
///
///
// https://docs.microsoft.com/en-us/windows/desktop/api/shlwapi/nf-shlwapi-urlisa BOOL UrlIsA( PCSTR pszUrl, URLIS UrlIs );
[DllImport(Lib.Shlwapi, SetLastError = false, CharSet = CharSet.Auto)]
[PInvokeData("shlwapi.h", MSDNShortId = "2e83c953-b4c5-4411-90ca-49ffb94ee374")]
[return: MarshalAs(UnmanagedType.Bool)]
public static extern bool UrlIs(string pszUrl, URLIS UrlIs);
///
/// Returns whether a URL is a URL that browsers typically do not include in navigation history.
///
///
/// Type: PCTSTR
/// A null-terminated string of maximum length INTERNET_MAX_URL_LENGTH that contains the URL.
///
///
/// Type: BOOL
/// Returns a nonzero value if the URL is a URL that is not included in navigation history, or zero otherwise.
///
///
/// This function is equivalent to the following:
///
// https://docs.microsoft.com/en-us/windows/desktop/api/shlwapi/nf-shlwapi-urlisnohistorya BOOL UrlIsNoHistoryA( PCSTR pszURL );
[DllImport(Lib.Shlwapi, SetLastError = false, CharSet = CharSet.Auto)]
[PInvokeData("shlwapi.h", MSDNShortId = "7602d2ef-1f21-4b2f-8ac9-195bb21d6ae7")]
[return: MarshalAs(UnmanagedType.Bool)]
public static extern bool UrlIsNoHistory(string pszURL);
///
/// Returns whether a URL is opaque.
///
///
/// Type: PCTSTR
/// A null-terminated string of maximum length INTERNET_MAX_URL_LENGTH that contains the URL.
///
///
/// Type: BOOL
/// Returns a nonzero value if the URL is opaque, or zero otherwise.
///
///
///
/// A URL that has a scheme that is not followed by two slashes (//) is opaque. For example, xyz@litwareinc.com is an opaque URL.
/// Opaque URLs cannot be separated into the standard URL hierarchy. UrlIsOpaque is equivalent to the following:
///
///
// https://docs.microsoft.com/en-us/windows/desktop/api/shlwapi/nf-shlwapi-urlisopaquea BOOL UrlIsOpaqueA( PCSTR pszURL );
[DllImport(Lib.Shlwapi, SetLastError = false, CharSet = CharSet.Auto)]
[PInvokeData("shlwapi.h", MSDNShortId = "460f4d41-2796-496d-9199-f2d1cd6e4a24")]
[return: MarshalAs(UnmanagedType.Bool)]
public static extern bool UrlIsOpaque(string pszURL);
///
/// Converts escape sequences back into ordinary characters.
///
///
/// Type: PTSTR
///
/// A pointer to a null-terminated string with the URL. If dwFlags is set to URL_UNESCAPE_INPLACE, the converted string is
/// returned through this parameter.
///
///
///
/// Type: PTSTR
///
/// A pointer to a buffer that will receive a null-terminated string that contains the unescaped version of pszURL. If
/// URL_UNESCAPE_INPLACE is set in dwFlags, this parameter is ignored.
///
///
///
/// Type: DWORD*
///
/// The number of characters in the buffer pointed to by pszUnescaped. On entry, the value pcchUnescaped points to is set to the size
/// of the buffer. If the function returns a success code, the value that pcchUnescaped points to is set to the number of characters
/// written to that buffer, not counting the terminating NULL character. If an E_POINTER error code is returned, the buffer
/// was too small, and the value to which pcchUnescaped points is set to the required number of characters that the buffer must be
/// able to contain. If any other errors are returned, the value to which pcchUnescaped points is undefined.
///
///
///
/// Type: DWORD
/// Flags that control which characters are unescaped. It can be a combination of the following flags.
/// URL_DONT_UNESCAPE_EXTRA_INFO
/// Do not convert the # or ? character, or any characters following them in the string.
/// URL_UNESCAPE_AS_UTF8
/// Introduced in Windows 8. Decode URLs that were encoded by using the URL_ESCAPE_AS_UTF8 flag.
/// URL_UNESCAPE_INPLACE
/// Use pszURL to return the converted string instead of pszUnescaped.
///
///
/// Type: HRESULT
///
/// Returns S_OK if successful. If the URL_UNESCAPE_INPLACE flag is not set, the value pointed to by pcchUnescaped will be set
/// to the number of characters in the output buffer pointed to by pszUnescaped. Returns E_POINTER if the URL_UNESCAPE_INPLACE
/// flag is not set and the output buffer is too small. The pcchUnescaped parameter will be set to the required buffer size.
/// Otherwise, returns a standard error value.
///
///
///
/// An escape sequence has the form "%xy".
/// Input strings cannot be longer than INTERNET_MAX_URL_LENGTH.
///
// https://docs.microsoft.com/en-us/windows/desktop/api/shlwapi/nf-shlwapi-urlunescapea LWSTDAPI UrlUnescapeA( PSTR pszUrl, PSTR
// pszUnescaped, DWORD *pcchUnescaped, DWORD dwFlags );
[DllImport(Lib.Shlwapi, SetLastError = false, CharSet = CharSet.Auto)]
[PInvokeData("shlwapi.h", MSDNShortId = "5bff5161-3b57-4f12-b126-42eac3f60267")]
public static extern HRESULT UrlUnescape(StringBuilder pszUrl, StringBuilder pszUnescaped, ref uint pcchUnescaped, URLFLAGS dwFlags);
///
/// Used by the ParseURL function to return the parsed URL.
///
// https://docs.microsoft.com/en-us/windows/desktop/api/shlwapi/ns-shlwapi-tagparsedurla typedef struct tagPARSEDURLA { DWORD cbSize;
// LPCSTR pszProtocol; UINT cchProtocol; LPCSTR pszSuffix; UINT cchSuffix; UINT nScheme; } PARSEDURLA, *PPARSEDURLA;
[PInvokeData("shlwapi.h", MSDNShortId = "9092dd7a-ff5b-465f-a808-ef4e0067f540")]
[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Auto)]
public struct PARSEDURL
{
///
/// Type: DWORD
///
/// [in] The size of the structure, in bytes. The calling application must set this member before calling the ParseURL function.
///
///
public uint cbSize;
///
/// Type: LPCTSTR
/// [out] A pointer to the beginning of the protocol part of the URL.
///
public string pszProtocol;
///
/// Type: UINT
/// The number of characters in the URL's protocol section.
///
public uint cchProtocol;
///
/// Type: LPCTSTR
///
/// [out] A pointer to the section of the URL that follows the protocol and colon (':'). For file URLs, the function also skips
/// the leading "//" characters.
///
///
public string pszSuffix;
///
/// Type: UINT
/// [out] The number of characters in the URL's suffix.
///
public uint cchSuffix;
///
/// Type: UINT
/// [out] A value from the URL_SCHEME enumeration that specifies the URL's scheme.
///
public URL_SCHEME nScheme;
}
}
}