HTTP on Symbian OS

Reviewer Approved    
Contents
[hide]
 1 Purpose
 2 Architectural relationships
 3 Description
  3.1 Sessions
  3.2 Transactions
  3.3 Headers
  3.4 Data suppliers
  3.5 Filters
 4 External Links
 5 Internal Links

[edit] Purpose 目的

The HTTP 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
Please be noted that this HTTP Client API support starts from Symbian OS 7.0s and forward.
In another word, if you develop for devices such as Nokia N-Gage QD, you will do HTTP client business yourself from socket scratch.

HTTP客户端API提供Internet应用程序客户端接口，来使用HTTP协议在Internet上和HTTP服务器通信。
正确使用API使应用程序能够成为一个有条件兼容HTTP 1.1的客户端，就像在RFC 2616中定义的那样。
请注意这个HTTP客户端API从SYMBIAN OS 7.0之后开始支持。换句话说，如果你开发N-GAGE QD一类的设备，就要自己从SOCKET开始做HTTP客户端业务。

[edit] 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.
The client is not expected to implement anything else specific to those choices 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.

HTTP客户端架构为类似于HTTP在不同传输上操作的协议提供一般性机制。使用一个简单的API，一个客户端能选择一个HTTP协议，编码和传输。
客户端不被期待去在其代码中实现任何其他的指定的选项。默认操作提供在TCP/IP连接上的纯文本HTTP操作。这条传输管线默认是需要的。

[edit] Description

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

在API中使用了5个关键的概念：会话、事务、头、数据提供者 和 过滤器。

[edit] Sessions

A session encapsulates the client's HTTP activity over the duration of the client's execution.
Usually, one session is used at a time; however the client may use several concurrently if desired.
Each session has an associated set of properties, which define the HTTP protocol, encoding and transport that are used.
Those properties apply to all HTTP transactions carried out 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.

一个会话封装了客户端在其执行期间的HTTP活动。一般说来，一次只使用一个会话，但是如果需要，客户端可以同时使用几个。
每一个会话有一组关联的属性，定义了HTTP协议、使用的编码和传输。
这些属性在这个会话生命中实施到所有的HTTP事务中。这个会话也有一组关联的过滤器，提供在其客户端行为上额外的自动行为。
会话类由RHTTPSession. 提供

[edit] Transactions

A transaction represents an interaction between the 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 by filters that operate on it.
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 are composed 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 wishes 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;
e.g. in error conditions, some servers may just return a status code and message, providing no entity body.
The transaction class is provided by RHTTPTransaction.

一个事务代表在HTTP原始服务器和客户端之间的一次互动行为。一般的，一个事务包含了在客户端和服务器间的单个交换消息：一个客户端请求和服务器响应。
但是，事务可能被操作在其上的过滤器扩展。事务在客户端进程中异步的执行。当每个发生的事务事件可用时，客户端被通知。
一个会话的请求和响应部分都由一个头和可选的体组成。会话的请求部分也指定一个HTTP方法，描述客户端希望如何请求原始服务器的操作类型。
响应部分包含一个HTTP状态码和消息，指出方法成功或者资源的状态。请求和响应的正文部分的用途由使用的HTTP方法决定。
比如：在错误的情况下，某些服务器可能只返回状态码和消息，而不提供正文。事务类由RHTTPTransaction.提供。

[edit] 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.
Headers as transmitted to or received from the HTTP server will be in an encoded form, according to the HTTP protocol and encoding that are used.
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.

请求或响应的头可能是0或者多个字段，用来在HTTP客户端和服务器间传达消息。这些信息可能和转达的正文和消息相关，或者和客户端同服务器的实际连接有关，
或者和服务器或客户端自身有关，从服务器收发的头会以编码的形式存在，这同HTTP协议和编码方式有关。
因为HTTP api 使得客户端实现独立于这些选项，API中使用一个一般的形式表达头。头类由RHTTPHeaders. 提供。

[edit] 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 wholly hidden.
The API enables signalling between the client and the transport in use,
to ensure that body data is only consumed or emitted 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.

请求和响应的正文部分以混合接口在API中表现。允许真正实现产生正文的类完全隐藏。
这个API使得客户端和正在使用的传输之间能够互传信号，以确保正文数据只在客户端支持的速率上消费或发出。
这意味着客户端可以一片片的组装他们请求的正文，只有准备好才会发送每一片，并当传出完成后发出信号。
数据提供者类必须实现MHTTPDataSupplier.

[edit] Filters 过滤器

Filters are add-on modules that provide additional behaviours to a session beyond the simple request-response transaction described above.
 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.
The RFC 2616 describes a number of standard behaviours that take place over a series of request-response exchanges: client authentication, redirection and caching.
Client authentication and redirection are implemented as individual filters in the 7.0 release.
Since the representation of headers is generic, as described in Headers, filters may be implemented in a protocol- and transport-independent manner.
Filter classes must implement MHTTPFilter.

过滤器是额外的模块，在简单的请求-响应事务之上提供附加的行为。行为可以被请求或响应中特定的头的出现触发，或被一个响应的状态码触发，或被事务中发生的特定事件触发。
RFC 2616描述了一些标准的行为，在一系列请求响应交换中发生：客户端验证、重定向和缓存。
客户端验证和重定向在7.0中作为独立的过滤器实现。因为头部的描述是一般性的，就像HEADER中描述的，过滤器将被实现在一个协议中 - 并且以独立于传输的方式。
过滤器类必须实现MHTTPFilter.

[edit] External Links
Hypertext Transfer Protocol -- HTTP/1.1