htreq.h

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

extern BOOL HTRequest_addRange       (HTRequest * request,
                                      char * unit, char * range);
extern BOOL HTRequest_deleteRangeAll (HTRequest * request);
extern HTAssocList * HTRequest_range (HTRequest * request);

/*
.
  HTTP Connection Control Request Directives
.

The connection control directives are all part of the connection header and
control the behavior of this connection. This association list is a list
of the connection control directives that are to be sent as part of the
Connection header.
*/

extern BOOL HTRequest_addConnection        (HTRequest * request,
                                            char * token, char * value);
extern BOOL HTRequest_deleteConnection     (HTRequest * request);
extern HTAssocList * HTRequest_connection  (HTRequest * request);

/*
.
  HTTP Access Authentication Credentials
.

When a access denied response is returned to the Library, for example from
a remote HTTP server, this code is passed back to the application. The
application can then decide whether a new request should be established or
not. These two methods return the authentication information required to
issue a new request, that is the new anchor and any list of keywords associated
with this anchor.
*/

extern BOOL HTRequest_addCredentials       (HTRequest * request,
                                            char * token, char * value);
extern BOOL HTRequest_deleteCredentialsAll (HTRequest * request);
extern HTAssocList * HTRequest_credentials (HTRequest * request);

/*
(
  Realms
)

The realm is normally set and used by the authentication filters.
*/

extern BOOL HTRequest_setRealm (HTRequest * request, char * realm);
extern const char * HTRequest_realm (HTRequest * request);
extern BOOL HTRequest_deleteRealm (HTRequest * me);

/*
.
  HTTP Referer Field
.

If this parameter is set then a `Referer: <parent address> can be generated
in the request to the server, see
Referer field in a HTTP Request
*/

extern void HTRequest_setParent (HTRequest *request, HTParentAnchor *parent);
extern HTParentAnchor * HTRequest_parent (HTRequest *request);

/*
.
  Local BEFORE and AFTER Filters
.

The request object may have it's own before and after
filters. These may override or suplement the
global set in HTNet. The request object itself handles
the list element, that is this should not be freed bu the caller.
(
  BEFORE Filters
)

The BEFORE filters are called just after the
request has been passed to the Library but before any request is issued over
the network. A BEFORE can infact stop a request completely from being processed.

  Add a local BEFORE Filter


You can add a local BEFORE filter for a single request so that the
both the local and global BEFORE filters are called or you can replace
the global filters with a local set. Note that the local set can be NULL.
This can be used to effectively disable all BEFORE filters without
unregistering the global ones.
*/

extern BOOL HTRequest_addBefore (HTRequest * request, HTNetBefore * filter,
				 const char * tmplate, void * param,
                                 HTFilterOrder order, BOOL override);
extern HTList * HTRequest_before (HTRequest * request, BOOL * override);

/*

  Delete a Local BEFORE Filter


You can delete a local BEFORE filter explicitly by passing the filter itself
or you can delete all filters which are registered for a certain status code.
*/
extern BOOL HTRequest_deleteBefore (HTRequest * request, HTNetBefore * filter);
extern BOOL HTRequest_deleteBeforeAll (HTRequest * request);

/*
(
  AFTER Filters
)

You can add a local AFTER filter for a single request so that the both the
local and global AFTER filters are called or you can replace the global filters
with a local set. Note that the local set can be NULL. This can be used to
effectively disable all AFTER filters without unregistering the global ones.

AFTER filters can be registered to handle a certain set of return values
from the protocol modules, for example explicitly to handle redirection,
authentication, etc. You can find all the available codes in the HTNet object
description.

  Add a local AFTER Filter

*/

extern BOOL HTRequest_addAfter (HTRequest * request, HTNetAfter * filter,
				const char * tmplate, void * param,
                                int status, HTFilterOrder order,
                                BOOL override);
extern HTList * HTRequest_after (HTRequest * request, BOOL * override);

/*

  Delete an AFTER Filter


You can delete a local AFTER filter explicitly by passing the filter itself
or you can delete all filters which are registered for a certain status code.
*/

