3 * @brief Headers for the fastcgi web interface
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
16 typedef enum StatusCodes {
19 STATUS_UNAUTHORIZED = -2,
20 STATUS_NOTRUNNING = -3,
21 STATUS_ALREADYEXISTS = -4
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))
36 #define CONTROL_KEY_BUFSIZ 41
39 * An entry that describes an expected user parameter for parsing.
40 * To be used in conjunction with @see FCGI_ParseRequest.
42 typedef struct FCGIValue {
43 /** The name of the key (from key/value pair) [in] **/
45 /** A pointer to a variable that will hold the parsed value [out] **/
47 /** Bit flags that determine things like if the field is required and if it was received [in/out] **/
51 /** The type of a user (unauthorised, normal, admin). **/
52 typedef enum {USER_UNAUTH, USER_NORMAL, USER_ADMIN} UserType;
54 /**Contextual information related to FCGI requests*/
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**/
65 /**Determines if the user is an admin or not**/
67 /**Name of the logged in user**/
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?**/
77 /** The type definition of a module handler. **/
78 typedef void (*ModuleHandler) (FCGIContext *context, char *params);
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);
101 extern void FCGI_WriteBinary(void * data, size_t size, size_t num_elem);
104 * Shortcut to calling FCGI_RejectJSONEx. Sets the error code
106 * @param context The context to work in
107 * @param description A short description of why the request was rejected.
108 * @see FCGI_RejectJSONEx
110 #define FCGI_RejectJSON(context, description) FCGI_RejectJSONEx(context, STATUS_ERROR, description)
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
118 #define FCGI_JSONValue FCGI_PrintRaw