htformat.h

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

*/

extern HTCoder HTIdentityCoding;

/*
(
  The HTCoding Object
)

The HTCoding object represents a registered encoding together with
a encoder and a decoder.
*/

typedef struct _HTCoding HTCoding;

/*

Predefined Coding Types We have a set of pre defined atoms for various types
of content encodings and transfer encodings. "chunked" is not exactly in
the same group as the other encodings such as "binary" but it really doesn't
make any difference as it is just a matter of how the words are chosen. The
first three transfer encodings are actually not encodings - they are just
left overs from brain dead mail systems.
*/

#define WWW_CODING_7BIT		HTAtom_for("7bit")
#define WWW_CODING_8BIT		HTAtom_for("8bit")
#define WWW_CODING_BINARY	HTAtom_for("binary")
#define WWW_CODING_IDENTITY     HTAtom_for("identity")

#define WWW_CODING_BASE64	HTAtom_for("base64")
#define WWW_CODING_MACBINHEX	HTAtom_for("macbinhex")
#define WWW_CODING_CHUNKED	HTAtom_for("chunked")

#define WWW_CODING_COMPRESS	HTAtom_for("compress")
#define WWW_CODING_GZIP	        HTAtom_for("gzip")
#define WWW_CODING_DEFLATE      HTAtom_for("deflate")

/*
(
  Register Content Coders
)

Some documents are not send in their original data obejct but is encoded
in some way. On the Web this is mostly some kind of compression but other
encodings for example base 64 can be encountered when talking to NNTP servers
etc. Just as for the other preferences, an application can register a supported
encoders or decodes as a list. Encoders and decoders are registered in the
same way with no differentiation whether it is a encoder or a decoder:
*/

extern BOOL HTCoding_add (HTList * 	list,
			 const char *	encoding,
			 HTCoder *	encoder,
			 HTCoder *	decoder,
			 double		quality);

extern void HTCoding_deleteAll (HTList * list);

extern const char * HTCoding_name (HTCoding * me);

extern double HTCoding_quality (HTCoding * me);

/*
.
  Content Charsets
.

As the Web reaches all parts of the Internet there are more and more documents
written in languages which contains characters not included in the ISO-8859-1
character set. A consequence of this the set of characters sets is often
tightly connected with the natural language. libwww does not directly support
other character sets but in case an application is capable of handling
alternative sets it can register these as preferred character sets along
with a quality factor just as all the other preferences in this section.
*/
extern void HTCharset_add (HTList * list, const char * charset, double quality);

/*
*/
typedef struct _HTAcceptNode {
    HTAtom *	atom;
    double	quality;
} HTAcceptNode;

/*
*/

extern void HTCharset_deleteAll	(HTList * list);

/*
.
  Content Languages
.

The preferred natural language or languages is in almost all situations dependent
on the individual user and an application should therefore give the user
the opportunity to change the setup. When specifying a natural language
preference, libwww will send this preference along with all HTTP requests.
The remote server will then (it if supports this feature) look for a version
in the language or languages mentioned. If it finds a matching document then
it returns this one, otherwise it uses the best alternative. If no language
is specified the remote server may whatever version it finds.
*/
extern void HTLanguage_add (HTList * list, const char * lang, double quality);
extern void HTLanguage_deleteAll (HTList * list);

/*
.
  Global Preferences
.

There are two places where these preferences can be registered: in a
global list valid for all requests and a local list
valid for a particular request only. These are valid for all requests.
See the Request Manager fro local sets.
(
  Global Converters and Presenters
)

The global list of specific conversions which the format manager
can do in order to fulfill the request. There is also a
local list of conversions which contains
a generic set of possible conversions.
*/
extern void HTFormat_setConversion	(HTList * list);
extern HTList * HTFormat_conversion	(void);

extern void HTFormat_addConversion (const char *	input_format,
				    const char *	output_format,
				    HTConverter *	converter,
				    double		quality,
				    double		secs, 
				    double		secs_per_byte);

/*
(
  Global Content Codings
)
*/
extern void HTFormat_setContentCoding	(HTList * list);
extern HTList * HTFormat_contentCoding	(void);

extern BOOL HTFormat_addCoding ( char *		encoding,
				 HTCoder *	encoder,
				 HTCoder *	decoder,
				 double		quality);

/*

We also define a macro to find out whether a content encoding is really an
encoding or whether it is a unity encoder.
*/

#define HTFormat_isUnityContent(me) \
	((me)==NULL || \
	(me)==WWW_CODING_BINARY || (me)==WWW_CODING_IDENTITY || \
        (me)==WWW_CODING_7BIT || (me)==WWW_CODING_8BIT)

/*
(
  Global Transfer Codings
)
*/
extern void HTFormat_setTransferCoding	(HTList * list);
extern HTList * HTFormat_transferCoding	(void);

extern BOOL HTFormat_addTransferCoding ( char *		encoding,
					 HTCoder *	encoder,
					 HTCoder *	decoder,
					 double		quality);

/*

We also define a macro to find out whether a transfer encoding is really
an encoding or whether it is just a "dummy" as for example 7bit, 8bit, and
binary.
*/