extern BOOL HTRequest_deleteAfter (HTRequest * request, HTNetAfter * filter);
extern BOOL HTRequest_deleteAfterStatus (HTRequest * request, int status);
extern BOOL HTRequest_deleteAfterAll (HTRequest * request);

/*
.
  Sending data from App to Network
.

Multiple Request objects can be connected in order to create a
PostWeb for sending data
from one location (source) to another (destination). Request objects are
bound together by connecting the output stream of the source with the input
stream of the destination requst. The connection can be done directly so
that the output from the source is exactly what is sent to the destination
or there can be a conversion between the two streams so that we can do
conversions on the fly while copying data. This is in fact the way we use
for building a proxy server.

The Library supports two ways of posting a data object to a remote destination:
Input comes from a socket descriptor or from memory. In the case where you
want to copy a URL, for example from local file system or
from a remote HTTP server then you must use the
PostWeb design. This model
operates by using at least two request objects which gets linked to eachother
as part of the PostWeb model. However, if you are posting from memory, we
only use one request object to perform the operation. In order to
do this, the application must register a callback function that can be called
when the HTTP client module is ready for accepting data.
be included as part of the body and/or as extra metainformation. In the latter
case you need to register a callback function of the following type using
the methods provided in the next section.
*/

typedef int HTPostCallback (HTRequest * request, HTStream * target);

extern void HTRequest_setPostCallback (HTRequest * request, HTPostCallback * cbf);
extern HTPostCallback * HTRequest_postCallback (HTRequest * request);

/*

The Entity Anchor is either the anchor directly associated with the Request
object or the post anchor associated with the object. The purpose of the
entity anchor is if we are to send data to a remote server then we get the
metainformation using the entity anchor.
*/

extern BOOL HTRequest_setEntityAnchor (HTRequest * request, HTParentAnchor * anchor);
extern HTParentAnchor * HTRequest_entityAnchor (HTRequest * request);

/*
(
  Input Stream
)

The input stream is to be used to put data to the network. Normally
each protocol sets the input stream in order to generate the protocol headers
while making a request.
*/

extern void HTRequest_setInputStream (HTRequest * request, HTStream * input);
extern HTStream *HTRequest_inputStream (HTRequest * request);

/*
(
  Is This Request part of a Post Web? (Deprecated)
)

Check to see if this request object is part of a Post Web.
*/

extern BOOL HTRequest_isPostWeb (HTRequest * request);

/*
(
  Source of a Request
)

A request may have a source in which is another request object that as output
stream has the input stream of this request object.
*/

extern BOOL HTRequest_setSource (HTRequest * request, HTRequest * source);
extern HTRequest * HTRequest_source (HTRequest * request);

/*
.
  Streams From Network to Application
.
(
  Default Output Stream
)

The output stream is to be used to put data down to as they come in
from the network and back to the application. The default value is
NULL which means that the stream goes to the user (display).
*/

extern void HTRequest_setOutputStream (HTRequest *request, HTStream *output);
extern HTStream *HTRequest_outputStream (HTRequest *request);

/*
(
  Default Output Stream Format
)

The desired format of the output stream. This is used in the
stream stack builder to determine which stream
to plug in to deal with the data. If NULL, then
WWW_PRESENT is default value.
*/

extern void HTRequest_setOutputFormat (HTRequest *request, HTFormat format);
extern HTFormat HTRequest_outputFormat (HTRequest *request);

/*
(
  Has Output Stream been Connected to Channel? (Deprecated)
)

Has output stream been connected to the channel? If not then we must free
it explicitly when deleting the request object
*/
extern void HTRequest_setOutputConnected (HTRequest * request, BOOL mode);
extern BOOL HTRequest_outputConnected	 (HTRequest * request);

/*
(
  Default Debug Stream
)

All object bodies sent from the server with status codes different from
200 OK will be put down this stream. This can be used for
redirecting body information in status codes different from "200 OK" to for
example a debug window. If the value is NULL (default) then the stream is
not set up.
*/

extern void HTRequest_setDebugStream (HTRequest *request, HTStream *debug);
extern HTStream *HTRequest_debugStream (HTRequest *request);

/*
(
  Default Debug Stream Format
)

The desired format of the error stream. This can be used to get unconverted
data etc. from the library. The default value if WWW_HTML as
a character based only has one WWW_PRESENT.
*/

