HTTP Sessions


		Contents Index Topic Contents
	Previous Topic: Gopher Sessions Next Topic: Cookie Functions

HTTP Sessions

The Win32 Internet functions allow you to access resources on the World Wide Web (WWW). These resources can be accessed directly by using InternetOpenUrl (for more information, see Accessing URLs directly) or the HTTP functions.
Resources on the WWW are accessed by using HTTP. The Win32 Internet functions include a set of stable HTTP functions that handle the underlying protocols, while allowing your application to access information on the WWW. As the HTTP protocol evolves, the underlying protocols will be updated to maintain HTTP function behavior.
The following diagram shows the relationships of the Win32 Internet functions that are used for the HTTP protocol. The shaded boxes represent functions that return HINTERNET handles, while the plain boxes represent functions that use the HINTERNET handle created by the function on which they depend.

For more information on HINTERNET handles and the handle hierarchy, see Appendix A: HINTERNET Handles.
Using the Win32 Internet Functions to Access the WWW

The following functions are used during HTTP sessions to access the WWW.

Function Description

HttpAddRequestHeaders Adds HTTP request headers to the HTTP request handle. This function requires a handle created by HttpOpenRequest.

HttpOpenRequest Opens an HTTP request handle. This function requires a handle created by InternetConnect.

HttpQueryInfo Queries information about an HTTP request. This function requires a handle created by the HttpOpenRequest or InternetOpenUrl function.

HttpSendRequest Sends the specified HTTP request to the HTTP server. This function requires a handle created by HttpOpenRequest.

InternetErrorDlg Displays predefined dialog boxes for common Internet error conditions. This function requires the handle used in the call to HttpSendRequest.

Initiating a connection to the WWW

To start a connection to the WWW, the application must call the InternetConnect function on the root HINTERNET returned by InternetOpen. InternetConnect must establish an HTTP session by declaring the INTERNET_SERVICE_HTTP service type. For more information on using InternetConnect, see Using InternetConnect.
Opening a request

The HttpOpenRequest function opens an HTTP request and returns an HINTERNET handle that can be used by the other HTTP functions. Unlike the other open functions (such as FtpOpenFile and InternetOpenUrl), HttpOpenRequest does not send the request to the Internet when called. The HttpSendRequest function sends the request and establishes a connection over the network.
HttpOpenRequest takes an HTTP session handle created by InternetConnect and a verb, object name, version string, referrer, accept types, flags, and context value.
The verb is a string to be used in the request. Common verbs used in requests include "GET", "PUT", and "POST". If this value is set to NULL, HttpOpenRequest uses the default value "GET".
The object name is a string that contains the name of the specified verb's target object. This is generally a file name, an executable module, or a search specifier. If the object name supplied is an empty string, HttpOpenRequest looks for the default page.
The version string should contain the HTTP version. If this parameter is set to NULL, the function uses "HTTP/1.0".
The referrer specifies the address of the document from which the object name was obtained. If this parameter is NULL, no referrer is specified.
The NULL-terminated string containing the accept types indicates the content types accepted by the application. Setting this parameter to NULL indicates that no content types are accepted by the application. If an empty string is supplied, the application is indicating it accepts only documents of type "text/*". The value "text/*" indicates text-only documents—not pictures or other binary files.
The flag values control caching, cookies, and security issues. For Microsoft Network (MSN), NTLM, and other types of authentication, set the INTERNET_FLAG_KEEP_CONNECTION flag.
If the INTERNET_FLAG_ASYNC flag was set in the call to InternetOpen, a nonzero context value should be set for proper asynchronous operation.
The following example is a sample call to HttpOpenRequest.
hHttpRequest = HttpOpenRequest(hHttpSession, "GET", "", NULL, "", NULL, 0,0);
Adding request headers

The Win32 Internet function HttpAddRequestHeaders allows applications to add one or more request headers to the initial request. This function allows an application to append additional free-format headers to the HTTP request handle; it is intended for use by sophisticated applications that need precise control over the request sent to the HTTP server.
HttpAddRequestHeaders needs an HTTP request handle created by HttpOpenRequest, a string containing the headers, the length of the headers, and modifiers.
The following modifiers can be used with HttpAddRequestHeaders:

HTTP_ADDREQ_FLAG_ADD Adds the header if it does not exist. Used with HTTP_ADDREQ_FLAG_REPLACE.

