WinHttpCrackUrl function (winhttp.h)
The WinHttpCrackUrl function separates a URL into its component parts such as host name and path.
Syntax
WINHTTPAPI BOOL WinHttpCrackUrl(
[in] LPCWSTR pwszUrl,
[in] DWORD dwUrlLength,
[in] DWORD dwFlags,
[in, out] LPURL_COMPONENTS lpUrlComponents
);
Parameters
[in] pwszUrl
Pointer to a string that contains the canonical URL to separate. WinHttpCrackUrl does not check this URL for validity or correct format before attempting to crack it.
[in] dwUrlLength
The length of the pwszUrl string, in characters. If dwUrlLength is set to zero, WinHttpCrackUrl assumes that the pwszUrl string is null terminated and determines the length of the pwszUrl string based on that assumption.
[in] dwFlags
The flags that control the operation. This parameter can be a combination of one or more of the following flags (values can be bitwise OR'd together). Or, the parameter can be 0, which performs no special operations.
| Value | Meaning |
|---|---|
|
Converts characters that are "escape encoded" (%xx) to their non-escaped form. This does not decode other encodings, such as UTF-8. This feature can be used only if the user provides buffers in the URL_COMPONENTS structure to copy the components into. |
|
Escapes certain characters to their escape sequences (%xx). Characters to be escaped are non-ASCII characters or those ASCII characters that must be escaped to be represented in an HTTP request. This feature can be used only if the user provides buffers in the URL_COMPONENTS structure to copy the components into. |
|
Rejects URLs as input that contain embedded credentials (either a username, a password, or both). If the function fails because of an invalid URL, then subsequent calls to GetLastError return ERROR_WINHTTP_INVALID_URL. |
[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. Among the error codes returned are the following.
| Error Codes | Description |
|---|---|
|
An internal error has occurred. |
|
The URL is invalid. |
|
The URL scheme could not be recognized, or is not supported. |
|
Not enough memory was available to complete the requested operation. (Windows error code) |
Remarks
Even when WinHTTP is used in asynchronous mode (that is, when WINHTTP_FLAG_ASYNC has been set in WinHttpOpen), this function operates synchronously. The return value indicates success or failure. To get extended error information, call GetLastError.
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. If the pointer to the value of the component is not NULL and the value of its corresponding length member is nonzero, the address of the first character of the corresponding component in the pwszUrl 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. The WinHttpCrackUrl function 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. If a user-supplied buffer is not large enough, WinHttpCrackUrl returns FALSE, and GetLastError returns ERROR_INSUFFICIENT_BUFFER.
For WinHttpCrackUrl to work properly, the size of the URL_COMPONENTS structure must be stored in the dwStructSize member of that structure.
If the Internet protocol of the URL passed in for
pwszUrl is not HTTP or HTTPS, then
WinHttpCrackUrl returns FALSE and
GetLastError indicates
ERROR_WINHTTP_UNRECOGNIZED_SCHEME.
WinHttpCrackUrl does not check the validity or format of a URL before attempting to crack it. As a result, if a string such as ""http://server?Bad=URL"" is passed in, the function returns incorrect results.
Examples
This example shows how to break a URL into its components, update a component, then reconstruct the URL.
URL_COMPONENTS urlComp;
LPCWSTR pwszUrl1 =
L"http://search.msn.com/results.asp?RS=CHECKED&FORM=MSNH&v=1&q=wininet";
DWORD dwUrlLen = 0;
// Initialize the URL_COMPONENTS structure.
ZeroMemory(&urlComp, sizeof(urlComp));
urlComp.dwStructSize = sizeof(urlComp);
// Set required component lengths to non-zero
// so that they are cracked.
urlComp.dwSchemeLength = (DWORD)-1;
urlComp.dwHostNameLength = (DWORD)-1;
urlComp.dwUrlPathLength = (DWORD)-1;
urlComp.dwExtraInfoLength = (DWORD)-1;
// Crack the URL.
if (!WinHttpCrackUrl( pwszUrl1, (DWORD)wcslen(pwszUrl1), 0, &urlComp))
{
printf("Error %u in WinHttpCrackUrl.\n", GetLastError());
}
else
{
// Change the search information.
// New info is the same length.
urlComp.lpszExtraInfo = L"?RS=CHECKED&FORM=MSNH&v=1&q=winhttp";
// Obtain the size of the new URL and allocate memory.
WinHttpCreateUrl( &urlComp, 0, NULL, &dwUrlLen);
LPWSTR pwszUrl2 = new WCHAR[dwUrlLen];
// Create a new URL.
if(!WinHttpCreateUrl( &urlComp, 0, pwszUrl2, &dwUrlLen))
{
printf("Error %u in WinHttpCreateUrl.\n", GetLastError());
}
else
{
// Show both URLs.
printf("Old URL: %S\nNew URL: %S\n", pwszUrl1, pwszUrl2);
}
// Free allocated memory.
delete [] pwszUrl2;
}
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows XP, Windows 2000 Professional with SP3 [desktop apps only] |
| Minimum supported server | Windows Server 2003, Windows 2000 Server with SP3 [desktop apps only] |
| Target Platform | Windows |
| Header | winhttp.h |
| Library | Winhttp.lib |
| DLL | Winhttp.dll |
| Redistributable | WinHTTP 5.0 and Internet Explorer 5.01 or later on Windows XP and Windows 2000. |
See also
About Microsoft Windows HTTP Services (WinHTTP)