htreq.h

www工具包

.

Should this request use preconditions when doing a PUT or a
POST? These are the "if-*" header fields that can be used
to avoid version conflicts etc. The default is not to use any preconsitions
(HT_NO_MATCH). The _THIS versions use etags and/or time
stamps and the _ANY versions use the "*" header field value
of the if-match and if-non-match header fields.
*/
typedef enum _HTPreconditions {
    HT_NO_MATCH = 0,
    HT_MATCH_THIS,
    HT_MATCH_ANY,
    HT_DONT_MATCH_THIS,
    HT_DONT_MATCH_ANY
} HTPreconditions;

extern void HTRequest_setPreconditions (HTRequest * me, HTPreconditions mode);
extern HTPreconditions HTRequest_preconditions (HTRequest * me);

/*
.
  Handling Metainformation (RFC822 Headers)
.

The Library supports a large set of headers that can be sent along with a
request (or a response for that matter). All headers can be either disabled
or enabled using bit flags that are defined in the following.
(
  General HTTP Header Mask
)

There are a few header fields which have general applicability for both request
and response mesages, but which do not apply to the communication parties
or theentity being transferred. This mask enables and disables these headers.
If the bit is not turned on they are not sent.
*/

typedef enum _HTGnHd {
    HT_G_CC             = 0x1,
    HT_G_CONNECTION	= 0x2,
    HT_G_DATE		= 0x4,
    HT_G_PRAGMA_NO_CACHE= 0x8,
    HT_G_FORWARDED	= 0x10,
    HT_G_MESSAGE_ID	= 0x20,
    HT_G_MIME		= 0x40,
    HT_G_TRAILER        = 0x80,
    HT_G_TRANSFER       = 0x100
} HTGnHd;

#define DEFAULT_GENERAL_HEADERS	\
        HT_G_CONNECTION + HT_G_CC + HT_G_TRANSFER + HT_G_TRAILER

extern void HTRequest_setGnHd (HTRequest *request, HTGnHd gnhd);
extern void HTRequest_addGnHd (HTRequest *request, HTGnHd gnhd);
extern HTGnHd HTRequest_gnHd (HTRequest *request);

/*
(
  Request Headers
)

The request header fields allow the client to pass additional information
about the request (and about the client itself) to the server. All headers
are optional but the default value is all request headers if present
except From and Pragma.
*/

typedef enum _HTRqHd {
    HT_C_ACCEPT_TYPE	= 0x1,
    HT_C_ACCEPT_CHAR	= 0x2,
    HT_C_ACCEPT_ENC	= 0x4,
    HT_C_ACCEPT_TE	= 0x8,
    HT_C_ACCEPT_LAN	= 0x10,
    HT_C_AUTH		= 0x20,             /* Includes proxy authentication */
    HT_C_EXPECT         = 0x40,
    HT_C_FROM		= 0x80,
    HT_C_HOST		= 0x100,
    HT_C_IMS		= 0x200,
    HT_C_IF_MATCH	= 0x400,
    HT_C_IF_MATCH_ANY	= 0x800,
    HT_C_IF_NONE_MATCH	= 0x1000,
    HT_C_IF_NONE_MATCH_ANY=0x2000,
    HT_C_IF_RANGE	= 0x4000,
    HT_C_IF_UNMOD_SINCE	= 0x8000,
    HT_C_MAX_FORWARDS	= 0x10000,
    HT_C_RANGE		= 0x20000,
    HT_C_REFERER	= 0x40000,
    HT_C_USER_AGENT	= 0x80000
} HTRqHd;

#define DEFAULT_REQUEST_HEADERS	\
	HT_C_ACCEPT_TYPE + HT_C_ACCEPT_CHAR + \
	HT_C_ACCEPT_ENC + HT_C_ACCEPT_TE + HT_C_ACCEPT_LAN + HT_C_AUTH + \
        HT_C_EXPECT + HT_C_HOST + HT_C_REFERER + HT_C_USER_AGENT

extern void HTRequest_setRqHd (HTRequest *request, HTRqHd rqhd);
extern void HTRequest_addRqHd (HTRequest *request, HTRqHd rqhd);
extern HTRqHd HTRequest_rqHd (HTRequest *request);