#define HTFormat_isUnityTransfer(me) \
	((me)==NULL || \
	 (me)==WWW_CODING_BINARY || (me)==WWW_CODING_IDENTITY || \
         (me)==WWW_CODING_7BIT || (me)==WWW_CODING_8BIT)

/*
(
  Global Content Languages
)
*/
extern void HTFormat_setLanguage	(HTList * list);
extern HTList * HTFormat_language	(void);

/*
(
  Global Content Charsets
)
*/
extern void HTFormat_setCharset		(HTList * list);
extern HTList * HTFormat_charset	(void);

/*
(
  Delete All Global Lists
)

This is a convenience function that might make life easier.
*/
extern void HTFormat_deleteAll (void);

/*
.
  The Content Type Stream Stack
.

This is the routine which actually sets up the content type conversion. It
currently checks only for direct conversions, but multi-stage conversions
are forseen. It takes a stream into which the output should be sent in the
final format, builds the conversion stack, and returns a stream into which
the data in the input format should be fed. If guess is true
and input format is www/unknown, try to guess the format by
looking at the first few bytes of the stream.
*/

extern HTStream * HTStreamStack (HTFormat	rep_in,
				 HTFormat	rep_out,
				 HTStream *	output_stream,
				 HTRequest *	request,
				 BOOL		guess);

/*
(
  Cost of a Stream Stack
)

Must return the cost of the same stack which HTStreamStack would set up.
*/

extern double HTStackValue	(HTList *	conversions,
				 HTFormat	format_in,
				 HTFormat	format_out,
				 double		initial_value,
				 long int	length);

/*
.
  Content Encoding Stream Stack
.

When creating a coding stream stack, it is important that we keep the right
order of encoders and decoders. As an example, the HTTP spec specifies that
the list in the Content-Encoding header follows the order in which
the encodings have been applied to the object. Internally, we represent the
content encodings as atoms in a linked
list object.

The creation of the content coding stack is not based on quality factors
as we don't have the freedom as with content types. When using content codings
we must apply the codings specified or fail.
*/

extern HTStream * HTContentCodingStack (HTEncoding	coding,
					HTStream *	target,
					HTRequest *	request,
					void *		param,
					BOOL		encoding);

/*

Here you can provide a complete list instead of a single token. The list
has to be filled up in the order the _encodings_ are to be applied
*/

extern HTStream * HTContentEncodingStack (HTList *	encodings,
					  HTStream *	target,
					  HTRequest *	request,
					  void *	param);

/*

Here you can provide a complete list instead of a single token. The list
has to be in the order the _encodings_ were applied - that is, the same way
that _encodings_ are to be applied. This is all consistent with the order
of the Content-Encoding header.
*/

extern HTStream * HTContentDecodingStack (HTList *	encodings,
					  HTStream *	target,
					  HTRequest *	request,
					  void *	param);

/*
.
  Transfer Encoding Stream Stack
.

When creating a coding stream stack, it is important that we keep the right
order of encoders and decoders. As an example, the HTTP spec specifies that
the list in the Transfer-Encoding header follows the order in which
the encodings have been applied to the object. Internally, we represent the
content encodings as atoms in a linked
list object.

The creation of the content coding stack is not based on quality factors
as we don't have the freedom as with content types. When using content codings
we must apply the codings specified or fail.
*/

extern HTStream * HTTransferCodingStack (HTEncoding	coding,
					 HTStream *	target,
					 HTRequest *	request,
					 void *		param,
					 BOOL		encoding);

/*

Here you can provide a complete list instead of a single token. The list
has to be filled up in the order the _encodings_ are to be applied
*/

extern HTStream * HTTransferEncodingStack (HTList *	encodings,
					   HTStream *	target,
					   HTRequest *	request,
					   void *	param);

/*

Here you can provide a complete list instead of a single token. The list
has to be in the order the _encodings_ were applied - that is, the same way
that _encodings_ are to be applied. This is all consistent with the order
of the Transfer-Encoding header.
*/

extern HTStream * HTTransferDecodingStack (HTList *	encodings,
					  HTStream *	target,
					  HTRequest *	request,
					  void *	param);

/*
.
  Transfer Encoding Stream Stack
.

Creating the transfer content encoding stream stack is not based on quality
factors as we don't have the freedom as with content types. Specify whether
you you want encoding or decoding using the BOOL "encode" flag.
*/

extern HTStream * HTContentTransferCodingStack (HTEncoding	encoding,
					        HTStream *	target,
					        HTRequest *	request,
					        void *		param,
					        BOOL		encode);

/*
(
  Presentation Object
)

This object is not to be used - it should have been hidden 
*/
typedef struct _HTPresentation {
    HTFormat	rep;			     /* representation name atomized */
    HTFormat	rep_out;			 /* resulting representation */
    HTConverter *converter;	      /* The routine to gen the stream stack */
    char *	command;			       /* MIME-format string */
    char *	test_command;			       /* MIME-format string */
    double	quality;		     /* Between 0 (bad) and 1 (good) */
    double	secs;
    double	secs_per_byte;
} HTPresentation;

/*
*/

#endif /* HTFORMAT */

/*

  

  @(#) $Id: HTFormat.html,v 2.85 2000/12/18 17:00:56 kahan Exp $

*/