HTTP_ADDREQ_FLAG_ADD_IF_NEW Adds the header only if it does not already exist; otherwise, an error is returned.

HTTP_ADDREQ_FLAG_COALESCE Coalesces headers of the same name.

HTTP_ADDREQ_FLAG_COALESCE_WITH_COMMA Coalesces headers of the same name. For example, adding "Accept: text/*" followed by "Accept: audio/*" with this flag forms the single header "Accept: text/*, audio/*", causing the first header found to be coalesced. It is up to the calling application to ensure a cohesive scheme with respect to coalesced/separate headers.

HTTP_ADDREQ_FLAG_COALESCE_WITH_SEMICOLON Coalesces headers of the same name, using a semicolon.

HTTP_ADDREQ_FLAG_REPLACE Replaces or removes a header. If the header value is empty and the header is found, it is removed. If the header value is not empty, the header value is replaced.

Sending a request

HttpSendRequest establishes a connection to the Internet and sends the request to the specified site. This function requires an HINTERNET handle created by HttpOpenRequest. HttpSendRequest can also send additional headers or optional information. The optional information is generally used for operations that write information to the server, such as PUT and POST.
After HttpSendRequest sends the request, the application can use the InternetReadFile, InternetQueryDataAvailable, and InternetSetFilePointer functions on the HINTERNET handle created by HttpOpenRequest to download the server's resources.
Posting data to the server

To post data to a server, the verb in the call to HttpOpenRequest must be either "POST" or "PUT". The address of the buffer containing the POST data should then be passed to the lpOptional parameter in HttpSendRequest. The dwOptionalLength parameter should be set to the size of the data.
Using the Microsoft Internet Explorer 4.0 version of WinInet, you can also use the InternetWriteFile function to post data on an HINTERNET handle sent using HttpSendRequestEx.
Getting information about a request

HttpQueryInfo allows an application to retrieve information about an HTTP request. The function requires an HINTERNET handle created by HttpOpenRequest or InternetOpenUrl, an information level value, and a buffer length. HttpQueryInfo also accepts a buffer that stores the information and a zero-based header index that enumerates multiple headers with the same name.
The following information level values can be used with a modifier to control the format in which the information is stored in lpvBuffer:

HTTP_QUERY_ALLOW Receives the methods supported by the server.

HTTP_QUERY_CONTENT_DESCRIPTION Receives the content description.

HTTP_QUERY_CONTENT_ID Receives the content identification.

HTTP_QUERY_CONTENT_LENGTH Receives the size of the resource in bytes.

HTTP_QUERY_CONTENT_TRANSFER_ENCODING Receives the additional content coding that has been applied to the resource.

HTTP_QUERY_CONTENT_TYPE Receives the content type of the resource (such as text/html).

HTTP_QUERY_DATE Receives the date and time at which the message was originated.

HTTP_QUERY_EXPIRES Receives the date and time after which the resource should be considered outdated.

HTTP_QUERY_LAST_MODIFIED Receives the date and time at which the server believes the resource was last modified.

HTTP_QUERY_MIME_VERSION Receives the version of the MIME protocol that was used to construct the message.

HTTP_QUERY_PRAGMA Receives the implementation-specific directives that might apply to any recipient along the request/response chain.

HTTP_QUERY_PUBLIC Receives the methods available from this server.

HTTP_QUERY_RAW_HEADERS Receives all the headers returned by the server. Each header is terminated by "\0". An additional "\0" terminates the list of headers.

HTTP_QUERY_RAW_HEADERS_CRLF Receives all the headers returned by the server. Each header is separated by a carriage return/line feed (CR/LF) sequence.

HTTP_QUERY_REQUEST_METHOD Receives the verb that is being used in the request, typically GET or POST.

HTTP_QUERY_STATUS_CODE Receives the status code returned by the server.

HTTP_QUERY_STATUS_TEXT Receives any additional text returned by the server on the response line.

HTTP_QUERY_URL Receives some or all of the URLs by which the Request-URL resource can be identified.

HTTP_QUERY_VERSION Receives the last response code returned by the server.

The following modifiers can be used with the information values:

HTTP_QUERY_CUSTOM Causes HttpQueryInfo to search for the ASCIIZ header name specified in lpvBuffer and store the header information in lpvBuffer.

