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