src/libfast/request.h

   1 /*
   2  * Copyright (C) 2007 Martin Willi
   3  * Hochschule fuer Technik Rapperswil
   4  *
   5  * This program is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License as published by the
   7  * Free Software Foundation; either version 2 of the License, or (at your
   8  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
   9  *
  10  * This program is distributed in the hope that it will be useful, but
  11  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  12  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  13  * for more details.
  14  *
  15  * $Id$
  16  */
  17
  18 /**
  19  * @defgroup request request
  20  * @{ @ingroup libfast
  21  */
  22
  23 #ifndef REQUEST_H_
  24 #define REQUEST_H_
  25
  26 #include <fcgiapp.h>
  27 #include <library.h>
  28
  29 typedef struct request_t request_t;
  30
  31 /**
  32  * A HTTP request, encapsulates FCGX_Request.
  33  *
  34  * The response is also handled through the request object.
  35  */
  36 struct request_t {
  37
  38         /**
  39          * Add a cookie to the reply (Set-Cookie header).
  40          *
  41          * @param name          name of the cookie to set
  42          * @param value         value of the cookie
  43          */
  44         void (*add_cookie)(request_t *this, char *name, char *value);
  45
  46         /**
  47          * Get a cookie the client sent in the request.
  48          *
  49          * @param name          name of the cookie
  50          * @return                      cookie value, NULL if no such cookie found
  51          */
  52         char* (*get_cookie)(request_t *this, char *name);
  53
  54         /**
  55          * Get the request path relative to the application.
  56          *
  57          * @return                      path
  58          */
  59         char* (*get_path)(request_t *this);
  60
  61         /**
  62          * Get the base path of the application.
  63          *
  64          * @return                      base path
  65          */
  66         char* (*get_base)(request_t *this);
  67
  68         /**
  69          * Get the remote host address of this request.
  70          *
  71          * @return                      host address as string
  72          */
  73         char* (*get_host)(request_t *this);
  74
  75         /**
  76          * Get the user agent string.
  77          *
  78          * @return                      user agent string
  79          */
  80         char* (*get_user_agent)(request_t *this);
  81
  82         /**
  83          * Get a post/get variable included in the request.
  84          *
  85          * @param name          name of the POST/GET variable
  86          * @return                      value, NULL if not found
  87          */
  88         char* (*get_query_data)(request_t *this, char *name);
  89
  90         /**
  91          * Close the session and it's context after handling.
  92          */
  93         void (*close_session)(request_t *this);
  94
  95         /**
  96          * Has the session been closed by close_session()?
  97          *
  98          * @return                      TRUE if session has been closed
  99          */
 100         bool (*session_closed)(request_t *this);
 101
 102         /**
 103          * Redirect the client to another location.
 104          *
 105          * @param fmt           location format string
 106          * @param ...           variable argument for fmt
 107          */
 108         void (*redirect)(request_t *this, char *fmt, ...);
 109
 110         /**
 111          * Redirect the client to the referer.
 112          */
 113         void (*to_referer)(request_t *this);
 114
 115         /**
 116          * Set a template value.
 117          *
 118          * @param key           key to set
 119          * @param value         value to set key to
 120          */
 121         void (*set)(request_t *this, char *key, char *value);
 122
 123         /**
 124          * Set a template value using format strings.
 125          *
 126          * Format string is in the form "key=value", where printf like format
 127          * substitution occurs over the whole string.
 128          *
 129          * @param format        printf like format string
 130          * @param ...           variable argument list
 131          */
 132         void (*setf)(request_t *this, char *format, ...);
 133
 134         /**
 135          * Render a template.
 136          *
 137          * The render() function additionally sets a HDF variable "base"
 138          * which points to the root of the web application and allows to point to
 139          * other targets without to worry about path location.
 140          *
 141          * @param template      clearsilver template file location
 142          */
 143         void (*render)(request_t *this, char *template);
 144
 145         /**
 146          * Stream a format string to the client.
 147          *
 148          * Stream is not closed and may be called multiple times to allow
 149          * server-push functionality.
 150          *
 151          * @param format        printf like format string
 152          * @param ...           argmuent list to format string
 153          * @return                      number of streamed bytes, < 0 if stream closed
 154          */
 155         int (*streamf)(request_t *this, char *format, ...);
 156
 157         /**
 158          * Serve a request with headers and a body.
 159          *
 160          * @param headers       HTTP headers, \n separated
 161          * @param chunk         body to write to output
 162          */
 163         void (*serve)(request_t *this, char *headers, chunk_t chunk);
 164
 165         /**
 166          * Increase the reference count to the stream.
 167          *
 168          * @return                      this with increased refcount
 169          */
 170         request_t* (*get_ref)(request_t *this);
 171
 172         /**
 173          * Destroy the request_t.
 174          */
 175         void (*destroy) (request_t *this);
 176 };
 177
 178 /**
 179  * Create a request from the fastcgi struct.
 180  *
 181  * @param fd                    file descripter opened with FCGX_OpenSocket
 182  * @param debug                 no stripping, no compression, timing information
 183  */
 184 request_t *request_create(int fd, bool debug);
 185
 186 #endif /** REQUEST_H_ @}*/