HTTP_QUERY_FLAG_COALESCE Combines the values from headers with the same name into the output buffer.

HTTP_QUERY_FLAG_NUMBER Returns the data as a 32-bit number for headers whose value is a number, such as the status code.

HTTP_QUERY_FLAG_REQUEST_HEADERS Queries request headers only.

HTTP_QUERY_FLAG_SYSTEMTIME Returns the header value as a standard Win32 SYSTEMTIME structure, which does not require the application to parse the data. Use for headers whose value is a date/time string, such as "Last-Modified-Time".

HTTP_QUERY_INFO_NUMBER Sets the data type returned by HttpQueryInfo to a DWORD.

Downloading resources from the WWW

After opening a request with HttpOpenRequest and sending it to the server with HttpSendRequest, the application can use the InternetReadFile, InternetQueryDataAvailable, and InternetSetFilePointer functions to download the resource from the HTTP server.
The following example downloads a resource. The function accepts the handle to the current window, the identification number of an edit box, and an HINTERNET handle created by HttpOpenRequest and sent by HttpSendRequest. It uses InternetQueryDataAvailable to determine the size of the resource and then downloads it using InternetReadFile. The contents are then displayed in the edit box.
int WINAPI Dumper(HWND hX, int intCtrlID, HINTERNET hResource)
{
     LPSTR     lpszData;          // buffer for the data
     DWORD     dwSize;               // size of the data available
     DWORD     dwDownloaded;     // size of the downloaded data
     DWORD     dwSizeSum=0;     // size of the data in the textbox
     LPSTR     lpszHolding;     // buffer to merge the textbox data and buffer

     // Set the cursor to an hourglass.
     SetCursor(LoadCursor(NULL,IDC_WAIT));


     // This loop handles reading the data.  
     do
     {
          // The call to InternetQueryDataAvailable determines the amount of 
          // data available to download.
          if (!InternetQueryDataAvailable(hResource,&dwSize,0,0))
          {
               ErrorOut(hX,GetLastError(),"InternetReadFile");
               SetCursor(LoadCursor(NULL,IDC_ARROW));
               return FALSE;
          }
          else
          {     
               // Allocates a buffer of the size returned by InternetQueryDataAvailable
               lpszData = new char[dwSize+1];

               // Reads the data from the HINTERNET handle.
               if(!InternetReadFile(hResource,(LPVOID)lpszData,dwSize,&dwDownloaded))
               {
                    ErrorOut(hX,GetLastError(),"InternetReadFile");
                    delete[] lpszData;
                    break;
               }
               else
               {
                    // Adds a null terminator to the end of the data buffer
                    lpszData[dwDownloaded]='\0';

                    // Allocates the holding buffer
                    lpszHolding = new char[dwSizeSum + dwDownloaded + 1];
                    
                    // Checks if there has been any data written to the textbox
                    if (dwSizeSum != 0)
                    {
                         // Retrieves the data stored in the textbox if any
                         GetDlgItemText(hX,intCtrlID,(LPSTR)lpszHolding,dwSizeSum);
                         
                         // Adds a null terminator at the end of the textbox data
                         lpszHolding[dwSizeSum]='\0';
                    }
                    else
                    {
                         // Make the holding buffer an empty string. 
                         lpszHolding[0]='\0';
                    }

                    // Adds the new data to the holding buffer
                    strcat(lpszHolding,lpszData);

                    // Writes the holding buffer to the textbox
                    SetDlgItemText(hX,intCtrlID,(LPSTR)lpszHolding);

                    // Delete the two buffers
                    delete[] lpszHolding;
                    delete[] lpszData;

                    // Add the size of the downloaded data to the textbox data size
                    dwSizeSum = dwSizeSum + dwDownloaded + 1;

                    // Check the size of the remaining data.  If it is zero, break.
                    if (dwDownloaded == 0)
                         break;
               }
          }
     }
     while(TRUE);

     // Close the HINTERNET handle
     InternetCloseHandle(hResource);

     // Set the cursor back to an arrow
     SetCursor(LoadCursor(NULL,IDC_ARROW));

     // Return
     return TRUE;
}
Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.

