htaccess.h

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

/*

  
  					W3C Sample Code Library libwww Accessing URIs


!
  Accessing URIs
!
*/

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

/*

This module is the application interface module to the
Request class. It contains a lot of methods for
loading URIs and also for uploading URIs using PUT or
POST, for example. You can use the Request class directly but
this module makes it easier to use by providing a lot of small request functions
using the Request class in different ways. It contains help functions for
accessing documents and for uploading documents to a remote server.

This module contains functions for handling all HTTP/1.1 methods:

  
    GET Requests
  
    	 
	       o 
	 	Various GET requests including specialized functions like
	loading a rule file, etc.
      o 
	 	Search requests based on the GET method
      o 
	 	Formdata requests based on the GET method
    
	   
    PUT Requests
  
    	 
	       o 
	 	Save a document from memory ASIS using PUT
      o 
	 	Save a structured document from memory using PUT
      o 
	 	Save any URI (FTP, HTTP, local disk) using PUT
    
	   
    POST Requests
  
    	 
	       o 
	 	Post Formdata to a remote HTTP server
      o 
	 	Post a document from memory ASIS to a remote HTTP
	server
    
	   
    HEAD, DELETE, OPTIONS, and TRACE requests
  
    	 
	       o 
	 	Get metainformation about a document using HEAD requests
      o 
	 	Delete documents based on the DELETE method
      o 
	 	Get information about the features supoprted by a resource
	using OPTIONS
      o 
	 	Trace a request using the TRACE method
    
	 

Furthermore, it contains a few access methods for handling
incoming requests - in orther words acting as a server. Although libwww
is primarily for clients, it is in fact symmetric in that it can handle both
client requests and server requests.

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

#ifndef HTACCESS_H
#define HTACCESS_H

#include "HTReq.h"
#include "HTAnchor.h"

/*
.
  Load a Document (Method = GET)
.

URIs can be accesses using a character string, for example
"http://www.w3.org" or it can be accessed by using the libwww
representation of a URI called an Anchor object.
Note that we call all objects accessible through URIs for documents
- this is a notion we have inherited from the hypertext world.
(
  Load a Document from Absolute URI
)

Request a document referencd by an absolute URI. The output from the
request is passed to the Stream Pipe Manager
that figures out where to pump the data. This can for example be to the display
or to a local file depending on the set of
converters registered by the application.
*/
extern BOOL HTLoadAbsolute (const char * url, HTRequest * request);

/*
(
  Load a Document from Relative URI
)

Request a document referenced by a relative URI. The relative URI
is made absolute by resolving it relative to the address of the 'base'
anchor.
*/
extern BOOL HTLoadRelative (const char * 	relative,
			    HTParentAnchor *	base,
			    HTRequest *		request);

/*
(
  Load a Document into Memory
)

Request a document referred to by the URI and load it into a
HTChunk object. A chunk
object is a dynamic string so in the end you will have a single memory
buffer containing the document. The chunk must be freed by the caller.
*/
extern HTChunk * HTLoadToChunk (const char * url, HTRequest * request);

/*
(
  Load a Document and Save as a Local File
)

This function loads a URI and saves the contents in the specifed file. The
file should not  be open, as the load function both opens and closes
the file. If the file already exists then it asks the user whether the file
should be overwritten or not. the contents is saved ASIS - that is
- we do not touch the contents of the file!
*/

extern BOOL HTLoadToFile (const char * url, HTRequest * request,
			  const char * filename);

/*
(
  Load a Document and put the Contents into a Stream
)

Request a document referenced by an absolute URI and sending the data down
a stream. This stream can be anny stream you like, for eample one from the
Stream Interface.
*/

extern BOOL HTLoadToStream (const char * url, HTStream * output,
			    HTRequest * request);

/*
(
  Load a Document using an Anchor
)

Here the URI is represented by an Anchor object.
You can get an anchor object representing a URI by passing the URI to the
appropriate method in the Anchor class.
*/
extern BOOL HTLoadAnchor (HTAnchor * anchor, HTRequest * request);

/*
(
  Load a Document into Memory using an Anchor
)

This is the same as HTLoadToChunk but instead of passing a URI
string you pass an HTAnchor object. Internally,
all URIs are represented as anchors which contains all the information we
have about the resource. The chunk must be freed by the caller.
*/
extern HTChunk * HTLoadAnchorToChunk (HTAnchor * anchor, HTRequest * request);

/*
(
  Recursively Request a Document using Anchors
)

Same as HTLoadAnchor() but the information in the
error stack in the request
object is kept, so that any error messages in one. This function is almost
identical to HTLoadAnchor, but it doesn't clear the error stack
so that the information in there is kept.
*/
extern BOOL HTLoadAnchorRecursive (HTAnchor * anchor, HTRequest * request);

/*
.
  Load Special Documents
.

We also have a set of functions for loading special files like rules files
which also are referenced by a URI but which do have to be treated specially.
(
  Load a Rule File
)

Rule files can be loaded just like any other URI but you can also just use
these functions which do all the work for you: they load a rule find with
the URI specified and add the set of rules to the existing set.

They come in two flavours - one that asks the user whether it is OK to add
the rules and one that does it automatically without asking. As the app would
have to call this method explicitly, it may have other ways of protecting
the user.

Both functions use preemptive requests
so that everything else stops in the meantime.
*/

extern BOOL HTLoadRules (const char * url);
extern BOOL HTLoadRulesAutomatically (const char * url);

/*
.
  Search a Document (Method = GET)
.

The search methods all use GET as the method in the
HTTP request. The functions take
the keywords and encode them according to
RFC
1866 (Hypertext Markup language). That is, the query part is separated
from the rest of the URI by a "?".

The keywords are passed to the function as a Chunk
Object and each keyword must be separated by a space ' '. This
will then be converted into a '+' before added to the URI.
(
  Search a Document from Absolute URI
)
*/

