<?xml version="1.0" encoding="utf-8"?>
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
<!-- This component and the accompanying materials are made available under the terms of the License 
"Eclipse Public License v1.0" which accompanies this distribution, 
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
<!-- Initial Contributors:
    Nokia Corporation - initial contribution.
Contributors: 
-->
<!DOCTYPE concept
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="GUID-50BBCB9C-F234-5813-A42E-3FCFB0F14B66" xml:lang="en"><title>HTTP Client
overview</title><prolog><metadata><keywords/></metadata></prolog><conbody>
<section id="GUID-D44E394A-3FB9-4884-A8AB-6E8E252ACBFC"><title>Purpose</title> <p>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. </p> <p>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. </p> <fig id="GUID-784DD05A-B86B-57F0-A2E0-A34E373ABA34">
<title>              Simple HTTP Interaction           </title>
<image href="GUID-18547A2C-7425-5478-8235-EC6D3848B404_d0e212244_href.png" placement="inline"/>
</fig> <p>See <xref href="http://www.ietf.org/rfc/rfc2616.txt" scope="external">Hypertext
Transfer Protocol -- HTTP/1.1, RFC 2616</xref> for more details. </p> </section>
<section id="GUID-80DD2A3D-1C59-4AD5-8838-8DC9E1752729"><title>Architectural
relationships</title> <p>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. </p> </section>
<section id="GUID-4F83C7A0-C17F-4C58-840E-3E51EA52F098"><title>Description</title> <p>There
are five key concepts used in the API: sessions, transactions, headers, data
suppliers, and filters. </p><p><b>Sessions </b> </p> <p>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. </p> <p> <b>Note:</b> An active
scheduler must be installed when a session is opened. </p> <p>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. </p> <p>The session class is provided by <xref href="GUID-651801A5-5473-3856-9647-46823598C5C1.dita"><apiname>RHTTPSession</apiname></xref>. </p> <p><b>Transactions </b> </p> <p>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 <xref href="GUID-AA2A730E-A7C9-5647-AD42-11C3BAF4C38D.dita">Filters</xref> for
more details. </p> <p>Transactions execute asychronously within the client's
process. The client is notified when events are available for each outstanding
transaction. </p> <p>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. </p> <p>The transaction
class is provided by <xref href="GUID-2E673024-239B-3965-8880-C47B7CC24EF6.dita"><apiname>RHTTPTransaction</apiname></xref>. </p> <p><b>Headers </b> </p> <p>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. </p> <p>The headers class is provided by <xref href="GUID-54F9A87B-FE2F-3429-9793-0A24B83466B9.dita"><apiname>RHTTPHeaders</apiname></xref>. </p> <p><b>Data
suppliers </b> </p> <p>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. </p> <p>Data supplier
classes must implement <xref href="GUID-1B03F068-9552-37BA-A284-8E54FAC2AAC5.dita"><apiname>MHTTPDataSupplier</apiname></xref>. </p> <p><b>Filters </b> </p> <p>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. </p> <p>Filter
classes must implement <xref href="GUID-2E1C08E2-9024-3269-A1BD-C6B901E78841.dita"><apiname>MHTTPFilter</apiname></xref>. </p> <p>Refer to <xref href="GUID-AA2A730E-A7C9-5647-AD42-11C3BAF4C38D.dita">Filters</xref> for more information. </p> </section>
<section id="GUID-75720715-786A-4537-BC1B-949815E5E8AD"><title>Example code</title> <p>Example
code used throughout this guide is taken from <filepath>HTTPEXAMPLECLIENT</filepath>,
a simple console application that provides a menu-driven interface to the
HTTP API. </p> </section>
</conbody></concept>