server/fastcgi.h

   1 /**
   2  * @file fastcgi.h
   3  * @brief Headers for the fastcgi web interface
   4  */
   5
   6 #ifndef _FASTCGI_H
   7 #define _FASTCGI_H
   8
   9 /**
  10  * Status codes that fcgi module handlers can return
  11  * Success status codes have values > 0
  12  * Failure status codes have values <(=) 0
  13  * Note: 0 is counted as an error code to minimise confusion
  14  * with in-browser JSON parsing error codes
  15  */
  16 typedef enum StatusCodes {
  17         STATUS_OK = 1,
  18         STATUS_ERROR = -1,
  19         STATUS_UNAUTHORIZED = -2,
  20         STATUS_NOTRUNNING = -3,
  21         STATUS_ALREADYEXISTS = -4
  22 } StatusCodes;
  23
  24 #define FCGI_PARAM_REQUIRED (1 << 0)
  25 #define FCGI_PARAM_RECEIVED (1 << 1)
  26 #define FCGI_BOOL_T (1 << 2)
  27 #define FCGI_INT_T      (1 << 3)
  28 #define FCGI_LONG_T (1 << 4)
  29 #define FCGI_DOUBLE_T (1 << 5)
  30 #define FCGI_STRING_T (1 << 6)
  31 #define FCGI_REQUIRED(x) ((x) | FCGI_PARAM_REQUIRED)
  32 #define FCGI_IS_REQUIRED(x) ((x) & FCGI_PARAM_REQUIRED)
  33 #define FCGI_RECEIVED(x) ((x) & FCGI_PARAM_RECEIVED)
  34 #define FCGI_TYPE(x) ((x) & ~(FCGI_PARAM_REQUIRED | FCGI_PARAM_RECEIVED))
  35
  36 #define CONTROL_KEY_BUFSIZ 41
  37
  38 /**
  39  * An entry that describes an expected user parameter for parsing.
  40  * To be used in conjunction with @see FCGI_ParseRequest.
  41  */
  42 typedef struct FCGIValue {
  43         /** The name of the key (from key/value pair) [in] **/
  44         const char *key;
  45         /** A pointer to a variable that will hold the parsed value [out] **/
  46         void *value;
  47         /** Bit flags that determine things like if the field is required and if it was received [in/out] **/
  48         unsigned flags;
  49 } FCGIValue;
  50
  51 /** The type of a user (unauthorised, normal, admin). **/
  52 typedef enum {USER_UNAUTH, USER_NORMAL, USER_ADMIN} UserType;
  53
  54 /**Contextual information related to FCGI requests*/
  55 typedef struct
  56 {
  57         /**The time of last valid user access possessing the control key**/
  58         time_t control_timestamp;
  59         /**A SHA-1 hash that is the control key, determining who is logged in**/
  60         char control_key[CONTROL_KEY_BUFSIZ];
  61         /**The received control key for the current request**/
  62         char received_key[CONTROL_KEY_BUFSIZ];
  63         /**The IPv4 address of the logged-in user**/
  64         char control_ip[16];
  65         /**Determines if the user is an admin or not**/
  66         UserType user_type;
  67         /**Name of the logged in user**/
  68         char user_name[31];
  69         /**User directory for the logged in user**/
  70         char user_dir[BUFSIZ];
  71         /**The name of the current module**/
  72         const char *current_module;
  73         /**For debugging purposes?**/
  74         int response_number;
  75 } FCGIContext;
  76
  77 /** The type definition of a module handler. **/
  78 typedef void (*ModuleHandler) (FCGIContext *context, char *params);
  79
  80 extern bool FCGI_LockControl(FCGIContext *context, const char * user_name, UserType user_type);
  81 extern void FCGI_ReleaseControl(FCGIContext *context);
  82 extern bool FCGI_HasControl(FCGIContext *context);
  83 extern void FCGI_GetControlCookie(char buffer[CONTROL_KEY_BUFSIZ]);
  84 extern void FCGI_SendControlCookie(FCGIContext *context, bool set);
  85 extern char *FCGI_KeyPair(char *in, const char **key, const char **value);
  86 extern bool FCGI_ParseRequest(FCGIContext *context, char *params, FCGIValue values[], size_t count);
  87 extern void FCGI_BeginJSON(FCGIContext *context, StatusCodes status_code);
  88 extern void FCGI_AcceptJSON(FCGIContext *context, const char *description);
  89 extern void FCGI_JSONPair(const char *key, const char *value);
  90 extern void FCGI_JSONLong(const char *key, long value);
  91 extern void FCGI_JSONDouble(const char *key, double value);
  92 extern void FCGI_JSONBool(const char *key, bool value);
  93 extern void FCGI_JSONKey(const char *key);
  94 extern void FCGI_PrintRaw(const char *format, ...);
  95 extern void FCGI_EndJSON();
  96 extern void FCGI_RejectJSONEx(FCGIContext *context, StatusCodes status, const char *description);
  97 extern char *FCGI_URLDecode(char *buf);
  98 extern char *FCGI_EscapeText(char *buf);
  99 extern void *FCGI_RequestLoop (void *data);
 100
 101 extern void FCGI_WriteBinary(void * data, size_t size, size_t num_elem);
 102
 103 /**
 104  * Shortcut to calling FCGI_RejectJSONEx. Sets the error code
 105  * to STATUS_ERROR.
 106  * @param context The context to work in
 107  * @param description A short description of why the request was rejected.
 108  * @see FCGI_RejectJSONEx
 109  */
 110 #define FCGI_RejectJSON(context, description) FCGI_RejectJSONEx(context, STATUS_ERROR, description)
 111
 112 /**
 113  * Custom formatting function for the JSON value. To be used in
 114  * conjunction with FCGI_JSONKey. Care should be taken to ensure
 115  * that valid JSON is produced.
 116  * @see FCGI_PrintRaw for calling syntax
 117  */
 118 #define FCGI_JSONValue FCGI_PrintRaw
 119
 120 #endif
 121
 122