extern BOOL HTSearchAbsolute (HTChunk *		keywords,
			      const char *	base,
			      HTRequest *	request);

/*
(
  Search a Document from Relative URI
)

Search a document referenced by a relative URI. The relative URI is
made absolute by resolving it relative to the address of the 'base'
anchor.
*/

extern BOOL HTSearchRelative (HTChunk *		keywords,
			      const char * 	relative,
			      HTParentAnchor *	base,
			      HTRequest *	request);

/*
(
  Search a Document using an Anchor
)
*/

extern BOOL HTSearchAnchor (HTChunk *		keywords,
			    HTAnchor *		anchor,
			    HTRequest * 	request);

/*
(
  Search a Document using an Anchor Using a String
)

This works exactly as the HTSearchAnchor() function but takes
a C string instead of a chunk object.
*/

extern BOOL HTSearchString (const char *	keywords,
			    HTAnchor *		anchor,
			    HTRequest * 	request);

/*
.
  Submit Forms Using GET Method
.

Formdata can be sent to an HTTP server in two ways - it can either use a
GET method or it can use a POST method. The difference
is whether the request "has side effects" or not. For example, if you are
ordering a pizza then the (hopefully positive) sideeffect is that you actually
get one delivered. However, if you are issuing search data - for example
to Alta Vista, then there is no sideeffect. In the former example you would
use the GET form and in the latter you would use the
POST form.
(
  Submit Form from Absolute URI using GET
)

Submit formdata using GET to the address indicated as the "base" which must
be an absolute URI. The list of form data must be given as an
association list where the name is the field name
and the value is the value of the field.
*/

extern BOOL HTGetFormAbsolute (HTAssocList *	formdata,
			       const char *	base,
			       HTRequest *	request);

/*
(
  Submit Form from Relative URI using GET
)

Submit formdata using GET to the address indicated relative to the address
of the base anchor. The list of form data must be given as an
association list where the name is the field name
and the value is the value of the field.
*/

extern BOOL HTGetFormRelative (HTAssocList * 	formdata,
			       const char * 	relative,
			       HTParentAnchor *	base,
			       HTRequest *	request);

/*
(
  Send a Form using an Anchor and the GET Method
)

Submit formdata using GET to the address indicated of the anchor. The list
of form data must be given as an association list
where the name is the field name and the value is the value of the field.
*/

extern BOOL HTGetFormAnchor (HTAssocList *	formdata,
			     HTAnchor *		anchor,
			     HTRequest * 	request);

/*
.
  Submit Forms Using POST Method
.

The data in a POST form is sent as the body part of the
HTTP message whereas a
GET form wraps it all up into the URI. In order to be able to
use the POST data object at a later point in time, we create
a new anchor on the fly. This anchor has a URI file location which points
into the temporary area given by the User Profile
Object. That is - you can actually save the anchor using a
PUT request and then be able to retrive the form data at a later
point in time. Even though this may seem "ambitious" for posting form data,
it is really just a special example of sending any kind of data to a remote
server. All POST form functions return the new anchor or
NULL if they fail.
(
  Submit Form from Absolute URI using POST
)

Submit formdata using POST to the address indicated as the "base" which must
be an absolute URI. The list of form data must be given as an
association list where the name is the field name
and the value is the value of the field.
*/

extern HTParentAnchor * HTPostFormAbsolute (HTAssocList *	formdata,
					    const char *	base,
					    HTRequest *	request);

/*
(
  Submit Form from a Relative URI using GET
)

Submit formdata using POST to the address indicated relative to the address
of the base anchor. The list of form data must be given as an association
list where the name is the field name and the value is the value of the field.
*/

extern HTParentAnchor * HTPostFormRelative (HTAssocList * 	formdata,
					    const char * 	relative,
					    HTParentAnchor *	base,
					    HTRequest *		request);

/*
(
  Submit Form using an Anchor and the POST Method
)

Submit formdata using POST to the address indicated of the anchor. The list
of form data must be given as an association list
where the name is the field name and the value is the value of the field.
*/

extern HTParentAnchor * HTPostFormAnchor (HTAssocList *	formdata,
					  HTAnchor *	anchor,
					  HTRequest * 	request);

/*
(
  Submit Form and Save the Result in a Memory Buffer
)

Submit formdata to the address referred to by the
HTAnchor object and load the result of the POST
into a HTChunk object. A
chunk object is a dynamic memory buffer so in
the end you will have a single memory buffer containing the document. The
chunk must be freed by the caller.
*/

extern HTChunk * HTPostFormAnchorToChunk (HTAssocList * formdata,
                                          HTAnchor *    anchor,
                                          HTRequest *   request);

/*
.
  Get Metainformation about a Document (Method = HEAD)
.

If you are not interested in the document itself but only in the
metainformation that describes the document then you should
use the HEAD method in your request.
(
  Get Metainformation about a Document from Absolute URI
)

Request metainfomration about a document referencd by an absolute
URI.
*/
extern BOOL HTHeadAbsolute (const char * url, HTRequest * request);

/*
(
  Get Metainformation about a Document from Relative URI
)

Request metainformation about a document referenced by a relative
URI.
*/
extern BOOL HTHeadRelative (const char * 	relative,
			    HTParentAnchor *	base,
			    HTRequest *		request);

/*
(
  Get Metainformation about a Document using an Anchor
)

Here the URI is represented by an Anchor object.
You can get an anchor object representing a URI by passing the URI to the
approproiate method in the Anchor class.
*/
extern BOOL HTHeadAnchor (HTAnchor * anchor, HTRequest * request);

/*