 | ||||||
| ||||||
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.
The following functions are used during HTTP sessions to access the WWW.
| 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. |
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.
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);
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. |
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.
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 Win32 Internet API, you can also use the InternetWriteFile function to post data on an HINTERNET handle sent using HttpSendRequestEx.
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. |
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
{
// Allocate a buffer of the size returned by
// InternetQueryDataAvailable.
lpszData = new char[dwSize+1];
// Read the data from the HINTERNET handle.
if(!InternetReadFile(hResource,(LPVOID)lpszData,dwSize,&dwDownloaded))
{
ErrorOut(hX,GetLastError(),"InternetReadFile");
delete[] lpszData;
break;
}
else
{
// Add a null terminator to the end of the data buffer.
lpszData[dwDownloaded]='\0';
// Allocate the holding buffer.
lpszHolding = new char[dwSizeSum + dwDownloaded + 1];
// Check if there has been any data written to the textbox.
if (dwSizeSum != 0)
{
// Retrieve the data stored in the textbox if any.
GetDlgItemText(hX,intCtrlID,(LPSTR)lpszHolding,dwSizeSum);
// Add a null terminator at the end of the textbox data.
lpszHolding[dwSizeSum]='\0';
}
else
{
// Make the holding buffer an empty string.
lpszHolding[0]='\0';
}
// Add the new data to the holding buffer
strcat(lpszHolding,lpszData);
// Write 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;
}
Did you find this topic useful? Suggestions for other topics? Write us!
© 1999 Microsoft Corporation. All rights reserved. Terms of use.
Back to top