HTTP Client -overview

Purpose

The -HTTP (Hypertext Transfer Protocol) Client API provides a client interface -for Internet applications to use the HTTP protocol for communication with -HTTP servers on the Internet. Using the API correctly enables the application -to be a conditionally HTTP 1.1 compliant client, as defined in RFC 2616.

The -HTTP protocol is a request and response protocol. A client sends a request -to the server. This request consists of a request method, URI, and protocol -version, including a Multipurpose Internet Mail Extensions (MIME)-like message -containing request modifiers, client information, and body content over a -server connection. The server responds with a status, which includes the message's -protocol version and a success or error code, and a MIME-like message containing -server information, meta information, and body content. The following image -illustrates a simple HTTP session between a client and a server.

- Simple HTTP Interaction - -

See Hypertext -Transfer Protocol -- HTTP/1.1, RFC 2616 for more details.

Architectural -relationships

The HTTP Client architecture provides a generalised -mechanism for HTTP-like protocols that operate over various transports. Using -a single API, a client can choose an HTTP protocol, encoding, and transport, -and need not implement these in its own code. The default operation provides -plain-text HTTP (as defined in RFC 2616) operating over a TCP/IP connection. -This transport pipelines requests by default.

Description

There -are five key concepts used in the API: sessions, transactions, headers, data -suppliers, and filters.

Sessions

A session encapsulates -the client's HTTP activity over the duration of the client's execution. Typicallly, -one HTTP session runs in one active scheduler.

Note: An active -scheduler must be installed when a session is opened.

Usually, one -session is used at a time. However, the client may use several concurrently, -if required. Each session has an associated set of properties, which define -the HTTP protocol, encoding, and transport used. Those properties apply to -all HTTP transactions within the life of that session. The session also has -an associated set of filters that provide additional automatic behaviours -on the client's behalf.

The session class is provided by RHTTPSession.

Transactions

A -transaction represents an interaction between a HTTP client and an HTTP origin -server. Normally a transaction consists of a single exchange of messages between -client and server: a client request and a server response. However, the transaction -may be extended or altered by filters that operate on it. See Filters for -more details.

Transactions execute asychronously within the client's -process. The client is notified when events are available for each outstanding -transaction.

Both the request and response portion of a transaction -consist of a header and an optional body. The request portion of the transaction -also specifies an HTTP Method that describes the type of operation that the -client wants to invoke at the origin server, together with a URI that specifies -the resource held at the server on which the method is to be invoked. The -response portion of a transaction contains an HTTP status code and message, -which indicate the success of the method or the state of the resource following -the method. The use of request and response bodies is determined by the HTTP -method in use. For example, in error conditions, some servers may just return -a status code and message, providing no entity body.

The transaction -class is provided by RHTTPTransaction.

Headers

The -header portion of requests and responses may have zero or more fields, which -are used to convey information between the HTTP client and server. The information -might relate to the data conveyed in body of the message, to the actual connection -between the client and server, or might be used to convey data describing -the client or server themselves. Typically, headers can contain content encoding -and transfer encoding information. Since the HTTP API gives clients implementation -independence from these choices, a generic form is used to represent header -data in the API.

The headers class is provided by RHTTPHeaders.

Data -suppliers

The body portion of requests and responses is represented -in the API as a mix-in interface, allowing the real implementation of the -classes that generate body data to be fully hidden. The API enables signalling -between the client and the transport in use, to ensure that body data is only -used or released at a rate the client can support. This means that clients -can assemble the body of their requests piece-by-piece, have each piece transmitted -only when it is ready, and be signalled when transmission is complete so the -next piece may be prepared and the old one released.

Data supplier -classes must implement MHTTPDataSupplier.

Filters

Filters -are add-on modules that provide additional behaviours to a session beyond -the simple request-response transaction described earlier. Behaviours may -be triggered by the presence of particular headers in a request or a response, -by status codes in a response, or by particular events that occur on a transaction. -RFC 2616 describes a number of standard behaviours that occur over a series -of request-response exchanges: client authentication, redirection, and caching. -Client authentication and redirection are implemented as individual filters.

Filter -classes must implement MHTTPFilter.

Refer to Filters for more information.

Example code

Example -code used throughout this guide is taken from HTTPEXAMPLECLIENT, -a simple console application that provides a menu-driven interface to the -HTTP API.

