git.maemo.org Git - xmlrpc-c/blob - include/xmlrpc-c/abyss.h

   1 /*****************************************************************************
   2                                  abyss.h
   3 ******************************************************************************
   4
   5   This file is the interface header for the Abyss HTTP server component of
   6   XML-RPC For C/C++ (Xmlrpc-c).
   7
   8   The Abyss component of Xmlrpc-c is based on the independently developed
   9   and distributed Abyss web server package from 2001.
  10
  11   Copyright information is at the end of the file.
  12 ****************************************************************************/
  13
  14 #ifndef _ABYSS_H_
  15 #define _ABYSS_H_
  16
  17
  18 #ifdef __cplusplus
  19 extern "C" {
  20 #endif
  21
  22 #include <sys/types.h>
  23
  24 #ifdef WIN32
  25 #include "xmlrpc_config.h"
  26 #else
  27 #include <inttypes.h>
  28 #endif
  29
  30 /****************************************************************************
  31   STUFF FOR THE OUTER CONTROL PROGRAM TO USE
  32 ****************************************************************************/
  33
  34 typedef int abyss_bool;
  35
  36 /*********************************************************************
  37 ** MIMEType
  38 *********************************************************************/
  39
  40 typedef struct MIMEType MIMEType;
  41
  42 MIMEType *
  43 MIMETypeCreate(void);
  44
  45 void
  46 MIMETypeDestroy(MIMEType * const MIMETypeP);
  47
  48 void
  49 MIMETypeInit(void);
  50
  51 void
  52 MIMETypeTerm(void);
  53
  54 abyss_bool
  55 MIMETypeAdd2(MIMEType *   const MIMETypeP,
  56              const char * const type,
  57              const char * const ext);
  58
  59 abyss_bool
  60 MIMETypeAdd(const char * const type,
  61             const char * const ext);
  62
  63
  64 enum abyss_foreback {ABYSS_FOREGROUND, ABYSS_BACKGROUND};
  65
  66
  67 typedef struct _TSocket TSocket;
  68
  69 /* TOsSocket is the type of a conventional socket offered by our OS.
  70    This is for backward compatibility; everyone should use TSocket
  71    sockets today.
  72 */
  73 #ifdef WIN32
  74 void
  75 SocketWinCreate(TSocket ** const socketPP);
  76
  77 void
  78 SocketWinCreateWinsock(SOCKET     const winsock,
  79                        TSocket ** const socketPP);
  80
  81 typedef SOCKET TOsSocket;
  82
  83 #else  /* WIN32 */
  84
  85 void
  86 SocketUnixCreate(TSocket ** const socketPP);
  87
  88 void
  89 SocketUnixCreateFd(int        const fd,
  90                    TSocket ** const socketPP);
  91
  92 typedef int TOsSocket;
  93 #endif  /* WIN32 */
  94
  95 void
  96 SocketDestroy(TSocket * const socketP);
  97
  98
  99 typedef struct {
 100     /* Before Xmlrpc-c 1.04, the internal server representation,
 101        struct _TServer, was exposed to users and was the only way to
 102        set certain parameters of the server.  Now, use the (new)
 103        ServerSet...() functions.  Use the HAVE_ macros to determine
 104        which method you have to use.
 105     */
 106     struct _TServer * srvP;
 107 } TServer;
 108
 109 typedef struct _TSession TSession;
 110
 111 abyss_bool
 112 ServerCreate(TServer *    const serverP,
 113              const char * const name,
 114              uint16_t     const port,
 115              const char * const filespath,
 116              const char * const logfilename);
 117
 118 abyss_bool
 119 ServerCreateSocket(TServer *    const serverP,
 120                    const char * const name,
 121                    TOsSocket    const socketFd,
 122                    const char * const filespath,
 123                    const char * const logfilename);
 124
 125 #define HAVE_SERVER_CREATE_SOCKET_2
 126 void
 127 ServerCreateSocket2(TServer *     const serverP,
 128                     TSocket *     const socketP,
 129                     const char ** const errorP);
 130
 131 abyss_bool
 132 ServerCreateNoAccept(TServer *    const serverP,
 133                      const char * const name,
 134                      const char * const filespath,
 135                      const char * const logfilename);
 136
 137 void
 138 ServerFree(TServer * const serverP);
 139
 140 void
 141 ServerSetName(TServer *    const serverP,
 142               const char * const name);
 143
 144 void
 145 ServerSetFilesPath(TServer *    const serverP,
 146                    const char * const filesPath);
 147
 148 void
 149 ServerSetLogFileName(TServer *    const serverP,
 150                      const char * const logFileName);
 151
 152 #define HAVE_SERVER_SET_KEEPALIVE_TIMEOUT 1
 153 void
 154 ServerSetKeepaliveTimeout(TServer * const serverP,
 155                           uint32_t  const keepaliveTimeout);
 156
 157 #define HAVE_SERVER_SET_KEEPALIVE_MAX_CONN 1
 158 void
 159 ServerSetKeepaliveMaxConn(TServer * const serverP,
 160                           uint32_t  const keepaliveMaxConn);
 161
 162 #define HAVE_SERVER_SET_TIMEOUT 1
 163 void
 164 ServerSetTimeout(TServer * const serverP,
 165                  uint32_t  const timeout);
 166
 167 #define HAVE_SERVER_SET_ADVERTISE 1
 168 void
 169 ServerSetAdvertise(TServer *  const serverP,
 170                    abyss_bool const advertise);
 171
 172 #define HAVE_SERVER_SET_MIME_TYPE 1
 173 void
 174 ServerSetMimeType(TServer *  const serverP,
 175                   MIMEType * const MIMETypeP);
 176
 177 void
 178 ServerInit(TServer * const serverP);
 179
 180 void
 181 ServerRun(TServer * const serverP);
 182
 183 void
 184 ServerRunOnce(TServer * const serverP);
 185
 186 /* ServerRunOnce2() is obsolete.  See user's guide. */
 187 void
 188 ServerRunOnce2(TServer *           const serverP,
 189                enum abyss_foreback const foregroundBackground);
 190
 191 void
 192 ServerRunConn(TServer * const serverP,
 193               TOsSocket const connectedSocket);
 194
 195 #define HAVE_SERVER_RUN_CONN_2
 196 void
 197 ServerRunConn2(TServer *     const serverP,
 198                TSocket *     const connectedSocketP,
 199                const char ** const errorP);
 200
 201 void
 202 ServerDaemonize(TServer * const serverP);
 203
 204 void
 205 ServerTerminate(TServer * const serverP);
 206
 207 void
 208 ServerResetTerminate(TServer * const serverP);
 209
 210 void
 211 ServerUseSigchld(TServer * const serverP);
 212
 213 #ifndef WIN32
 214 void
 215 ServerHandleSigchld(pid_t const pid);
 216 #endif
 217
 218 typedef abyss_bool (*URIHandler) (TSession *); /* deprecated */
 219
 220 struct URIHandler2;
 221
 222 typedef void (*initHandlerFn)(struct URIHandler2 *,
 223                               abyss_bool *);
 224
 225 typedef void (*termHandlerFn)(void *);
 226
 227 typedef void (*handleReq2Fn)(struct URIHandler2 *,
 228                              TSession *,
 229                              abyss_bool *);
 230
 231 typedef struct URIHandler2 {
 232     initHandlerFn init;
 233     termHandlerFn term;
 234     handleReq2Fn  handleReq2;
 235     URIHandler    handleReq1;  /* deprecated */
 236     void *        userdata;
 237 } URIHandler2;
 238
 239 void
 240 ServerAddHandler2(TServer *     const srvP,
 241                   URIHandler2 * const handlerP,
 242                   abyss_bool *  const successP);
 243
 244 abyss_bool
 245 ServerAddHandler(TServer * const srvP,
 246                  URIHandler const handler);
 247
 248 void
 249 ServerDefaultHandler(TServer *  const srvP,
 250                      URIHandler const handler);
 251
 252 /* This is inappropriately named; it was a mistake.  But then, so is
 253    having this function at all.  The config file is inappropriate for
 254    an API.
 255 */
 256 abyss_bool
 257 ConfReadServerFile(const char * const filename,
 258                    TServer *    const srvP);
 259
 260 void
 261 LogWrite(TServer *    const srvP,
 262          const char * const c);
 263
 264 /****************************************************************************
 265   STUFF FOR URI HANDLERS TO USE
 266 ****************************************************************************/
 267
 268 typedef enum {
 269     m_unknown, m_get, m_put, m_head, m_post, m_delete, m_trace, m_options
 270 } TMethod;
 271
 272 typedef struct {
 273     TMethod method;
 274     const char * uri;
 275         /* This is NOT the URI.  It is the pathname part of the URI.
 276            We really should fix that and put the pathname in another
 277            member.
 278         */
 279     const char * query;
 280         /* The query part of the URI (stuff after '?') */
 281     const char * host;
 282         /* NOT the value of the host: header.  Rather, the name of the
 283            target host (could be part of the host: value).  No port number.
 284         */
 285     const char * from;
 286     const char * useragent;
 287     const char * referer;
 288     const char * requestline;
 289     const char * user;
 290     unsigned short port;
 291     abyss_bool keepalive;
 292 } TRequestInfo;
 293
 294 abyss_bool
 295 SessionRefillBuffer(TSession * const sessionP);
 296
 297 size_t
 298 SessionReadDataAvail(TSession * const sessionP);
 299
 300 void
 301 SessionGetReadData(TSession *    const sessionP,
 302                    size_t        const max,
 303                    const char ** const outStartP,
 304                    size_t *      const outLenP);
 305
 306 void
 307 SessionGetRequestInfo(TSession *            const sessionP,
 308                       const TRequestInfo ** const requestInfoPP);
 309
 310 char *
 311 RequestHeaderValue(TSession * const sessionP,
 312                    char *     const name);
 313
 314 abyss_bool
 315 ResponseAddField(TSession *   const sessionP,
 316                  const char * const name,
 317                  const char * const value);
 318
 319 void
 320 ResponseWriteStart(TSession * const sessionP);
 321
 322 /* For backward compatibility: */
 323 #define ResponseWrite ResponseWriteStart
 324
 325 abyss_bool
 326 ResponseWriteBody(TSession *   const sessionP,
 327                   const char * const data,
 328                   uint32_t     const len);
 329
 330 abyss_bool
 331 ResponseWriteEnd(TSession * const sessionP);
 332
 333 abyss_bool
 334 ResponseChunked(TSession * const sessionP);
 335
 336 uint16_t
 337 ResponseStatusFromErrno(int const errnoArg);
 338
 339 void
 340 ResponseStatus(TSession * const sessionP,
 341                uint16_t   const code);
 342
 343 void
 344 ResponseStatusErrno(TSession * const sessionP);
 345
 346 abyss_bool
 347 ResponseContentType(TSession *   const serverP,
 348                     const char * const type);
 349
 350 abyss_bool
 351 ResponseContentLength(TSession * const sessionP,
 352                       uint64_t   const len);
 353
 354 void
 355 ResponseError(TSession * const sessionP);
 356
 357 const char *
 358 MIMETypeFromExt(const char * const ext);
 359
 360 const char *
 361 MIMETypeFromExt2(MIMEType *   const MIMETypeP,
 362                  const char * const ext);
 363
 364 const char *
 365 MIMETypeFromFileName2(MIMEType *   const MIMETypeP,
 366                       const char * const fileName);
 367
 368 const char *
 369 MIMETypeFromFileName(const char * const fileName);
 370
 371 const char *
 372 MIMETypeGuessFromFile2(MIMEType *   const MIMETypeP,
 373                        const char * const fileName);
 374
 375 const char *
 376 MIMETypeGuessFromFile(const char * const filename);
 377
 378
 379 /****************************************************************************
 380   STUFF THAT PROBABLY DOESN'T BELONG IN THIS FILE BECAUSE IT IS INTERNAL
 381
 382   Some day, we sort this out.
 383 ****************************************************************************/
 384
 385
 386 #define CR      '\r'
 387 #define LF      '\n'
 388 #define CRLF    "\r\n"
 389
 390 /*********************************************************************
 391 ** Paths and so on...
 392 *********************************************************************/
 393
 394 #ifdef WIN32
 395 #define DEFAULT_ROOT        "c:\\abyss"
 396 #define DEFAULT_DOCS        DEFAULT_ROOT"\\htdocs"
 397 #define DEFAULT_CONF_FILE   DEFAULT_ROOT"\\conf\\abyss.conf"
 398 #define DEFAULT_LOG_FILE    DEFAULT_ROOT"\\log\\abyss.log"
 399 #else
 400 #ifdef __rtems__
 401 #define DEFAULT_ROOT        "/abyss"
 402 #else
 403 #define DEFAULT_ROOT        "/usr/local/abyss"
 404 #endif
 405 #define DEFAULT_DOCS        DEFAULT_ROOT"/htdocs"
 406 #define DEFAULT_CONF_FILE   DEFAULT_ROOT"/conf/abyss.conf"
 407 #define DEFAULT_LOG_FILE    DEFAULT_ROOT"/log/abyss.log"
 408 #endif
 409
 410 /*********************************************************************
 411 ** Maximum number of simultaneous connections
 412 *********************************************************************/
 413
 414 #define MAX_CONN    16
 415
 416 /*********************************************************************
 417 ** General purpose definitions
 418 *********************************************************************/
 419
 420 #ifndef NULL
 421 #define NULL ((void *)0)
 422 #endif  /* NULL */
 423
 424 #ifndef TRUE
 425 #define TRUE    1
 426 #endif  /* TRUE */
 427
 428 #ifndef FALSE
 429 #define FALSE    0
 430 #endif  /* FALSE */
 431
 432 /*********************************************************************
 433 ** Buffer
 434 *********************************************************************/
 435
 436 typedef struct
 437 {
 438     void *data;
 439     uint32_t size;
 440     uint32_t staticid;
 441 } TBuffer;
 442
 443 abyss_bool BufferAlloc(TBuffer *buf,uint32_t memsize);
 444 abyss_bool BufferRealloc(TBuffer *buf,uint32_t memsize);
 445 void BufferFree(TBuffer *buf);
 446
 447
 448 /*********************************************************************
 449 ** String
 450 *********************************************************************/
 451
 452 typedef struct
 453 {
 454     TBuffer buffer;
 455     uint32_t size;
 456 } TString;
 457
 458 abyss_bool StringAlloc(TString *s);
 459 abyss_bool StringConcat(TString *s,char *s2);
 460 abyss_bool StringBlockConcat(TString *s,char *s2,char **ref);
 461 void StringFree(TString *s);
 462 char *StringData(TString *s);
 463
 464
 465 /*********************************************************************
 466 ** Range
 467 *********************************************************************/
 468
 469 abyss_bool
 470 RangeDecode(char *str,
 471             uint64_t filesize,
 472             uint64_t *start,
 473             uint64_t *end);
 474
 475 abyss_bool DateInit(void);
 476
 477 /*********************************************************************
 478 ** Base64
 479 *********************************************************************/
 480
 481 void Base64Encode(char *s,char *d);
 482
 483 /*********************************************************************
 484 ** Session
 485 *********************************************************************/
 486
 487 abyss_bool SessionLog(TSession *s);
 488
 489
 490 #ifdef __cplusplus
 491 }
 492
 493
 494 #endif
 495
 496 /*****************************************************************************
 497 ** Here is the copyright notice from the Abyss web server project file from
 498 ** which this file is derived.
 499 **
 500 ** Copyright (C) 2000 by Moez Mahfoudh <mmoez@bigfoot.com>.
 501 ** All rights reserved.
 502 **
 503 ** Redistribution and use in source and binary forms, with or without
 504 ** modification, are permitted provided that the following conditions
 505 ** are met:
 506 ** 1. Redistributions of source code must retain the above copyright
 507 **    notice, this list of conditions and the following disclaimer.
 508 ** 2. Redistributions in binary form must reproduce the above copyright
 509 **    notice, this list of conditions and the following disclaimer in the
 510 **    documentation and/or other materials provided with the distribution.
 511 ** 3. The name of the author may not be used to endorse or promote products
 512 **    derived from this software without specific prior written permission.
 513 **
 514 ** THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
 515 ** ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 516 ** IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 517 ** ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
 518 ** FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 519 ** DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 520 ** OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 521 ** HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 522 ** LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 523 ** OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 524 ** SUCH DAMAGE.
 525 **
 526 ******************************************************************************/
 527 #endif  /* _ABYSS_H_ */