WinHttpConnect function (winhttp.h)
The WinHttpConnect function specifies the initial target server of an HTTP request and returns an HINTERNET connection handle to an HTTP session for that initial target.
Syntax
WINHTTPAPI HINTERNET WinHttpConnect(
[in] HINTERNET hSession,
[in] LPCWSTR pswzServerName,
[in] INTERNET_PORT nServerPort,
[in] DWORD dwReserved
);
Parameters
[in] hSession
Valid HINTERNET WinHTTP session handle returned by a previous call to WinHttpOpen.
[in] pswzServerName
Pointer to a null-terminated string that contains the host name of an HTTP server. Alternately, the string can contain the IP address of the site as a string, for example, 10.0.1.45. Note that WinHttp does not accept international host names without converting them first to Punycode. For more information, see Handling Internationalized Domain Names (IDNs).
[in] nServerPort
Unsigned integer that specifies the TCP/IP port on the server to which a connection is made. This parameter can be any valid TCP/IP port number, or one of the following values.
| Value | Meaning |
|---|---|
|
Uses the default port for HTTP servers (port 80). |
|
Uses the default port for HTTPS servers (port 443). Selecting this port does not automatically establish a secure connection. You must still specify the use of secure transaction semantics by using the WINHTTP_FLAG_SECURE flag with WinHttpOpenRequest. |
|
Uses port 80 for HTTP and port 443 for Secure Hypertext Transfer Protocol (HTTPS). |
[in] dwReserved
This parameter is reserved and must be 0.
Return value
Returns a valid connection handle to the HTTP session if the connection is successful, or NULL otherwise. To retrieve extended error information, call GetLastError. Among the error codes returned are the following.
| Error Codes | Description |
|---|---|
|
The type of handle supplied is incorrect for this operation. |
|
An internal error has occurred. |
|
The URL is invalid. |
|
The operation was canceled, usually because the handle on which the request was operating was closed before the operation completed. |
|
The URL scheme could not be recognized, or is not supported. |
|
The WinHTTP function support is being shut down or unloaded. |
|
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.
After the calling application has finished using the HINTERNET handle returned by WinHttpConnect, it must be closed using the WinHttpCloseHandle function.
WinHttpConnect specifies the target HTTP server, however a response can come from another server if the request was redirected. You can determine the URL of the server sending the response by calling WinHttpQueryOption with the WINHTTP_OPTION_URL flag.
Examples
The following example shows how to use secure transaction semantics to download a resource from an HTTPS server. The sample code initializes the Microsoft Windows HTTP Services (WinHTTP) application programming interface (API), selects a target HTTPS server, then opens and sends a request for this secure resource.
WinHttpQueryDataAvailable is used with the request handle to determine how much data is available for download, then
WinHttpReadData is used to read that data. This process repeats until the entire document has been retrieved and displayed.
DWORD dwSize = 0;
DWORD dwDownloaded = 0;
LPSTR pszOutBuffer;
BOOL bResults = FALSE;
HINTERNET hSession = NULL,
hConnect = NULL,
hRequest = NULL;
// Use WinHttpOpen to obtain a session handle.
hSession = WinHttpOpen( L"WinHTTP Example/1.0",
WINHTTP_ACCESS_TYPE_DEFAULT_PROXY,
WINHTTP_NO_PROXY_NAME,
WINHTTP_NO_PROXY_BYPASS, 0);
// Specify an HTTP server.
if (hSession)
hConnect = WinHttpConnect( hSession, L"www.microsoft.com",
INTERNET_DEFAULT_HTTPS_PORT, 0);
// Create an HTTP request handle.
if (hConnect)
hRequest = WinHttpOpenRequest( hConnect, L"GET", NULL,
NULL, WINHTTP_NO_REFERER,
WINHTTP_DEFAULT_ACCEPT_TYPES,
WINHTTP_FLAG_SECURE);
// Send a request.
if (hRequest)
bResults = WinHttpSendRequest( hRequest,
WINHTTP_NO_ADDITIONAL_HEADERS,
0, WINHTTP_NO_REQUEST_DATA, 0,
0, 0);
// End the request.
if (bResults)
bResults = WinHttpReceiveResponse( hRequest, NULL);
// Keep checking for data until there is nothing left.
if (bResults)
do
{
// Check for available data.
dwSize = 0;
if (!WinHttpQueryDataAvailable( hRequest, &dwSize))
printf("Error %u in WinHttpQueryDataAvailable.\n", GetLastError());
// Allocate space for the buffer.
pszOutBuffer = new char[dwSize+1];
if (!pszOutBuffer)
{
printf("Out of memory\n");
dwSize=0;
}
else
{
// Read the Data.
ZeroMemory(pszOutBuffer, dwSize+1);
if (!WinHttpReadData( hRequest, (LPVOID)pszOutBuffer,
dwSize, &dwDownloaded))
printf( "Error %u in WinHttpReadData.\n", GetLastError());
else
printf( "%s\n", pszOutBuffer);
// Free the memory allocated to the buffer.
delete [] pszOutBuffer;
}
} while (dwSize > 0);
// Report any errors.
if (!bResults)
printf("Error %d has occurred.\n", GetLastError());
// Close any open handles.
if (hRequest) WinHttpCloseHandle(hRequest);
if (hConnect) WinHttpCloseHandle(hConnect);
if (hSession) WinHttpCloseHandle(hSession);
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. |