InternetCrackUrlA function (wininet.h)

Cracks a URL into its component parts.

Syntax

BOOL InternetCrackUrlA(
  [in]      LPCSTR            lpszUrl,
  [in]      DWORD             dwUrlLength,
  [in]      DWORD             dwFlags,
  [in, out] LPURL_COMPONENTSA lpUrlComponents
);

Parameters

[in] lpszUrl

Pointer to a string that contains the canonical URL to be cracked.

[in] dwUrlLength

Size of the lpszUrl string, in TCHARs, or zero if lpszUrl is an ASCIIZ string.

[in] dwFlags

Controls the operation. This parameter can be one of the following values.

Value Meaning
ICU_DECODE
Converts encoded characters back to their normal form. This can be used only if the user provides buffers in the URL_COMPONENTS structure to copy the components into.
ICU_ESCAPE
Converts all escape sequences (%xx) to their corresponding characters. This can be used only if the user provides buffers in the URL_COMPONENTS structure to copy the components into.

[in, out] lpUrlComponents

Pointer to a URL_COMPONENTS structure that receives the URL components.

Return value

Returns TRUE if the function succeeds, or FALSE otherwise. To get extended error information, call GetLastError.

Remarks

The required components are indicated by members of the URL_COMPONENTS structure. Each component has a pointer to the value and has a member that stores the length of the stored value. If both the value and the length for a component are equal to zero, that component is not returned. Windows Vista and later.:  If the pointer to the value of the component is NULL and the value of its corresponding length member is nonzero, the address of the first character of the corresponding component in the lpszUrl string is stored in the pointer, and the length of the component is stored in the length member.

If the pointer contains the address of the user-supplied buffer, the length member must contain the size of the buffer. InternetCrackUrl copies the component into the buffer, and the length member is set to the length of the copied component, minus 1 for the trailing string terminator.

For InternetCrackUrl to work properly, the size of the URL_COMPONENTS structure, in bytes, must be stored in the dwStructSize member.

Note  Do not use InternetCrackUrl on "file://" URLs that contain spaces, because the value returned in the dwUrlPathLength member of the URL_COMPONENTS structure pointed to by lpUrlComponents is too large. This is only the case, however, with "file://" URLs that contain space characters.

Like all other aspects of the WinINet API, this function cannot be safely called from within DllMain or the constructors and destructors of global objects.

Note  WinINet does not support server implementations. In addition, it should not be used from a service. For server implementations or services use Microsoft Windows HTTP Services (WinHTTP).
 

Note

The wininet.h header defines InternetCrackUrl 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.

Requirements

Requirement Value
Minimum supported client Windows 2000 Professional [desktop apps only]
Minimum supported server Windows 2000 Server [desktop apps only]
Target Platform Windows
Header wininet.h
Library Wininet.lib
DLL Wininet.dll

See also

FtpOpenFile

Handling Uniform Resource Locators

InternetCloseHandle

InternetFindNextFile

InternetSetStatusCallback

WinINet Functions