libsablot/src/engine/shandler.h

   1 /*
   2  * The contents of this file are subject to the Mozilla Public
   3  * License Version 1.1 (the "License"); you may not use this file
   4  * except in compliance with the License. You may obtain a copy of
   5  * the License at http://www.mozilla.org/MPL/
   6  *
   7  * Software distributed under the License is distributed on an "AS
   8  * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
   9  * implied. See the License for the specific language governing
  10  * rights and limitations under the License.
  11  *
  12  * The Original Code is the Sablotron XSLT Processor.
  13  *
  14  * The Initial Developer of the Original Code is Ginger Alliance Ltd.
  15  * Portions created by Ginger Alliance are Copyright (C) 2000-2002
  16  * Ginger Alliance Ltd. All Rights Reserved.
  17  *
  18  * Contributor(s):
  19  *
  20  * Alternatively, the contents of this file may be used under the
  21  * terms of the GNU General Public License Version 2 or later (the
  22  * "GPL"), in which case the provisions of the GPL are applicable
  23  * instead of those above.  If you wish to allow use of your
  24  * version of this file only under the terms of the GPL and not to
  25  * allow others to use your version of this file under the MPL,
  26  * indicate your decision by deleting the provisions above and
  27  * replace them with the notice and other provisions required by
  28  * the GPL.  If you do not delete the provisions above, a recipient
  29  * may use your version of this file under either the MPL or the
  30  * GPL.
  31  */
  32
  33 #ifndef ShandlerHIncl
  34 #define ShandlerHIncl
  35
  36 /* we have to deal with the size_t type, sys/types.h;
  37    is needed on some platforms */
  38 #if !defined(_MSC_VER)
  39 #include <sabcfg.h>
  40 #endif
  41
  42 #include <stddef.h>
  43
  44 /* GP: clean */
  45
  46 /*****************************************************************
  47
  48   handler types
  49
  50 *****************************************************************/
  51
  52 typedef enum
  53 {
  54     HLR_MESSAGE = 0,
  55     HLR_SCHEME,
  56     HLR_SAX,
  57     HLR_MISC,
  58     HLR_ENC
  59 } HandlerType;
  60
  61 extern const char* hlrTypeNames[]; /* found in base.cpp */
  62
  63 typedef enum
  64 {
  65     SH_ERR_OK = 0,
  66     SH_ERR_NOT_OK = 1,
  67     SH_ERR_UNSUPPORTED_SCHEME
  68 } SchemeHandlerErrors;
  69
  70 /*****************************************************************
  71 SchemeHandler
  72
  73   is a structure for a scheme handler. It contains pointers to
  74   the following functions of the handler:
  75         open(), get(), put(), close().
  76   All of these function return an error flag (0=OK, 1=not).
  77   open() may also return SH_ERR_UNSUPPORTED_SCHEME.
  78 *****************************************************************/
  79
  80 /*  getAll: open the URI and return the whole string
  81         scheme = URI scheme (e.g. "http")
  82         rest = the rest of the URI (without colon)
  83         the document is returned in a handler-allocated buffer
  84         byteCount holds the byte count on return
  85         return *buffer = NULL if not processed
  86 */
  87 typedef int SchemeHandlerGetAll(void *userData, SablotHandle processor_,
  88     const char *scheme, const char *rest,
  89     char **buffer, int *byteCount);
  90
  91 /*  freeMemory: free the buffer allocated by getAll
  92 */
  93
  94 typedef int SchemeHandlerFreeMemory(void *userData, SablotHandle processor_,
  95     char *buffer);
  96
  97 /*  open: open the URI and return a handle
  98         scheme = URI scheme (e.g. "http")
  99         rest = the rest of the URI (without colon)
 100         the resulting handle is returned in '*handle'
 101 */
 102 typedef int SchemeHandlerOpen(void *userData, SablotHandle processor_,
 103     const char *scheme, const char *rest, int *handle);
 104
 105 /*  get: retrieve data from the URI
 106         handle = the handle assigned on open
 107         buffer = pointer to the data
 108         *byteCount = number of bytes to read
 109             (the number actually read is returned here)
 110 */
 111 typedef int SchemeHandlerGet(void *userData, SablotHandle processor_,
 112     int handle, char *buffer, int *byteCount);
 113
 114 /*  put: save data to the URI (if possible)
 115         handle = the handle assigned on open
 116         buffer = pointer to the data
 117         *byteCount = number of bytes to write
 118             (the number actually written is returned here)
 119 */
 120 typedef int SchemeHandlerPut(void *userData, SablotHandle processor_,
 121     int handle, const char *buffer, int *byteCount);
 122
 123 /*  close: close the URI with the given handle
 124         handle = the handle assigned on open
 125 */
 126 typedef int SchemeHandlerClose(void *userData, SablotHandle processor_,
 127     int handle);
 128
 129 typedef struct
 130 {
 131     SchemeHandlerGetAll *getAll;
 132     SchemeHandlerFreeMemory *freeMemory;
 133     SchemeHandlerOpen *open;
 134     SchemeHandlerGet *get;
 135     SchemeHandlerPut *put;
 136     SchemeHandlerClose *close;
 137 } SchemeHandler;
 138
 139 /*****************************************************************
 140 MessageHandler
 141
 142   a structure for external message handlers. Such a handler, if set,
 143   receives all error reports, displays them, keeps the log, the
 144   error trace, etc.
 145 *****************************************************************/
 146
 147 /*
 148    define the "facility number" for Sablotron. This does not mean much
 149    nowadays.
 150 */
 151
 152 #define MH_FACILITY_SABLOTRON 2
 153
 154 /* type for the error codes used by the message handler */
 155
 156 typedef unsigned long MH_ERROR;
 157
 158 /* logging levels for the message handler */
 159
 160 typedef enum
 161 {
 162     MH_LEVEL_DEBUG,
 163     MH_LEVEL_INFO,
 164     MH_LEVEL_WARN,
 165     MH_LEVEL_ERROR,
 166     MH_LEVEL_CRITICAL
 167 } MH_LEVEL;
 168
 169 /*
 170    makeCode()
 171    makes the "external" error code to report with log() or error()
 172    call with facility = module id; severity = 1 iff critical.
 173    'code' is the error code internal to Sablotron.
 174 */
 175
 176 typedef MH_ERROR
 177 MessageHandlerMakeCode(
 178     void *userData, SablotHandle processor_,
 179     int severity, unsigned short facility, unsigned short code);
 180
 181 /*
 182    log()
 183    pass code created by makeCode, level as necessary
 184    fields is a NULL-terminated list of strings in form "field:contents"
 185    distinguished fields include: msg, file, line, token
 186 */
 187
 188 typedef MH_ERROR
 189 MessageHandlerLog(
 190     void *userData, SablotHandle processor_,
 191     MH_ERROR code, MH_LEVEL level, char **fields);
 192
 193 /*
 194    error()
 195    for reporting errors, meaning as with log()
 196 */
 197
 198 typedef MH_ERROR
 199 MessageHandlerError(void *userData, SablotHandle processor_,
 200     MH_ERROR code, MH_LEVEL level, char **fields);
 201
 202 /* the message handler structure. Use SablotRegMessageHandler() to register. */
 203
 204 typedef struct
 205 {
 206     MessageHandlerMakeCode *makeCode;
 207     MessageHandlerLog *log;
 208     MessageHandlerError *error;
 209 } MessageHandler;
 210
 211
 212
 213
 214
 215 /*
 216
 217                 SAXHandler
 218     a SAX-like, streaming interface for access to XML docs
 219
 220 */
 221
 222
 223 #define SAX_RETURN void
 224
 225 typedef SAX_RETURN
 226 SAXHandlerStartDocument(void* userData, SablotHandle processor_);
 227
 228 typedef SAX_RETURN
 229 SAXHandlerStartElement(void* userData, SablotHandle processor_,
 230     const char* name, const char** atts);
 231
 232 typedef SAX_RETURN
 233 SAXHandlerEndElement(void* userData, SablotHandle processor_,
 234     const char* name);
 235
 236 typedef SAX_RETURN
 237 SAXHandlerStartNamespace(void* userData, SablotHandle processor_,
 238     const char* prefix, const char* uri);
 239
 240 typedef SAX_RETURN
 241 SAXHandlerEndNamespace(void* userData, SablotHandle processor_,
 242     const char* prefix);
 243
 244 typedef SAX_RETURN
 245 SAXHandlerComment(void* userData, SablotHandle processor_,
 246     const char* contents);
 247
 248 typedef SAX_RETURN
 249 SAXHandlerPI(void* userData, SablotHandle processor_,
 250     const char* target, const char* contents);
 251
 252 typedef SAX_RETURN
 253 SAXHandlerCharacters(void* userData, SablotHandle processor_,
 254     const char* contents, int length);
 255
 256 typedef SAX_RETURN
 257 SAXHandlerEndDocument(void* userData, SablotHandle processor_);
 258
 259
 260 /*
 261     The SAX handler structure. Use SablotRegSAXHandler() to register.
 262 */
 263
 264
 265 typedef struct
 266 {
 267     SAXHandlerStartDocument     *startDocument;
 268     SAXHandlerStartElement      *startElement;
 269     SAXHandlerEndElement        *endElement;
 270     SAXHandlerStartNamespace    *startNamespace;
 271     SAXHandlerEndNamespace      *endNamespace;
 272     SAXHandlerComment           *comment;
 273     SAXHandlerPI                *processingInstruction;
 274     SAXHandlerCharacters        *characters;
 275     SAXHandlerEndDocument       *endDocument;
 276 } SAXHandler;
 277
 278
 279 /*****************************************************************
 280 MiscHandler
 281
 282   Collects miscellaneous callbacks.
 283 *****************************************************************/
 284
 285 /*
 286     documentInfo()
 287     If set, this callback gets called after the output of a result
 288     document is finished, giving information about its content type
 289     and encoding.
 290 */
 291
 292 typedef void
 293 MiscHandlerDocumentInfo(void* userData, SablotHandle processor_,
 294     const char *contentType, const char *encoding);
 295
 296 /*
 297     The Misc handler structure.
 298     Use SablotRegHandler(HLR_MISC, ...) to register.
 299 */
 300
 301 typedef struct
 302 {
 303     MiscHandlerDocumentInfo     *documentInfo;
 304 } MiscHandler;
 305
 306 /*****************************************************************
 307 EncHandler
 308
 309   Handler for recoding requests in absence of iconv.
 310 *****************************************************************/
 311
 312 #define EH_FROM_UTF8 1
 313 #define EH_TO_UTF8 0
 314
 315 /*
 316     the conversion descriptor like iconv_t
 317 */
 318
 319 typedef void* EHDescriptor;
 320
 321 typedef enum
 322 {
 323     EH_OK,
 324     EH_EINVAL,
 325     EH_E2BIG,
 326     EH_EILSEQ
 327 } EHResult;
 328
 329 /*
 330     open()
 331     direction is either EH_FROM_UTF8 or EH_TO_UTF8
 332     encoding is the other encoding
 333     RETURN the descriptor, or -1 if the encoding is not supported
 334 */
 335
 336 typedef EHDescriptor EncHandlerOpen(void* userData, SablotHandle processor_,
 337     int direction, const char *encoding);
 338
 339 /*
 340     conv()
 341     arguments 3 through 7 are just like for iconv, see the manpage
 342     RETURN -1 on error (set errno), a different value (e.g. 0) if OK
 343 */
 344
 345 typedef EHResult EncHandlerConv(void* userData, SablotHandle processor_,
 346     EHDescriptor cd, const char** inbuf, size_t *inbytesleft,
 347     char ** outbuf, size_t *outbytesleft);
 348
 349 /*
 350     close()
 351     cd is the descriptor to close. Return 0 if OK, -1 on error.
 352 */
 353
 354 typedef int EncHandlerClose(void* userData, SablotHandle processor_,
 355     EHDescriptor cd);
 356
 357 /*
 358     The EncHandler structure.
 359     Use SablotRegHandler(HLR_ENC, ...) to register.
 360 */
 361
 362 typedef struct
 363 {
 364     EncHandlerOpen      *open;
 365     EncHandlerConv      *conv;
 366     EncHandlerClose     *close;
 367 } EncHandler;
 368
 369 #endif