Function	Description
HttpAddRequestHeaders	Adds HTTP request headers to the HTTP request handle. This function requires a handle created by HttpOpenRequest.
HttpOpenRequest	Opens an HTTP request handle. This function requires a handle created by InternetConnect.
HttpQueryInfo	Queries information about an HTTP request. This function requires a handle created by the HttpOpenRequest or InternetOpenUrl function.
HttpSendRequest	Sends the specified HTTP request to the HTTP server. This function requires a handle created by HttpOpenRequest.
InternetErrorDlg	Displays predefined dialog boxes for common Internet error conditions. This function requires the handle used in the call to HttpSendRequest.

HTTP_ADDREQ_FLAG_ADD	Adds the header if it does not exist. Used with HTTP_ADDREQ_FLAG_REPLACE.
HTTP_ADDREQ_FLAG_ADD_IF_NEW	Adds the header only if it does not already exist; otherwise, an error is returned.
HTTP_ADDREQ_FLAG_COALESCE	Coalesces headers of the same name.
HTTP_ADDREQ_FLAG_COALESCE_WITH_COMMA	Coalesces headers of the same name. For example, adding "Accept: text/" followed by "Accept: audio/" with this flag forms the single header "Accept: text/, audio/", causing the first header found to be coalesced. It is up to the calling application to ensure a cohesive scheme with respect to coalesced/separate headers.
HTTP_ADDREQ_FLAG_COALESCE_WITH_SEMICOLON	Coalesces headers of the same name, using a semicolon.
HTTP_ADDREQ_FLAG_REPLACE	Replaces or removes a header. If the header value is empty and the header is found, it is removed. If the header value is not empty, the header value is replaced.

HTTP_QUERY_ALLOW	Receives the methods supported by the server.
HTTP_QUERY_CONTENT_DESCRIPTION	Receives the content description.
HTTP_QUERY_CONTENT_ID	Receives the content identification.
HTTP_QUERY_CONTENT_LENGTH	Receives the size of the resource in bytes.
HTTP_QUERY_CONTENT_TRANSFER_ENCODING	Receives the additional content coding that has been applied to the resource.
HTTP_QUERY_CONTENT_TYPE	Receives the content type of the resource (such as text/html).
HTTP_QUERY_DATE	Receives the date and time at which the message was originated.
HTTP_QUERY_EXPIRES	Receives the date and time after which the resource should be considered outdated.
HTTP_QUERY_LAST_MODIFIED	Receives the date and time at which the server believes the resource was last modified.
HTTP_QUERY_MIME_VERSION	Receives the version of the MIME protocol that was used to construct the message.
HTTP_QUERY_PRAGMA	Receives the implementation-specific directives that might apply to any recipient along the request/response chain.
HTTP_QUERY_PUBLIC	Receives the methods available from this server.
HTTP_QUERY_RAW_HEADERS	Receives all the headers returned by the server. Each header is terminated by "\0". An additional "\0" terminates the list of headers.
HTTP_QUERY_RAW_HEADERS_CRLF	Receives all the headers returned by the server. Each header is separated by a carriage return/line feed (CR/LF) sequence.
HTTP_QUERY_REQUEST_METHOD	Receives the verb that is being used in the request, typically GET or POST.
HTTP_QUERY_STATUS_CODE	Receives the status code returned by the server.
HTTP_QUERY_STATUS_TEXT	Receives any additional text returned by the server on the response line.
HTTP_QUERY_URL	Receives some or all of the URLs by which the Request-URL resource can be identified.
HTTP_QUERY_VERSION	Receives the last response code returned by the server.

HTTP_QUERY_CUSTOM	Causes HttpQueryInfo to search for the ASCIIZ header name specified in lpvBuffer and store the header information in lpvBuffer.
HTTP_QUERY_FLAG_COALESCE	Combines the values from headers with the same name into the output buffer.
HTTP_QUERY_FLAG_NUMBER	Returns the data as a 32-bit number for headers whose value is a number, such as the status code.
HTTP_QUERY_FLAG_REQUEST_HEADERS	Queries request headers only.
HTTP_QUERY_FLAG_SYSTEMTIME	Returns the header value as a standard Win32 SYSTEMTIME structure, which does not require the application to parse the data. Use for headers whose value is a date/time string, such as "Last-Modified-Time".
HTTP_QUERY_INFO_NUMBER	Sets the data type returned by HttpQueryInfo to a DWORD.