WinHttpCreateUrl function (winhttp.h)
The WinHttpCreateUrl function creates a URL from component parts such as the host name and path.
Syntax
WINHTTPAPI BOOL WinHttpCreateUrl(
[in] LPURL_COMPONENTS lpUrlComponents,
[in] DWORD dwFlags,
[out] LPWSTR pwszUrl,
[in, out] LPDWORD pdwUrlLength
);
Parameters
[in] lpUrlComponents
Pointer to a URL_COMPONENTS structure that contains the components from which to create the URL.
[in] dwFlags
Flags that control the operation of this function. This parameter can be one of the following values.
Value | Meaning |
---|---|
|
Converts all unsafe characters to their corresponding escape sequences in the path string pointed to by the lpszUrlPath member and in lpszExtraInfo the extra-information string pointed to by the member of the URL_COMPONENTS structure pointed to by the lpUrlComponents parameter. |
|
Rejects URLs as input that contains either a username, or a password, or both. If the function fails because of an invalid URL, subsequent calls to GetLastError will return ERROR_WINHTTP_INVALID_URL. |
[out] pwszUrl
Pointer to a character buffer that receives the URL as a wide character (Unicode) string.
[in, out] pdwUrlLength
Pointer to a variable of type unsigned long integer that receives the length of the pwszUrl buffer in wide (Unicode) characters. When the function returns, this parameter receives the length of the URL string wide in characters, minus 1 for the terminating character. If GetLastError returns ERROR_INSUFFICIENT_BUFFER, this parameter receives the number of wide characters required to hold the created URL.
Return value
Returns TRUE if the function succeeds, or FALSE otherwise. To get extended error data, call GetLastError. Among the error codes returned are the following.
Error Code | Description |
---|---|
|
An internal error occurred. |
|
Insufficient memory 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 data, call GetLastError.
Examples
The following example shows how to decompile, or crack, a URL into its subcomponents, 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 data. New data 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)