Windows Internet

Extensions
HTTP API Specification

Revision 0.0
October 31, 1994

Microsoft Confidential
 Table of Contents
Table of Contents
..............................................................................................................................................................

Revision History
..............................................................................................................................................................

Outstanding Issues
..............................................................................................................................................................

1.  Overview
..............................................................................................................................................................

1.1 Goals
................................................................................................................................................

2.  API Details
..............................................................................................................................................................

2.1 Constants
................................................................................................................................................

2.2 Types
................................................................................................................................................

2.3 Status Codes
................................................................................................................................................

2.4 APIs
................................................................................................................................................

2.4.1. HttpOpenRequest
.................................................................................................................................

2.4.2. HttpCloseRequest
.................................................................................................................................

2.4.3. HttpAddRequestHeaders
.................................................................................................................................

2.4.4. HttpSendRequest
.................................................................................................................................

2.4.5. HttpReadData

ii
 .................................................................................................................................

2.4.6. HttpQueryInfo
.................................................................................................................................

3.  Sample Client Code Fragment
..............................................................................................................................................................

iii
 Revision History
Version Date Author Description
0.0 31-Oct-1994 KeithMo Created this document.
 Outstanding Issues

1. What is the default content-transfer-encoding?

2. Define error codes!
3. Speaking of error codes, what are we going to do about WinSock error codes? Do we map them to
existing Win32 error codes? Do we map them to new Win32 error codes? Do we return them
“raw” to the client DLL? Returning them “raw” feels strange, since GetLastError() is
supposted to return a Win32 error code.
4. What about RPC? I suspect we may need to create a (hopefully small) set of “private” error codes.
Certain RPC & WinSock operations would get their error codes mapped to one of these
“private” error codes. This would present a uniform view to the client application, regardless
of whether they were running direct connect or via a Catapult gateway.
5. Is HttpAddRequestHeaders() really necessary, or is the fact that HttpSendRequest() takes an
“additional headers” parameter sufficient?
1. Overview
This document defines a set of APIs for accessing HTTP servers. These APIs leverage off the INET API
(see the INET API Specification) for local and Catapult-enabled Internet access.

1.1 Goals
The HTTP API design must meet the following goals:
1. Hide the HTTP protocol from the application. By concentrating all protocol knowlege in a single
DLL, application writers are free to concentrate more on the applications themselves.
2. Allow sophisticated clients access to the raw HTTP data if they think they really need it.
3. Support HTTP protocol extensions (such as the Keep-Connection pragma) to optimize network
bandwidth and system resources when the HTTP DLL is accessing a Windows NT HTTP
Server.
4. Tolerate minor HTTP protocol changes/extensions without requiring API changes.
5. Minimize the number of extraneous RFC822/MIME/HTTP headers sent to the server in the
request block. In other words, don’t send the server a header just to tell it to use a default
value.
6. Leverage off the INET API to enable seemless direct (local) and indirect (Catapult-enabled)
Internet access.
7. Provide ANSI and UNICODE versions of all data types and APIs.
2. API Details
This section details the constants, types, and APIs defined by the INET header file.

2.1 Constants
//
// The default HTTP port for TCP/IP connections.
//

#define HTTP_TCPIP_PORT 80

//
// The default major/minor HTTP version numbers.
//

#define HTTP_MAJOR_VERSION 1
#define HTTP_MINOR_VERSION 0

//
// HttpQueryInfo info levels. Generally, there is one info level
// for each potential RFC822/MIME/HTTP header that an HTTP server
// may send as part of a request response.
//
// The HTTP_QUERY_RAW_HEADERS info level is provided for clients
// that choose to perform their own header parsing.
//

#define HTTP_QUERY_MIME_VERSION 0x0001

#define HTTP_QUERY_CONTENT_TYPE 0x0002
#define HTTP_QUERY_CONTENT_TRANSFER_ENCODING 0x0003
#define HTTP_QUERY_CONTENT_ID 0x0004
#define HTTP_QUERY_CONTENT_DESCRIPTION 0x0005
#define HTTP_QUERY_CONTENT_LENGTH 0x0006
#define HTTP_QUERY_ALLOWED_METHODS 0x0007
#define HTTP_QUERY_PUBLIC_METHODS 0x0008
#define HTTP_QUERY_DATE 0x0009
#define HTTP_QUERY_EXPIRES 0x000A
#define HTTP_QUERY_LAST_MODIFIED 0x000B
#define HTTP_QUERY_MESSAGE_ID 0x000C
#define HTTP_QUERY_URI 0x000D
#define HTTP_QUERY_VERSION 0x000E
#define HTTP_QUERY_DERIVED_FROM 0x000F
#define HTTP_QUERY_LANGUAGE 0x0010
#define HTTP_QUERY_COST 0x0011
#define HTTP_QUERY_WWW_LINK 0x0012
#define HTTP_QUERY_STATUS_CODE 0x0013
#define HTTP_QUERY_STATUS_TEXT 0x0014
#define HTTP_QUERY_RAW_HEADERS 0x0015
#define HTTP_QUERY_MAX 0x0015