/*
(
  Response Headers
)

The response header fields allow the server to pass additional information
about the response (and about the server itself) to the client. All headers
are optional.
*/

typedef enum _HTRsHd {
    HT_S_AGE		= 0x1,
    HT_S_LOCATION   	= 0x2,
    HT_S_PROXY_AUTH 	= 0x4,
    HT_S_PUBLIC    	= 0x8,
    HT_S_RETRY_AFTER	= 0x10,
    HT_S_SERVER		= 0x20,
    HT_S_VARY		= 0x40,
    HT_S_WARNING	= 0x80,
    HT_S_WWW_AUTH	= 0x100,
    HT_S_TRAILER        = 0x200
} HTRsHd;

#define DEFAULT_RESPONSE_HEADERS HT_S_SERVER

extern void HTRequest_setRsHd (HTRequest * request, HTRsHd rshd);
extern void HTRequest_addRsHd (HTRequest * request, HTRsHd rshd);
extern HTRsHd HTRequest_rsHd (HTRequest * request);

/*
(
  Entity Header Mask
)

The entity headers contain information about the object sent in the HTTP
transaction. See the Anchor module, for the storage
of entity headers. This flag defines which headers are to be sent in a request
together with an entity body. All headers are optional but the default value
is ALL ENTITY HEADERS IF PRESENT
*/

typedef enum _HTEnHd {
    HT_E_ALLOW			= 0x1,
    HT_E_CONTENT_BASE		= 0x2,
    HT_E_CONTENT_ENCODING	= 0x4,
    HT_E_CONTENT_LANGUAGE	= 0x8,
    HT_E_CONTENT_LENGTH		= 0x10,
    HT_E_CONTENT_LOCATION	= 0x20,
    HT_E_CONTENT_MD5		= 0x40,
    HT_E_CONTENT_RANGE		= 0x80,
    HT_E_CTE			= 0x100,	/* Content-Transfer-Encoding */
    HT_E_CONTENT_TYPE		= 0x200,
    HT_E_DERIVED_FROM		= 0x400,
    HT_E_ETAG			= 0x800,
    HT_E_EXPIRES		= 0x1000,
    HT_E_LAST_MODIFIED		= 0x2000,
    HT_E_LINK			= 0x4000,
    HT_E_TITLE			= 0x8000,
    HT_E_URI			= 0x10000,
    HT_E_VERSION		= 0x20000
} HTEnHd;

#define DEFAULT_ENTITY_HEADERS		0xFFFF			      /* all */

extern void HTRequest_setEnHd (HTRequest *request, HTEnHd enhd);
extern void HTRequest_addEnHd (HTRequest *request, HTEnHd enhd);
extern HTEnHd HTRequest_enHd (HTRequest *request);

/*
.
  Local MIME header Parsers
.

MIMEParsers get their own type which is optimized for static and regex parser
strings.
*/

typedef struct _HTMIMEParseSet HTMIMEParseSet;
extern void HTRequest_setMIMEParseSet (HTRequest *request, 
				       HTMIMEParseSet * parseSet, BOOL local);
extern HTMIMEParseSet * HTRequest_MIMEParseSet (HTRequest *request,
					      BOOL * pLocal);

/*
.
  Accept Headers
.

The Accept family of headers is an important part of HTTP handling the format
negotiation. The Library supports both a global set of accept headers that
are used in all HTTP requests and a local set of accept headers
that are used in specific requests only. The global ones are defined in the
Format Manager.

Each request can have its local set of accept headers that either are added
to the global set or replaces the global set of accept headers. Non of the
headers have to be set. If the global set is sufficient for all
requests then this us perfectly fine. If the parameter "override" is set
then only local accept headers are used, else both local and global
headers are used.
(
  Content Types
)

The local list of specific conversions which the format manager
can do in order to fulfill the request. It typically points to a list set
up on initialisation time for example by HTInit().
There is also a global list of
conversions which contains a generic set of possible conversions.
*/

extern void HTRequest_setConversion (HTRequest *request, HTList *type, BOOL override);
extern HTList * HTRequest_conversion (HTRequest *request);

/*
(
  Content Encodings
)

The list of encodings acceptable in the output stream.
*/