extern void HTRequest_setDebugFormat (HTRequest *request, HTFormat format);
extern HTFormat HTRequest_debugFormat (HTRequest *request);

/*
.
  Context Swapping
.

In multi threaded applications it is often required to keep track of the
context of a request so that when the Library returns a result of a request,
it can be put into the context it was in before the request was first passed
to the Library. This call back function allows the application to do this.
*/

typedef int HTRequestCallback (HTRequest * request, void *param);

extern void HTRequest_setCallback (HTRequest *request, HTRequestCallback *cb);
extern HTRequestCallback *HTRequest_callback (HTRequest *request);

/*

The callback function can be passed an arbitrary pointer (the void part)
which can describe the context of the current request structure. If such
context information is required then it can be set using the following methods:
*/

extern void HTRequest_setContext (HTRequest *request, void *context);
extern void *HTRequest_context (HTRequest *request);

/*
.
  Should we Issue a full HTTP Request-URI?
.

In early versions of HTTP, the request sent to the remote server varies whether
we use a proxy or go directly to the origin server. The default value is
OFF but we use a full request if we are talking to a proxy server.
*/

extern void HTRequest_setFullURI (HTRequest *request, BOOL mode);
extern BOOL HTRequest_fullURI (HTRequest *request);

/*
.
  Handling Proxies
.

In case we are using a proxy for this requst then we can register it together
with the request object. That way we can find the proxy and look for
authentication information, for example in the
Authentication filter. The string is freed by
the Request object on deletion. This is normally handled automatically by
the proxy and gateway module
*/

extern BOOL HTRequest_setProxy    (HTRequest * request, const char * proxy);
extern char * HTRequest_proxy     (HTRequest * request);
extern BOOL HTRequest_deleteProxy (HTRequest * request);

/*
.
Message Body Manipulation
.

An application may use these functions to set and manipulate the request
message body.  This message body is specially indicate for methods that use
small XML message bodies. Once the application defines it, this message body
will be send just after the headers. It  does not use
"Expect: 100-continue" header, and the application
should not try to use both.  It's important to remark that
"Expect: 100-continue" header is a very importante feature defined in HTTP.
It's prevents that, for example, the server must read many unnecessary bytes
from request body. Using "Expect: 100-continue" header, your application
safes time and network (see 
RFC2616, section 8.2.3).
Please, if possible, use always HTRequest Entity and entity callback, leave
this only for small XML bodies in extension methods (see 
HTMethod), and when using it, be very
careful!

When using a message body, the application may define its length and
format. If the message body is set and its length is also set and it greater
than 0, a Content-Lenght header will be added to the request. Similarly, if 
the message body and its type are set, a Content-Type header will be added 
to the request too. Otherwise, those headers will not be included.

Note: The caller should free the string returned by
HTRequest_messageBody function!
*/

extern BOOL HTRequest_setMessageBody (HTRequest * request, const char * body);
extern BOOL HTRequest_deleteMessageBody (HTRequest * request);
extern char * HTRequest_messageBody (HTRequest * request);

extern BOOL HTRequest_setMessageBodyLength (HTRequest * request, long int length);
extern long int HTRequest_messageBodyLength (HTRequest * request);

extern BOOL HTRequest_setMessageBodyFormat (HTRequest * request, HTFormat format);
extern HTFormat HTRequest_messageBodyFormat (HTRequest * request);

/*

.
  Bytes Read or Written in a Request
.

This function returns the bytes read in the current request. For a deeper
description of what the current request is, please read the user's guide.
This function can be used in for example the HTAlert
module to give the number of bytes read or written in a progress message.
*/

extern long HTRequest_bodyRead (HTRequest * request);
extern long HTRequest_bodyWritten (HTRequest * request);

/*

You can also get the total number of bytes read or written including the
headers
*/

extern long HTRequest_bytesRead (HTRequest * request);
extern long HTRequest_bytesWritten (HTRequest * request);

/*
*/

#endif /* HTREQ_H */

/*

  

  @(#) $Id: HTReq.html,v 2.72 2002/06/04 15:14:11 kirschpi Exp $

*/