2.2 Types
//
// HHTTPREQ : A handle to an HTTP request.
//

typedef LPVOID HHTTPREQ;

//
// A TCP/IP port.
//

typedef unsigned short TCPIP_PORT;

2.3 Status Codes
//
// HTTP Response Status Codes:
//

#define HTTP_STATUS_OK 200 // request completed

#define HTTP_STATUS_CREATED 201 // object created, reason = new URI
#define HTTP_STATUS_ACCEPTED 202 // async completion (TBS)
#define HTTP_STATUS_PARTIAL 203 // partial completion

#define HTTP_STATUS_MOVED 301 // object permanently moved

#define HTTP_STATUS_REDIRECT 302 // object temporarily moved
#define HTTP_STATUS_REDIRECT_METHOD 303 // redirection w/ new access method

#define HTTP_STATUS_BAD_REQUEST 400 // invalid syntax

#define HTTP_STATUS_DENIED 401 // access denied
#define HTTP_STATUS_PAYMENT_REQ 402 // payment required
#define HTTP_STATUS_FORBIDDEN 403 // request forbidden
#define HTTP_STATUS_NOT_FOUND 404 // object not found

#define HTTP_STATUS_SERVER_ERROR 500 // internal server error

#define HTTP_STATUS_NOT_SUPPORTED 501 // required not supported

2.4 APIs
All HTTP APIs use a consistent naming convention, function linkage, and decoration. Each API is of the
following form:

INETAPI
<<return_type>>
WINAPI
HttpXxxx(
<<parameters>>
);

The INETAPI decoration allows the APIs to be “declspec’d” for efficiency. The WINAPI linkage specifier
provides consistency with other Win32 APIs.

All HTTP APIs return an easily identified value to indicate a failure condition. Additional error status is
always available via the GetLastError() API.
2.4.1. HttpOpenRequest
Description Opens an HTTP request handle. An HTTP request handle encapsulates a request to be
sent to an HTTP server. The HTTP request handle contains all RFC822/MIME/HTTP
headers to be sent as part of the request.

#define INCL_HTTP
#include <inetapi.h>

INETAPI
HTTPREQ
WINAPI
HttpOpenRequest%(
IN HINET hInternet,
IN LPCTSTR% lpszServerName,
IN PORT nServerPort,
IN LPCTSTR %lpszVerb,
IN LPCTSTR% lpszObjectName,
IN DWORD dwMajorVersion,
IN DWORD dwMinorVersion,
IN LPCTSTR% lpszUserAgent,
IN LPCTSTR% lpszReferer,
IN LPCTSTR% FAR * lplpszAcceptTypes,
IN LPCTSTR% FAR * lplpszAcceptEncodings
);

hInternet An open Internet handle returned by the InetOpen() API.

lpszServerName The name of the target HTTP server. This name may be either
a name resolvable via the RNR APIs, or a dotted IP address
resolvable via the inet_addr() API.

nServerPort The IP port to connect to (if using TCP/IP).

lpszVerb The verb to use in the request.

lpszObjectName The target object of the specified verb. This is typically a file
name, an executable module, or a search specifier.

dwMajorVersion The major HTTP version for the request. Must be

HTTP_MAJOR_VERSION in the initial release.

dwMinorVersion The minor HTTP version for the request. Must be

HTTP_MINOR_VERSION in the initial release.

lpszUserAgent Specifies the software program used by the original client.

May be NULL in which case no user agent is specified.

lpszReferer Specifies the address (URI) of the document from which the
URI in the request (lpszObjectName) was obtained. May be
NULL in which case no referer is specified.

lplpszAcceptTypes Points to a NULL-terminated array of LPCTSTR pointers to

content-types accepted by the client. This value may be NULL
in which case the default content-type (text/html) is used.
 lplpszAcceptEncodings Points to a NULL-terminated array of LPCTSTR pointers to
