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          * Get an arbitrary environment variable.
  90          *
  91          * @param name          name of the environment variable
  92          * @return                      value, NULL if not found
  93          */
  94         char* (*get_env_var)(request_t *this, char *name);
  95
  96         /**
  97          * Read raw POST/PUT data from HTTP request.
  98          *
  99          * @param buf           buffer to read data into
 100          * @param len           size of the supplied buffer
 101          * @return                      number of bytes read, < 0 on error
 102          */
 103         int (*read_data)(request_t *this, char *buf, int len);
 104
 105         /**
 106          * Close the session and it's context after handling.
 107          */
 108         void (*close_session)(request_t *this);
 109
 110         /**
 111          * Has the session been closed by close_session()?
 112          *
 113          * @return                      TRUE if session has been closed
 114          */
 115         bool (*session_closed)(request_t *this);
 116
 117         /**
 118          * Redirect the client to another location.
 119          *
 120          * @param fmt           location format string
 121          * @param ...           variable argument for fmt
 122          */
 123         void (*redirect)(request_t *this, char *fmt, ...);
 124
 125         /**
 126          * Get the HTTP referer.
 127          *
 128          * @return                      HTTP referer
 129          */
 130         char* (*get_referer)(request_t *this);
 131
 132         /**
 133          * Redirect back to the referer.
 134          */
 135         void (*to_referer)(request_t *this);
 136
 137         /**
 138          * Set a template value.
 139          *
 140          * @param key           key to set
 141          * @param value         value to set key to
 142          */
 143         void (*set)(request_t *this, char *key, char *value);
 144
 145         /**
 146          * Set a template value using format strings.
 147          *
 148          * Format string is in the form "key=value", where printf like format
 149          * substitution occurs over the whole string.
 150          *
 151          * @param format        printf like format string
 152          * @param ...           variable argument list
 153          */
 154         void (*setf)(request_t *this, char *format, ...);
 155
 156         /**
 157          * Render a template.
 158          *
 159          * The render() function additionally sets a HDF variable "base"
 160          * which points to the root of the web application and allows to point to
 161          * other targets without to worry about path location.
 162          *
 163          * @param template      clearsilver template file location
 164          */
 165         void (*render)(request_t *this, char *template);
 166
 167         /**
 168          * Stream a format string to the client.
 169          *
 170          * Stream is not closed and may be called multiple times to allow
 171          * server-push functionality.
 172          *
 173          * @param format        printf like format string
 174          * @param ...           argmuent list to format string
 175          * @return                      number of streamed bytes, < 0 if stream closed
 176          */
 177         int (*streamf)(request_t *this, char *format, ...);
 178
 179         /**
 180          * Serve a request with headers and a body.
 181          *
 182          * @param headers       HTTP headers, \n separated
 183          * @param chunk         body to write to output
 184          */
 185         void (*serve)(request_t *this, char *headers, chunk_t chunk);
 186
 187         /**
 188          * Increase the reference count to the stream.
 189          *
 190          * @return                      this with increased refcount
 191          */
 192         request_t* (*get_ref)(request_t *this);
 193
 194         /**
 195          * Destroy the request_t.
 196          */
 197         void (*destroy) (request_t *this);
 198 };
 199
 200 /**
 201  * Create a request from the fastcgi struct.
 202  *
 203  * @param fd                    file descripter opened with FCGX_OpenSocket
 204  * @param debug                 no stripping, no compression, timing information
 205  */
 206 request_t *request_create(int fd, bool debug);
 207
 208 #endif /** REQUEST_H_ @}*/