<?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_d0e281425_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>