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
INTERNET_DEFAULT_HTTP_PORT
Uses the default port for HTTP servers (port 80).
INTERNET_DEFAULT_HTTPS_PORT
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.
INTERNET_DEFAULT_PORT
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
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE
The type of handle supplied is incorrect for this operation.
ERROR_WINHTTP_INTERNAL_ERROR
An internal error has occurred.
ERROR_WINHTTP_INVALID_URL
The URL is invalid.
ERROR_WINHTTP_OPERATION_CANCELLED
The operation was canceled, usually because the handle on which the request was operating was closed before the operation completed.
ERROR_WINHTTP_UNRECOGNIZED_SCHEME
The URL scheme could not be recognized, or is not supported.
ERROR_WINHTTP_SHUTDOWN
The WinHTTP function support is being shut down or unloaded.
ERROR_NOT_ENOUGH_MEMORY
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.

Note  For Windows XP and Windows 2000, see the Run-Time Requirements section of the WinHttp start page.
 

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.

See also

About Microsoft Windows HTTP Services (WinHTTP)

WinHTTP Versions

WinHttpCloseHandle

WinHttpOpen

WinHttpOpenRequest