htreq.h

www工具包. 这是W3C官方支持的www支撑库. 其中提供通用目的的客户端的WebAPI: complete HTTP/1.1 (with caching, pipelining, PUT, POS

/*

  
  					W3C Sample Code Library libwww Request Class


!
  The Request Class
!
*/

/*
**	(c) COPYRIGHT MIT 1995.
**	Please first read the full copyright statement in the file COPYRIGH.
*/

/*

Libwww is based on a request/response paradigm and the Request class defines
"an operation to be performed on a URL". The request object is the
main entry point for an application to issue a request to the Library - all
operations on a URL must use a Request object. The request object
is application independent in that both servers and clients use the same
Request class. Examples of requests passed to the Library are a client
application issuing a GET request on a HTTP URL, or a server issuing
a load on a local file URL. The only difference is that the client gets the
input from a user whereas the server gets the input via the network.

A request object is created with a default set of parameters which are applicable
for many URL requests but the class defines a huge set of methods that an
be used to customize a request for a particular purpose. Example of things
that you can define is natural language, media types, what RFC 822 headers
to use, whether the request should be refreshed from cache etc. Scroll down
and see the set of parameters you can tune.

A request object is registered in the library by issuing an operation on
a URL - for example PUT, POST, or DELETE. You can find
many higher level "request issuing functions" in the
Access module - the methods defined by the Request
class itself are very low level but can of course be used directly if needed.

Whereas the lifetime of the URL (in form of an anchor) often is very long
(for example as long as the application is running), the lifetime of a request
is limited to the time it takes to service the request. The core does not
automatically delete any request object created by the application - it is
for the application to do. In many cases a request object can be deleted
when any of the termination callback functions
are called but the application may keep request objects around longer than
that

The Library can accept an unlimited number of simultaneous requests passed
by the application. One of the main functions of the Library core is to handle
any number of ongoing requests in an intelligent manner by limiting the number
of active request to the fit the available resources as defined by the
application. This is described in more detail in the HTNet
module.

This module is implemented by HTReqMan.c, and it
is a part of the  W3C Sample Code
Library.
*/

#ifndef HTREQ_H
#define HTREQ_H

typedef long HTRequestID;
typedef struct _HTRequest HTRequest;

#include "HTEvent.h"
#include "HTList.h"
#include "HTAssoc.h"
#include "HTFormat.h"
#include "HTStream.h"
#include "HTError.h"
#include "HTNet.h"
#include "HTUser.h"
#include "HTResponse.h"

/*
.
  Creation and Deletion Methods
.

The request object is intended to live as long as the request is still active,
but can be deleted as soon as it has terminated, for example in one of the
request termination callback functions as described in the
Net Manager. Only the anchor object stays around
after the request itself is terminated.
(
  Create new Object
)

Creates a new request object with a default set of options -- in most cases
it will need some information added which can be done using the methods in
this module, but it will work as is for a simple request.
*/

extern HTRequest * HTRequest_new (void);

/*
(
  Clear a Request Object
)

Clears all protocol specific information so that the request object can be
used for another request. It should be used with care as application specific
information is not re-initialized. Returns YES if OK, else NO.
*/

extern BOOL HTRequest_clear (HTRequest * me);

/*
(
  Create a duplicate
)

Creates a new HTRequest object as a duplicate of the src request. Returns
YES if OK, else NO
*/

extern HTRequest * HTRequest_dup (HTRequest * src);

/*

  Create a duplicate for Internal use


Creates a new HTRequest object as a duplicate of the src request. The difference
to the HTRequest_dup function is that we don't copy the error_stack and other
information that the application keeps in its copy of the request object.
Otherwise it will be freed multiple times. Returns YES if OK, else NO
*/

extern HTRequest * HTRequest_dupInternal (HTRequest * src);

extern BOOL HTRequest_setInternal (HTRequest * request, BOOL mode);
extern BOOL HTRequest_internal (HTRequest * request);

/*
(
  Delete Object
)

This function deletes the object and cleans up the memory.
*/

extern void HTRequest_delete (HTRequest * request);

/*
.
  Issuing a Request
.

These are the "basic request methods" provided directly by the Request
class. This is a very low level API as the caller must have set up the request
object before passing it to libwww. There are two versions: one for issuing
client requests and one for issuing server requests. You will probably most
often use the client version, but, in fact, libwww can also deal with incoming
connections. You can find many higher level issuing functions in the
HTAccess module. If you like, you can of course
use this directly!
*/

extern BOOL HTLoad (HTRequest * request, BOOL recursive);
extern BOOL HTServe(HTRequest * request, BOOL recursive);

/*
.
  Killing a Request
.

This function kills this particular request, see HTNet
module for a function that kills them all. If you know that you are
pipelining requests (typically the case for GUI browsers, robots etc.) then
it is often not enough to just kill a single request as the whole pipeline
gets affected. Therefore, in that case you MUST call the
HTHost_killPipe function instead,
*/

extern BOOL HTRequest_kill(HTRequest * request);

/*

Note that you can get to the HTHost object via the HTNet
object which you can get by calling
HTRequest_net(...).
.
  Relations to Other Libwww Objects
.

The Request object is linked to a set of other libwww objects - here's how
to get to these objects...
(
  Binding to an Anchor Object
)

Every request object has an anchor associated
with it. The anchor normally lives until the application terminates but a
request object only lives as long as the request is being serviced. If the
anchor that we have requested is a child anchor then we always load
the parent anchor; after the load jump to the location. A child anchor
is a an anchor which points to a subpart of the document (has a "#" in the
URL).
*/

extern void HTRequest_setAnchor (HTRequest *request, HTAnchor *anchor);
extern HTParentAnchor * HTRequest_anchor (HTRequest *request);

extern HTChildAnchor * HTRequest_childAnchor (HTRequest * request);

/*
(
  Binding to a User Profile
)

Each request is associated with a User profile
which contains information about the local host name, email address of the
user, news server etc. A request object is created with a default "generic
user" but can be assigned a specific user at any time.
*/

extern BOOL HTRequest_setUserProfile (HTRequest * request, HTUserProfile * up);
extern HTUserProfile * HTRequest_userProfile (HTRequest * request);

/*
(
  Binding to a Net Object
)

If a request is actually going on the net then the Net
Manager is contacted to handle the request. The Net manager creates a
HTNEt object and links it to the Request object. You can get to the HTNet
object using the following functions.
*/

extern HTNet * HTRequest_net (HTRequest * request);
extern BOOL HTRequest_setNet (HTRequest * request, HTNet * net);

/*

Note that you can go from the HTNet object to the
HTHost object by calling HTNet_host(...).
(
  Binding to a Response Object
)

If a request is actually going on the net and we are getting a response back
then we also create a HTResponse object and
bind it to the request object. Once we know what to do with the response,
we may transfer the information to the anchor object.
*/

extern HTResponse * HTRequest_response (HTRequest * request);
extern BOOL HTRequest_setResponse (HTRequest * request, HTResponse * response);

/*
.
  Set the Method for the Request
.

The Method is the operation to be executed on the requested object. The default
set if the set of operations defined by the HTTP protocol, that is "GET",
"HEAD", "PUT", "POST", "LINK", "UNLINK", and "DELETE" but many of these can
be used in other protocols as well. The important thing is to think of the
requested element as an object on which you want to perform an operation.
Then it is for the specific protocol implementation to try and carry this
operation out. However, not all operations can be implemented (or make sense)
in all protocols.

Methods are handled by the Method Module, and
the default value is "GET".
*/

extern void HTRequest_setMethod (HTRequest *request, HTMethod method);
extern HTMethod HTRequest_method (HTRequest *request);

/*
.
  Priority Management
.

The request can be assigned an initial priority which then gets inherited
by all HTNet objects and other requests objects
created as a result of this one. You can also assign a separate priority
to an indicidual HTNet object by using the methods in the
Net manager.
*/

extern HTPriority HTRequest_priority (HTRequest * request);
extern BOOL HTRequest_setPriority (HTRequest * request, HTPriority priority);

/*
.
  Pipelining Managament
.

Libwww supports HTTP/1.1 pipelining which greatly optimizes HTTP's behavior
over TCP. libwww also tries very hard to minimize the number of TCP packets
sent over the network. This is done by buffering outgoing requests until
either a minimum amount of data has been collected or a timeout causes a
flush to happen. The application can override the output buffering by explicit
request a request object to be flushed.
*/

extern BOOL HTRequest_setFlush (HTRequest * me, BOOL mode);
extern BOOL HTRequest_flush (HTRequest * me);

/*
(
  Force the Pipeline to be Flushed Immediately
)

Forcing a fluch immediatly is slightly different as this can be done in
"retrospect". That is, if suddenly the application decides on performing
a flush after the request was initiated then it can use this function to
flush at a later time.
*/

extern int HTRequest_forceFlush (HTRequest * request);

/*
.
  Dealing with Request Error Messages
.

Errors are, like almost anything,  kept in lists. An error list can be
associated with a request using the following functions. In order to make 
life easier, there are also some easy mapping functions to the
HTError object, so that you can add an error directly
to a request object.
*/

extern HTList * HTRequest_error (HTRequest * request);
extern void HTRequest_setError	(HTRequest * request, HTList * list);
extern void HTRequest_deleteAllErrors (HTRequest * request);

/*

These are the cover functions that go directly to the
Error Object
*/

extern BOOL HTRequest_addError (HTRequest * 	request,
				HTSeverity	severity,
				BOOL		ignore,
				int		element,
				void *		par,
				unsigned int	length,
				char *		where);

extern BOOL HTRequest_addSystemError (HTRequest * 	request,
				      HTSeverity 	severity,
				      int		errornumber,
				      BOOL		ignore,
				      char *		syscall);

/*
.
  Max number of Retrys for a Down Load
.

Automatic reload can happen in two situations:
	 
	   o 
	     The server sends a redirection response
	   o 
	     The document has expired
	 
	 
In order to avoid the Library going into an infinite loop, it is necessary
to keep track of the number of automatic reloads. Loops can occur if the
server has a reload to the same document or if the server sends back a Expires
header which has already expired. The default maximum number of automatic
reloads is 6.
*/

extern BOOL HTRequest_setMaxRetry (int newmax);
extern int  HTRequest_maxRetry (void);

extern int HTRequest_retrys (HTRequest * request);
extern BOOL HTRequest_doRetry (HTRequest *request);
extern BOOL HTRequest_addRetry (HTRequest * request);

extern int HTRequest_AAretrys (HTRequest * request);
extern BOOL HTRequest_addAARetry (HTRequest * request);

/*
.
  Set Max Forwards for TRACE methods
.

The TRACE method is used to invoke a remote, application-layer
loop-back of the request message. The final recipient of the request SHOULD
reflect the message received back to the client as the entity-body of a 200
(OK) response. The final recipient is either the origin server or the first
proxy or gateway to receive a Max-Forwards value of zero (0) in the request.
A TRACE request MUST NOT include an entity.
*/
extern BOOL HTRequest_setMaxForwards (HTRequest * request, int maxforwards);
extern int HTRequest_maxForwards (HTRequest * request);

/*
.
  Preemptive or Non-preemptive Access
.

An access scheme is defined with a default for using either preemptive (blocking
I/O) or non-preemptive (non-blocking I/O). This is basically a result of the
implementation of the protocol module itself. However, if non-blocking I/O
is the default then some times it is nice to be able to set the mode to blocking
instead. For example, when loading the first document (the home page),
blocking mode can be used instead of non-blocking.
*/

extern void HTRequest_setPreemptive (HTRequest *request, BOOL mode);
extern BOOL HTRequest_preemptive (HTRequest *request);

/*
.
  Content Negotiation
.

When accessing the local file system, the Library is capable of performing
content negotioation as described by the HTTP protocol. This is mainly for
server applications, but some client applications might also want to use
content negotiation when accessing the local file system. This method enables
or disables content negotiation - the default value is ON.
*/

extern void HTRequest_setNegotiation (HTRequest *request, BOOL mode);
extern BOOL HTRequest_negotiation (HTRequest *request);