content-transfer-encodings accepted by the clinet. This value
may be NULL in which case the default content-transfer-
encoding is used.

BUGBUG: What is the default content-transfer-encoding?

Remarks This function creates a new HTTP request handle and stores the specified parameters in
that handle.

Return Value A valid (non-NULL) HTTP request handle if successful, NULL otherwise. Extended
error information is available via the GetLastError() API.

Error Codes
ERROR_INVALID_PARAMETER Invalid parameter.

See Also InetOpen(), HttpCloseRequest(), HttpSendRequest(), HttpAddRequestHeaders(),

HttpReadData(), HttpQueryInfo().
2.4.2. HttpCloseRequest
Description Closes an open HTTP request handle.

#define INCL_HTTP
#include <inetapi.h>

INETAPI
BOOL
WINAPI
HttpCloseRequest(
IN HHTTPREQ hHttpRequest
);

hHttpRequest An open HTTP request handle returned by

HttpOpenRequest().

Remarks This function closes an open HTTP request handle. All resources associated with the
handle are released, and any open HTTP server connections are aborted.

Return Value TRUE if the function is successful, FALSE otherwise. Extended error information is
available via the GetLastError() API.

Error Codes
ERROR_INVALID_PARAMETER Invalid parameter.

See Also HttpOpenRequest().

2.4.3. HttpAddRequestHeaders
Description Adds one or more HTTP request headers to the HTTP request handle.

#define INCL_HTTP
#include <inetapi.h>

INETAPI
BOOL
WINAPI
HttpAddRequestHeaders%(
IN HHTTPREQ hHttpRequest,
IN LPCTSTR% lpszHeaders,
IN DWORD dwHeadersLength
);

hHttpRequest An open HTTP request handle returned by

HttpOpenRequest().

lpszHeaders The headers to append to the request. Each header must be

terminated by a CR/LF pair.

dwHeadersLength The length (in characters) of lpszHeaders. If this is -1L, then

lpszHeaders is assumed to be zero terminated (ASCIIZ) and
the length is computed.

Remarks This function appends additional “free format” headers to the HTTP request handle.
This API is intended for use by sophisticated clients that need detailed control over the
exact request sent to the HTTP server.

Return Value TRUE if the function is successful, FALSE otherwise. Extended error information is
available via the GetLastError() API.

Error Codes
ERROR_INVALID_PARAMETER Invalid parameter.

See Also HttpOpenRequest(), HttpSendRequest().

2.4.4. HttpSendRequest
Description This function sends the specified request to the HTTP server.

#define INCL_HTTP
#include <inetapi.h>

INETAPI
BOOL
WINAPI
HttpSendRequest%(
IN HHTTPREQ hHttpRequest,
IN LPCTSTR% lpszHeaders,
IN DWORD dwHeadersLength,
IN LPVOID lpOptional,
IN DWORD dwOptionalLength
);

hHttpRequest An open HTTP request handle returned by

HttpOpenRequest().

lpszAdditional Additional headers to be appended to the request. This may

be NULL if there are no additional headers to append.

dwAdditionalLength The length (in characters) of the additional headers. If this is

-1L and lpszAdditional is non-NULL, then lpszAdditional is
assumed to be zero terminated (ASCIIZ) and the length is
calculated.

lpOptional Any optional data to send immediately after the request

headers. This is typically used for POST and PUT operations.
This may be NULL if there is no optional data to send.

dwOptionalLength The length (in BYTEs) of the optional data. This may be zero
if there is no optional data to send.

Remarks This function sends the specified request to the HTTP server. This function allows the
client to specify additional RFC822/MIME/HTTP headers to send along with the
request.

This function also allows the client to specify “optional” data to send to the HTTP server
immediately following the request headers. This feature is typically used for “write”
operations such as PUT and POST.

After the request is sent, this function reads the status code and response headers from
the HTTP server. These headers are maintained internally to the request handle, and are
available to client applications via the HttpQueryInfo() API.

Return Value TRUE if the function is successful, FALSE otherwise. Extended error information is
available via the GetLastError() API.

Error Codes
ERROR_INVALID_PARAMETER Invalid parameter.

See Also HttpOpenRequest(), HttpReadData(), HttpQueryInfo().

2.4.5. HttpReadData
Description This function reads a block of data from an outstanding HTTP request.

#define INCL_HTTP
#include <inetapi.h>