+ + + + + +HTTP Client +overview +

Purpose

The +HTTP (Hypertext Transfer Protocol) Client API provides a client interface +for Internet applications to use the HTTP protocol for communication with +HTTP servers on the Internet. Using the API correctly enables the application +to be a conditionally HTTP 1.1 compliant client, as defined in RFC 2616.

The +HTTP protocol is a request and response protocol. A client sends a request +to the server. This request consists of a request method, URI, and protocol +version, including a Multipurpose Internet Mail Extensions (MIME)-like message +containing request modifiers, client information, and body content over a +server connection. The server responds with a status, which includes the message's +protocol version and a success or error code, and a MIME-like message containing +server information, meta information, and body content. The following image +illustrates a simple HTTP session between a client and a server.

+ Simple HTTP Interaction + +

See Hypertext +Transfer Protocol -- HTTP/1.1, RFC 2616 for more details.

Architectural +relationships

The HTTP Client architecture provides a generalised +mechanism for HTTP-like protocols that operate over various transports. Using +a single API, a client can choose an HTTP protocol, encoding, and transport, +and need not implement these in its own code. The default operation provides +plain-text HTTP (as defined in RFC 2616) operating over a TCP/IP connection. +This transport pipelines requests by default.

Description

There +are five key concepts used in the API: sessions, transactions, headers, data +suppliers, and filters.

Sessions

A session encapsulates +the client's HTTP activity over the duration of the client's execution. Typicallly, +one HTTP session runs in one active scheduler.

Note: An active +scheduler must be installed when a session is opened.

Usually, one +session is used at a time. However, the client may use several concurrently, +if required. Each session has an associated set of properties, which define +the HTTP protocol, encoding, and transport used. Those properties apply to +all HTTP transactions within the life of that session. The session also has +an associated set of filters that provide additional automatic behaviours +on the client's behalf.

The session class is provided by RHTTPSession.

Transactions

A +transaction represents an interaction between a HTTP client and an HTTP origin +server. Normally a transaction consists of a single exchange of messages between +client and server: a client request and a server response. However, the transaction +may be extended or altered by filters that operate on it. See Filters for +more details.

Transactions execute asychronously within the client's +process. The client is notified when events are available for each outstanding +transaction.

Both the request and response portion of a transaction +consist of a header and an optional body. The request portion of the transaction +also specifies an HTTP Method that describes the type of operation that the +client wants to invoke at the origin server, together with a URI that specifies +the resource held at the server on which the method is to be invoked. The +response portion of a transaction contains an HTTP status code and message, +which indicate the success of the method or the state of the resource following +the method. The use of request and response bodies is determined by the HTTP +method in use. For example, in error conditions, some servers may just return +a status code and message, providing no entity body.

The transaction +class is provided by RHTTPTransaction.

Headers

The +header portion of requests and responses may have zero or more fields, which +are used to convey information between the HTTP client and server. The information +might relate to the data conveyed in body of the message, to the actual connection +between the client and server, or might be used to convey data describing +the client or server themselves. Typically, headers can contain content encoding +and transfer encoding information. Since the HTTP API gives clients implementation +independence from these choices, a generic form is used to represent header +data in the API.

The headers class is provided by RHTTPHeaders.

Data +suppliers

The body portion of requests and responses is represented +in the API as a mix-in interface, allowing the real implementation of the +classes that generate body data to be fully hidden. The API enables signalling +between the client and the transport in use, to ensure that body data is only +used or released at a rate the client can support. This means that clients +can assemble the body of their requests piece-by-piece, have each piece transmitted +only when it is ready, and be signalled when transmission is complete so the +next piece may be prepared and the old one released.

Data supplier +classes must implement MHTTPDataSupplier.

Filters

Filters +are add-on modules that provide additional behaviours to a session beyond +the simple request-response transaction described earlier. Behaviours may +be triggered by the presence of particular headers in a request or a response, +by status codes in a response, or by particular events that occur on a transaction. +RFC 2616 describes a number of standard behaviours that occur over a series +of request-response exchanges: client authentication, redirection, and caching. +Client authentication and redirection are implemented as individual filters.

Filter +classes must implement MHTTPFilter.

Refer to Filters for more information.

Example code

Example +code used throughout this guide is taken from HTTPEXAMPLECLIENT, +a simple console application that provides a menu-driven interface to the +HTTP API.

\ No newline at end of file