/* ** (c) COPYRIGHT CERN 1994. ** Please first read the full copyright statement in the file COPYRIGH. */This module keeps a list of valid protocol (naming scheme) specifiers with associated access code. It allows documents to be loaded given various combinations of parameters. New access protocols may be registered at any time.
Note: HTRequest defined and request parameter added to almost all calls 18 Nov 1993.
This module is implemented by HTAccess.c, and it is a part of the Library of Common Code.
The module contains a lot of stuff but the main topics are:
#ifndef HTACCESS_H #define HTACCESS_H #include "HTList.h" #include "RoverBuffer.h"
extern BOOL HTLibInit NOPARAMS; extern BOOL HTLibTerminate NOPARAMS;
typedef enum { METHOD_INVALID = 0, METHOD_GET = 1, METHOD_HEAD, METHOD_POST, METHOD_PUT, METHOD_DELETE, METHOD_CHECKOUT, METHOD_CHECKIN, METHOD_SHOWMETHOD, METHOD_LINK, METHOD_UNLINK, MAX_METHODS } HTMethod;
extern HTMethod HTMethod_enum PARAMS((char * name));
extern char * HTMethod_name PARAMS((HTMethod method));
extern BOOL HTMethod_inList PARAMS((HTMethod method, HTList * list));
typedef struct _HTRequest HTRequest; typedef struct _HTNetInfo HTNetInfo; /* ** Callback to a protocol module */ typedef int (*HTLoadCallBack) PARAMS((HTRequest * req)); #include "HTAnchor.h" #include "HTFormat.h"
struct _HTNetInfo { SOCKFD sockfd; /* Socket descripter */ SockA sock_addr; /* SockA is defined in tcp.h */ HTInputSocket * isoc; /* Input buffer */ HTStream * target; /* Output stream */ RoverBuffer * transmit; /* Line to be send */ int addressCount; /* Attempts if multi-homed host */ time_t connecttime; /* Used on multihomed hosts */ struct _HTRequest * request; /* Link back to request structure */ int state; /* Private client state */ };Note: The AddressCount varaible is used to count the number of attempt to connect to a multi-homed host so we know when to stop trying new IP-addresses.
Note 1: There is also a global list of converters
Note 2: If you reuse the request structure for more than one request then make sure that the request is re-initialized, so that no `old' data is reused, see functions to manipulate HTRequest Structure. The library handles its own internal information from request to request but the information set by the caller is untouched.
The elements of the request structure are as follows.
struct _HTRequest {
HTMethod method;An enum used to specify the HTTP method used. The default value is
GET
HTList * conversions;NULL, or a list of conversions which the format manager can do in order to fulfill the request. It typically points to a list set up an initialisation time for example by HTInit().
HTList * encodings;The list of encodings acceptable in the output stream.
HTList * languages;The list of (human) language values acceptable in the response. The default is all languages.
BOOL (* callback ) PARAMS((struct _HTRequest* request, void *param));A function to be called back in the event that a file has been saved to disk by HTSaveAndCallBack for example.
void * context;An arbitrary pointer passed to HTAccess and passed back as a parameter to the callback .
HTStream* output_stream;The output stream to be used to put data down to as they come in from the network. The default value is
NULL
which means that the stream
goes to the user (display).
HTStream* output_flush;All object bodies sent from the server with status codes different from
200 OK
will be put down this stream. This can be
used as a debug window etc. If the value is NULL (default) then the
stream used is HTBlackHole.
HTAtom * output_format;The output format of the stream. This can be used to get unconverted data etc. from the library. If
NULL
, then WWW_PRESENT is
default value.
BOOL BlockingIO;This flag can be set to override if a protocol module is registered as using non-blocking IO.
HTParentAnchor *parentAnchor;If this parameter is set then a `Referer: <parent address> is generated in the request to the server, see Referer field in a HTTP Request
HTParentAnchor* anchor;The anchor for the object in question. Set immediately by HTAcesss. Used by the protocol and parsing modules. Valid thoughout the access.
HTChildAnchor * childAnchor; /* For element within the object */The anchor for the sub object if any. The object builder should ensure that htis is selected, highlighted, etc when the object is loaded.
void * using_cache;Pointer to cache element if cache hit
BOOL error_block; /* YES if stream has been used */ HTList * error_stack; /* List of errors */
HTNetInfo * net_info; /* Information about socket etc. */ int redirections; /* Number of redirections */
char * redirect; /* Location or URI */ char * WWWAAScheme; /* WWW-Authenticate scheme */ char * WWWAARealm; /* WWW-Authenticate realm */ char * WWWprotection; /* WWW-Protection-Template */
HTAtom * content_type; /* Content-Type: */ HTAtom * content_language;/* Language */ HTAtom * content_encoding;/* Encoding */ int content_length; /* Content-Length: */ HTInputSocket * isoc; /* InputSocket object for reading */ char * authorization; /* Authorization: field */
HTList * valid_schemes; /* Valid auth.schemes */ char * authenticate; /* WWW-authenticate: field */ char * prot_template; /* WWW-Protection-Template: field */ char * dialog_msg; /* Authentication prompt (client) */
#ifdef ROVER char * post_content_type; /* Type of post data */ char * post_content; /* Data to be posted */ #endif /* ROVER */
#ifdef ROVER int noretry; /* No immediate retry */ #endif /* ROVER */
#ifdef ROVER int compress; /* Compression level (0-9) */ #endif /* ROVER */
#ifdef ROVER int batch; /* Batched request indicator */ #endif /* ROVER */ };
extern HTRequest * HTRequest_new NOPARAMS;
extern void HTRequest_delete PARAMS((HTRequest * req));
extern void HTRequest_clear PARAMS((HTRequest * req));
BOOL
, that is
YES
or NO
. Insted they have been replaced
with the following set of return codes defined in the Utility module:
There are also some functions to help the client getting started with
the first URI.
Load a document from relative name
extern int HTLoadRelative PARAMS((CONST char * relative_name, HTParentAnchor* here, HTRequest * request));
extern int HTLoadAbsolute PARAMS((CONST char * addr, HTRequest * request));
extern int HTLoadToStream PARAMS((CONST char * addr, BOOL filter, HTRequest * request));
extern int HTLoadAnchor PARAMS((HTAnchor * a, HTRequest * request)); extern int HTLoadAnchorRecursive PARAMS((HTAnchor * a, HTRequest * request));
If keep_error_stack
is YES then the error (or info) stack
is not cleared from the previous call.
extern int HTLoad PARAMS((HTRequest * request, BOOL keep_error_stack));
extern BOOL HTLoadTerminate PARAMS((HTRequest * request, int status));
extern int HTSearch PARAMS((CONST char * keywords, HTParentAnchor* here, HTRequest * request));
extern int HTSearchAbsolute PARAMS((CONST char * keywords, CONST char * indexname, HTRequest * request));
HTAccessInit()
if not defined
NO_INIT
Each of these routine takes as a parameter a request structure containing details of the request. When the protocol class routine is called, the anchor element in the request is already valid (made valid by HTAccess).
typedef enum _HTSocBlock { SOC_BLOCK, SOC_NON_BLOCK } HTSocBlock; typedef struct _HTProtocol { char * name; HTSocBlock block; int (*load) PARAMS((HTRequest * request)); HTStream* (*saveStream) PARAMS((HTRequest * request)); HTStream* (*postStream) PARAMS((HTRequest * request, HTParentAnchor* postTo)); } HTProtocol; extern BOOL HTRegisterProtocol PARAMS((HTProtocol * protocol)); extern void HTDisposeProtocols NOPARAMS;
YES
or
NO
. If the Library is run in NON-INTERACTIVE MODE then
the function always returns YES;
extern BOOL HTProtocolBlocking PARAMS((HTRequest * request)); /* ** Helpful macros */ #ifndef FREE #define FREE(x) if (x) {free(x); x=NULL;} #endif /* FREE */end
#ifdef WWWLIB_SIG extern void HTSetSignal NOPARAMS; #endif
#endif /* HTACCESS_H */end of HTAccess