WinHttpConnect

 

Description

 

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.

 

C/C++ Syntax

 

HINTERNET WinHttpConnect(

HINTERNET hSession,

LPCWSTR pswzServerName,

INTERNET_PORT nServerPort,

DWORD dwReserved

);

 

PowerBASIC Syntax

 

FUNCTION WinHttpConnect ( _

BYVAL hSession AS DWORD, _

BYVAL pswzServerName AS DWORD, _

BYVAL nServerPort AS WORD, _

BYVAL dwReserved AS DWORD _

) AS LONG

 

Parameters

 

hSession

 

[in] Valid HINTERNET WinHTTP session handle returned by a previous call to WinHttpOpen.

 

pswzServerName

 

[in] Pointer to a null-terminated Unicode string that contains the host name of an HTTP server. Alternately, the string can contain the IP address of the site in ASCII, for example, 10.0.1.45.

 

nServerPort

 

[in] Unsigned integer that specifies the TCP/IP port on the server to which a connection is made. This can be any valid TCP/IP port number, or one of the following values:

 

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).

 

dwReserved

 

[in] Reserved. Must be zero.

 

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:

 

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.

 

Example Code [PowerBASIC]

 

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.

 

#COMPILE EXE

#DIM ALL

#INCLUDE "WIN32API.INC"

#INCLUDE "WINHTTP.INC"

 

FUNCTION PBMAIN () AS LONG

 

 LOCAL dwSize AS DWORD

 LOCAL dwDownloaded AS DWORD

 LOCAL bResults AS LONG

 LOCAL hSession AS DWORD

 LOCAL hConnect AS DWORD

 LOCAL hRequest AS DWORD

 LOCAL strUserAgent AS STRING

 LOCAL strServerName AS STRING

 LOCAL strVerb AS STRING

 LOCAL strOutBuffer AS STRING

 

 dwSize = 4  ' size of a DWORD

 

 ' Use WinHttpOpen to obtain a session handle.

 strUserAgent = UCODE$("A WinHTTP Example Program/1.0" & $NUL)

 hSession = WinHttpOpen(STRPTR(strUserAgent), _

                        %WINHTTP_ACCESS_TYPE_DEFAULT_PROXY, _

                        %WINHTTP_NO_PROXY_NAME, _

                        %WINHTTP_NO_PROXY_BYPASS, _

                        0)

 

 ' Specify an HTTP server.

 IF hSession THEN

    strServerName = UCODE$("www.microsoft.com" & $NUL)

    hConnect = WinHttpConnect(hSession, _

                              STRPTR(strServerName), _

                              %INTERNET_DEFAULT_HTTP_PORT, _

                              0)

 END IF

 

 

 ' Create an HTTP Request handle.

 IF hConnect THEN

    strVerb = UCODE$("GET" & $NUL)

    hRequest = WinHttpOpenRequest(hConnect, _

                                  STRPTR(strVerb), _

                                  %NULL,  _

                                  %NULL, _

                                  %WINHTTP_NO_REFERER, _

                                  BYVAL %WINHTTP_DEFAULT_ACCEPT_TYPES, _

                                  0)

 END IF

 

 ' Send a Request.

 ' Note: The Microsoft C example uses WINHTTP_FLAG_SECURE for the last

 ' parameter, but I have changed it to 0 because, otherwise, it returns

 ' error 12175 (ERROR_WINHTTP_SECURE_FAILURE)

 IF hRequest THEN

    bResults = WinHttpSendRequest(hRequest, _

                                  %WINHTTP_NO_ADDITIONAL_HEADERS, _

                                  0, _

                                  %WINHTTP_NO_REQUEST_DATA, _

                                  0, _

                                  0, _

                                  0)

 END IF

 

 ' End the request.

 IF bResults THEN

    bResults = WinHttpReceiveResponse(hRequest, %NULL)

 END IF

 

 ' Keep checking for data until there is nothing left.

 IF bResults THEN

    DO

       ' Check for available data.

       dwSize = 0

       IF ISFALSE WinHttpQueryDataAvailable(hRequest, dwSize) THEN

          PRINT "Error " GetLastError " in WinHttpQueryDataAvailable."

          EXIT DO

       ELSE

          ' Allocate space for the buffer.

          strOutBuffer = STRING$(dwSize + 1, $NUL)

          ' Read the data.

          IF ISFALSE WinHttpReadData(hRequest, STRPTR(strOutBuffer), _

                                     dwSize, dwDownloaded) THEN

             PRINT "Error " GetLastError " in WinHttpReadData."

          ELSE

             STDOUT strOutBuffer

          END IF

       END IF

    LOOP WHILE dwSize > 0

 END IF

 

 ' Report any errors.

 IF ISFALSE bResults THEN

    PRINT "Error " GetLastError " has occurred."

 END IF

 

 ' Close open handles.

 IF hRequest THEN WinHttpCloseHandle(hRequest)

 IF hConnect THEN WinHttpCloseHandle(hConnect)

 IF hSession THEN WinHttpCloseHandle(hSession)

 

 WAITKEY$

 

END FUNCTION

 

Example Code [C++]

 

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

              cout << 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);

 

Valid XHTML 1.0 Transitional