extern void HTRequest_setEncoding (HTRequest *request, HTList *enc, BOOL override);
extern HTList * HTRequest_encoding (HTRequest *request);

/*
(
  Transfer Encodings
)

The list of transfer encodings acceptable in the output stream.
*/

extern void HTRequest_setTransfer (HTRequest *request, HTList *te, BOOL override);
extern HTList * HTRequest_transfer (HTRequest *request);

/*
(
  Content Languages
)

The list of (human) language values acceptable in the response. The default
is all languages.
*/

extern void HTRequest_setLanguage (HTRequest *request, HTList *lang, BOOL override);
extern HTList * HTRequest_language (HTRequest *request);

/*
(
  Content Charsets
)

The list of charsets accepted by the application
*/

extern void HTRequest_setCharset (HTRequest *request, HTList *charset, BOOL override);
extern HTList * HTRequest_charset (HTRequest *request);

/*
.
  HTTP Cache Validation and Cache Control
.

The Library has two concepts of caching: in memory and on file. When loading
a document, this flag can be set in order to define who can give a response
to the request. The mempory buffer is considered to be equivalent to a history
buffer. That is, it doesn't not follow the same expiration mechanism that
is characteristic for a persistent file cache.

You can also set the cache to run in disconnected mode - see the
Cache manager for more details on how to do this.
*/

typedef enum _HTReload {
    HT_CACHE_OK	            = 0x0,	        /* Use any version available */
    HT_CACHE_FLUSH_MEM	    = 0x1,	/* Reload from file cache or network */
    HT_CACHE_VALIDATE	    = 0x2,	             /* Validate cache entry */
    HT_CACHE_END_VALIDATE   = 0x4,                  /* End to end validation */
    HT_CACHE_RANGE_VALIDATE = 0x8,
    HT_CACHE_FLUSH	    = 0x10,                     /* Force full reload */
    HT_CACHE_ERROR          = 0x20         /* An error occurred in the cache */
} HTReload;

extern void HTRequest_setReloadMode (HTRequest *request, HTReload mode);
extern HTReload HTRequest_reloadMode (HTRequest *request);

/*
(
  HTTP Cache Control Directives
)

The cache control directives are all part of the cache control header and
control the behavior of any intermediate cache between the user agent and
the origin server. This association list is a list of the connection control
directives that are to be sent as part of the Cache-Control
header.
*/

extern BOOL HTRequest_addCacheControl        (HTRequest * request,
                                              char * token, char *value);
extern BOOL HTRequest_deleteCacheControlAll  (HTRequest * request);
extern HTAssocList * HTRequest_cacheControl  (HTRequest * request);

/*
(
  HTTP Expect Directives
)

The Expect request-header field is used to indicate that particular server
behaviors are required by the client. A server that does not understand or
is unable to comply with any of the expectation values in the Expect field
of a request MUST respond with appropriate error status.
*/

extern BOOL HTRequest_addExpect (HTRequest * me,
				 char * token, char * value);
extern BOOL HTRequest_deleteExpect (HTRequest * me);
extern HTAssocList * HTRequest_expect (HTRequest * me);

/*
(
  Partial Requests and Range Retrievals
)

Libwww can issue range requests in case we have already obtained a part of
the entity body. Since all HTTP entities are represented in HTTP messages
as sequences of bytes, the concept of a byte range is meaningful for any
HTTP entity. (However, not all clients and servers need to support byte-range
operations.) Byte range specifications in HTTP apply to the sequence of bytes
in the entity-body (not necessarily the same as the message-body). A byte
range operation may specify a single range of bytes, or a set of ranges within
a single entity.
*/

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 Extensions (PEP)
.

HTTP can be extended in several ways but traditionally it has been by using
new headers. Here we present a new idea which provides a framework for describing
extensions and their scope. This is only an idea an may be modified later!
The implementation of the extensions can be found in the
PEP module
(
  Protocol
)

This association list is a list of the extension directives that are to be
sent as part of the request.
*/

extern BOOL HTRequest_addProtocol       (HTRequest * request,
                                         char * token, char * value);
extern BOOL HTRequest_deleteProtocolAll (HTRequest * request);