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          * Get the HTTP referer.
 110          *
 111          * @return                      HTTP referer
 112          */
 113         char* (*get_referer)(request_t *this);
 114
 115         /**
 116          * Redirect back to the referer.
 117          */
 118         void (*to_referer)(request_t *this);
 119
 120         /**
 121          * Set a template value.
 122          *
 123          * @param key           key to set
 124          * @param value         value to set key to
 125          */
 126         void (*set)(request_t *this, char *key, char *value);
 127
 128         /**
 129          * Set a template value using format strings.
 130          *
 131          * Format string is in the form "key=value", where printf like format
 132          * substitution occurs over the whole string.
 133          *
 134          * @param format        printf like format string
 135          * @param ...           variable argument list
 136          */
 137         void (*setf)(request_t *this, char *format, ...);
 138
 139         /**
 140          * Render a template.
 141          *
 142          * The render() function additionally sets a HDF variable "base"
 143          * which points to the root of the web application and allows to point to
 144          * other targets without to worry about path location.
 145          *
 146          * @param template      clearsilver template file location
 147          */
 148         void (*render)(request_t *this, char *template);
 149
 150         /**
 151          * Stream a format string to the client.
 152          *
 153          * Stream is not closed and may be called multiple times to allow
 154          * server-push functionality.
 155          *
 156          * @param format        printf like format string
 157          * @param ...           argmuent list to format string
 158          * @return                      number of streamed bytes, < 0 if stream closed
 159          */
 160         int (*streamf)(request_t *this, char *format, ...);
 161
 162         /**
 163          * Serve a request with headers and a body.
 164          *
 165          * @param headers       HTTP headers, \n separated
 166          * @param chunk         body to write to output
 167          */
 168         void (*serve)(request_t *this, char *headers, chunk_t chunk);
 169
 170         /**
 171          * Increase the reference count to the stream.
 172          *
 173          * @return                      this with increased refcount
 174          */
 175         request_t* (*get_ref)(request_t *this);
 176
 177         /**
 178          * Destroy the request_t.
 179          */
 180         void (*destroy) (request_t *this);
 181 };
 182
 183 /**
 184  * Create a request from the fastcgi struct.
 185  *
 186  * @param fd                    file descripter opened with FCGX_OpenSocket
 187  * @param debug                 no stripping, no compression, timing information
 188  */
 189 request_t *request_create(int fd, bool debug);
 190
 191 #endif /** REQUEST_H_ @}*/