|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-50BBCB9C-F234-5813-A42E-3FCFB0F14B66" xml:lang="en"><title>HTTP Client |
|
13 overview</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <section id="GUID-D44E394A-3FB9-4884-A8AB-6E8E252ACBFC"><title>Purpose</title> <p>The |
|
15 HTTP (Hypertext Transfer Protocol) Client API provides a client interface |
|
16 for Internet applications to use the HTTP protocol for communication with |
|
17 HTTP servers on the Internet. Using the API correctly enables the application |
|
18 to be a conditionally HTTP 1.1 compliant client, as defined in RFC 2616. </p> <p>The |
|
19 HTTP protocol is a request and response protocol. A client sends a request |
|
20 to the server. This request consists of a request method, URI, and protocol |
|
21 version, including a Multipurpose Internet Mail Extensions (MIME)-like message |
|
22 containing request modifiers, client information, and body content over a |
|
23 server connection. The server responds with a status, which includes the message's |
|
24 protocol version and a success or error code, and a MIME-like message containing |
|
25 server information, meta information, and body content. The following image |
|
26 illustrates a simple HTTP session between a client and a server. </p> <fig id="GUID-784DD05A-B86B-57F0-A2E0-A34E373ABA34"> |
|
27 <title> Simple HTTP Interaction </title> |
|
28 <image href="GUID-18547A2C-7425-5478-8235-EC6D3848B404_d0e212244_href.png" placement="inline"/> |
|
29 </fig> <p>See <xref href="http://www.ietf.org/rfc/rfc2616.txt" scope="external">Hypertext |
|
30 Transfer Protocol -- HTTP/1.1, RFC 2616</xref> for more details. </p> </section> |
|
31 <section id="GUID-80DD2A3D-1C59-4AD5-8838-8DC9E1752729"><title>Architectural |
|
32 relationships</title> <p>The HTTP Client architecture provides a generalised |
|
33 mechanism for HTTP-like protocols that operate over various transports. Using |
|
34 a single API, a client can choose an HTTP protocol, encoding, and transport, |
|
35 and need not implement these in its own code. The default operation provides |
|
36 plain-text HTTP (as defined in RFC 2616) operating over a TCP/IP connection. |
|
37 This transport pipelines requests by default. </p> </section> |
|
38 <section id="GUID-4F83C7A0-C17F-4C58-840E-3E51EA52F098"><title>Description</title> <p>There |
|
39 are five key concepts used in the API: sessions, transactions, headers, data |
|
40 suppliers, and filters. </p><p><b>Sessions </b> </p> <p>A session encapsulates |
|
41 the client's HTTP activity over the duration of the client's execution. Typicallly, |
|
42 one HTTP session runs in one active scheduler. </p> <p> <b>Note:</b> An active |
|
43 scheduler must be installed when a session is opened. </p> <p>Usually, one |
|
44 session is used at a time. However, the client may use several concurrently, |
|
45 if required. Each session has an associated set of properties, which define |
|
46 the HTTP protocol, encoding, and transport used. Those properties apply to |
|
47 all HTTP transactions within the life of that session. The session also has |
|
48 an associated set of filters that provide additional automatic behaviours |
|
49 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 |
|
50 transaction represents an interaction between a HTTP client and an HTTP origin |
|
51 server. Normally a transaction consists of a single exchange of messages between |
|
52 client and server: a client request and a server response. However, the transaction |
|
53 may be extended or altered by filters that operate on it. See <xref href="GUID-AA2A730E-A7C9-5647-AD42-11C3BAF4C38D.dita">Filters</xref> for |
|
54 more details. </p> <p>Transactions execute asychronously within the client's |
|
55 process. The client is notified when events are available for each outstanding |
|
56 transaction. </p> <p>Both the request and response portion of a transaction |
|
57 consist of a header and an optional body. The request portion of the transaction |
|
58 also specifies an HTTP Method that describes the type of operation that the |
|
59 client wants to invoke at the origin server, together with a URI that specifies |
|
60 the resource held at the server on which the method is to be invoked. The |
|
61 response portion of a transaction contains an HTTP status code and message, |
|
62 which indicate the success of the method or the state of the resource following |
|
63 the method. The use of request and response bodies is determined by the HTTP |
|
64 method in use. For example, in error conditions, some servers may just return |
|
65 a status code and message, providing no entity body. </p> <p>The transaction |
|
66 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 |
|
67 header portion of requests and responses may have zero or more fields, which |
|
68 are used to convey information between the HTTP client and server. The information |
|
69 might relate to the data conveyed in body of the message, to the actual connection |
|
70 between the client and server, or might be used to convey data describing |
|
71 the client or server themselves. Typically, headers can contain content encoding |
|
72 and transfer encoding information. Since the HTTP API gives clients implementation |
|
73 independence from these choices, a generic form is used to represent header |
|
74 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 |
|
75 suppliers </b> </p> <p>The body portion of requests and responses is represented |
|
76 in the API as a mix-in interface, allowing the real implementation of the |
|
77 classes that generate body data to be fully hidden. The API enables signalling |
|
78 between the client and the transport in use, to ensure that body data is only |
|
79 used or released at a rate the client can support. This means that clients |
|
80 can assemble the body of their requests piece-by-piece, have each piece transmitted |
|
81 only when it is ready, and be signalled when transmission is complete so the |
|
82 next piece may be prepared and the old one released. </p> <p>Data supplier |
|
83 classes must implement <xref href="GUID-1B03F068-9552-37BA-A284-8E54FAC2AAC5.dita"><apiname>MHTTPDataSupplier</apiname></xref>. </p> <p><b>Filters </b> </p> <p>Filters |
|
84 are add-on modules that provide additional behaviours to a session beyond |
|
85 the simple request-response transaction described earlier. Behaviours may |
|
86 be triggered by the presence of particular headers in a request or a response, |
|
87 by status codes in a response, or by particular events that occur on a transaction. |
|
88 RFC 2616 describes a number of standard behaviours that occur over a series |
|
89 of request-response exchanges: client authentication, redirection, and caching. |
|
90 Client authentication and redirection are implemented as individual filters. </p> <p>Filter |
|
91 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> |
|
92 <section id="GUID-75720715-786A-4537-BC1B-949815E5E8AD"><title>Example code</title> <p>Example |
|
93 code used throughout this guide is taken from <filepath>HTTPEXAMPLECLIENT</filepath>, |
|
94 a simple console application that provides a menu-driven interface to the |
|
95 HTTP API. </p> </section> |
|
96 </conbody></concept> |