INETAPI
BOOL
WINAPI
HttpReadData(
IN HHTTPREQ hHttpRequest,
OUT LPVOID lpBuffer,
IN OUT LPDWORD lpBufferLength
);

hHttpRequest An open HTTP request handle returned by

HttpOpenRequest().

lpBuffer Pointer to the buffer that will receive the data.

lpBufferLength On entry, points to a value containing the length (in BYTEs)

of the data buffer. On exit, points to a value containing the
number of BYTEs actually read.

Remarks This function reads a block of data from an outstanding HTTP request. This is typically
used to retrieve object data from a GET operation.

Return Value TRUE if the function is successful, FALSE otherwise. Extended error information is
available via the GetLastError() API.

Error Codes
ERROR_INVALID_PARAMETER Invalid parameter.

See Also HttpOpenRequest().

2.4.6. HttpQueryInfo
Description Queries information about an HTTP request.

#define INCL_HTTP
#include <inetapi.h>

INETAPI
BOOL
WINAPI
HttpQueryInfo%(
IN HHTTPREQ hHttpRequest,
IN DWORD dwInfoLevel,
IN OUT LPTSTR% lpBuffer,
IN OUT LPDWORD lpBufferLength
);

hHttpRequest An open HTTP request handle returned by

HttpOpenRequest().

dwInfoLevel One of the HTTP_QUERY_* values indicating the attribute

to query.

lpBuffer Pointer to the buffer that will receive the information.

lpBufferLength On entry, points to a value containing the length (in BYTEs)

of the data buffer. On exit, points to a value containing the
length (in BYTEs) of the information written to the buffer.

Remarks This function queries information from an HTTP request.

Most info levels return simple values. HTTP_QUERY_CONTENT_LENGTH, for

example, returns an ASCII string representing the size (in BYTEs) of the returned
object.

HTTP_QUERY_RAW_HEADERS is not so simple. This info level allows a client to

access the raw RFC822/MIME/HTTP headers returned by the HTTP server. On entry to
this API, lpBuffer points to the field name of the header to retrieve (i.e. “Accept:”). If
lpBuffer points to an empty string (i.e. “”), then *all* headers are returned.

Return Value TRUE if the function is successful, FALSE otherwise. Extended error information is
available via the GetLastError() API.

Error Codes
ERROR_INVALID_PARAMETER Invalid parameter.

See Also HttpOpenRequest().

3. Sample Client Code Fragment
This section contains a sample code fragment from a simple HTTP client. The fragment connects to an
HTTP server and retrieves the /default.htm object. This simplified fragment performs no error checking.
HINET hInternet;
HHTTPREQ hHttpRequest;
CHAR szBuffer[512];
DWORD dwBufferLength;
LPCTSTR AcceptTypes[] =
{
TEXT(“text/html, q=1.0”),
TEXT(“text/plain, q=0.9”),
NULL
};
LPCTSTR AcceptEncodings[] =
{
TEXT(“8BIT”),
NULL
};

//
// Open the Internet.
//

hInternet = InetOpen(
NULL, // lpReserved
0 // dwReserved
);

//
// Open a new request.
//

hHttpRequest = HttpOpenRequest(
hInternet, // hInternet
TEXT(“www.foo.com”), // lpServerName
HTTP_TCPIP_PORT // nServerPort
TEXT(“GET”), // HttpVerb
TEXT(“/default.htm”), // lpszObjectName
HTTP_MAJOR_VERSION, // dwMajorVersion
HTTP_MINOR_VERSION, // dwMinorVersion
TEXT(“Test Client”), // lpszUserAgent
NULL, // lpszReferer
AcceptTypes, // lplpszAcceptTypes
AcceptEncodings // lplpszAcceptEncodings,
);

//
// Send the request.
//

HttpSendRequest(
hHttpRequest, // hHttpRequest
NULL, // lpszAdditional
0, // dwHeadersLength
NULL, // lpOptional
0 // dwOptionalLength
);

//
// Read the raw data, write it to stdout.
//

for( ; ; )
{
dwBufferLength = sizeof(szBuffer);

HttpReadData(
 hHttpRequest, // hHttpRequest
szBuffer, // lpBuffer
&dwBufferLength // lpBufferLength
);

if( dwBufferLength == 0 )
{
break;
}

fwrite( szBuffer, 1, dwBufferLength, stdout );

}

//
// Cleanup.
//

HttpCloseRequest( hHttpRequest ); // hHttpRequest

InetClose( hInternet ); // hInternet