source4/web_server/esp/esp.h

   1 /**
   2  *      @file   esp.h
   3  *      @brief  Header for Embedded Server Pages (ESP)
   4  */
   5 /********************************* Copyright **********************************/
   6 /*
   7  *      @copy   default
   8  *
   9  *      Copyright (c) Mbedthis Software LLC, 2003-2005. All Rights Reserved.
  10  *
  11  *      This software is distributed under commercial and open source licenses.
  12  *      You may use the GPL open source license described below or you may acquire
  13  *      a commercial license from Mbedthis Software. You agree to be fully bound
  14  *      by the terms of either license. Consult the LICENSE.TXT distributed with
  15  *      this software for full details.
  16  *
  17  *      This software is open source; you can redistribute it and/or modify it
  18  *      under the terms of the GNU General Public License as published by the
  19  *      Free Software Foundation; either version 2 of the License, or (at your
  20  *      option) any later version. See the GNU General Public License for more
  21  *      details at: http://www.mbedthis.com/downloads/gplLicense.html
  22  *
  23  *      This program is distributed WITHOUT ANY WARRANTY; without even the
  24  *      implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  25  *
  26  *      This GPL license does NOT permit incorporating this software into
  27  *      proprietary programs. If you are unable to comply with the GPL, you must
  28  *      acquire a commercial license to use this software. Commercial licenses
  29  *      for this software and support services are available from Mbedthis
  30  *      Software at http://www.mbedthis.com
  31  *
  32  *      @end
  33  */
  34 /********************************** Includes **********************************/
  35
  36 #ifndef _h_ESP_h
  37 #define _h_ESP_h 1
  38
  39 #include        "lib/ejs/ejs.h"
  40 #include        "web_server/esp/espEnv.h"
  41 #include        "lib/ejs/var.h"
  42 #include        "lib/ejs/miniMpr.h"
  43
  44 /*********************************** Defines **********************************/
  45
  46 #define ESP_STRING_ARGS                 MPR_TYPE_STRING_ARGS
  47
  48 #if BLD_FEATURE_SQUEEZE
  49 #define ESP_TOK_INCR                    1024
  50 #define ESP_MAX_HEADER                  1024
  51 #else
  52 #define ESP_TOK_INCR                    4096
  53 #define ESP_MAX_HEADER                  4096
  54 #endif
  55
  56 /*
  57  *      ESP lexical analyser tokens
  58  */
  59 #define ESP_TOK_ERR                             -1                      /* Any input error */
  60 #define ESP_TOK_EOF                             0                       /* End of file */
  61 #define ESP_TOK_START_ESP               1                       /* <% */
  62 #define ESP_TOK_END_ESP                 2                       /* %> */
  63 #define ESP_TOK_ATAT                    3                       /* @@var */
  64 #define ESP_TOK_LITERAL                 4                       /* literal HTML */
  65 #define ESP_TOK_INCLUDE                 5                       /* include file.esp */
  66 #define ESP_TOK_EQUALS                  6                       /* = var */
  67
  68 /*
  69  *      ESP parser states
  70  */
  71 #define ESP_STATE_BEGIN                 1                       /* Starting state */
  72 #define ESP_STATE_IN_ESP_TAG    2                       /* Inside a <% %> group */
  73
  74 /*********************************** Types ************************************/
  75
  76 typedef void* EspHandle;                                        /* Opaque Web server handle type */
  77
  78 /*
  79  *      Per request control block
  80  */
  81 typedef struct EspRequest {
  82         MprStr          docPath;                                        /* Physical path for ESP page */
  83         EjsId           eid;                                            /* EJS instance handle */
  84         const struct Esp        *esp;                           /* Pointer to ESP control block */
  85         EspHandle       requestHandle;                          /* Per request web server handle */
  86         MprStr          uri;                                            /* Request URI */
  87         MprVar          *variables;                                     /* Pointer to variables */
  88 } EspRequest;
  89
  90 /*
  91  *      Master ESP control block. This defines the function callbacks for a
  92  *      web server handler to implement. ESP will call these functions as
  93  *      required.
  94  */
  95 typedef struct Esp {
  96         int             maxScriptSize;
  97         void    (*createSession)(EspHandle handle, int timeout);
  98         void    (*destroySession)(EspHandle handle);
  99         const char *(*getSessionId)(EspHandle handle);
 100         int             (*mapToStorage)(EspHandle handle, char *path, int len, const char *uri,
 101                                 int flags);
 102         int             (*readFile)(EspHandle handle, char **buf, int *len, const char *path);
 103         void    (*redirect)(EspHandle handle, int code, char *url);
 104         void    (*setCookie)(EspHandle handle, const char *name, const char *value,
 105                                 int lifetime, const char *path, bool secure);
 106         void    (*setHeader)(EspHandle handle, const char *value, bool allowMultiple);
 107         void    (*setResponseCode)(EspHandle handle, int code);
 108         int             (*writeBlock)(EspHandle handle, char *buf, int size);
 109         int             (*writeFmt)(EspHandle handle, char *fmt, ...);
 110 #if BLD_FEATURE_MULTITHREAD
 111         void    (*lock)(void *lockData);
 112         void    (*unlock)(void *lockData);
 113         void    *lockData;
 114 #endif
 115 } Esp;
 116
 117
 118 /*
 119  *      ESP parse context
 120  */
 121 typedef struct {
 122         char    *inBuf;                                 /* Input data to parse */
 123         char    *inp;                                   /* Next character for input */
 124         char    *endp;                                  /* End of storage (allow for null) */
 125         char    *tokp;                                  /* Pointer to current parsed token */
 126         char    *token;                                 /* Storage buffer for token */
 127         int             tokLen;                                 /* Length of buffer */
 128 } EspParse;
 129
 130
 131 /******************************** Private APIs ********************************/
 132
 133 extern void                     espRegisterProcs(void);
 134
 135 /******************************** Published API *******************************/
 136 #ifdef  __cplusplus
 137 extern "C" {
 138 #endif
 139
 140 /*
 141  *      Function callback signatures
 142  */
 143 typedef int             (*EspCFunction)(EspRequest *ep, int argc,
 144                                                 struct MprVar **argv);
 145 typedef int             (*EspStringCFunction)(EspRequest *ep, int argc,
 146                                                 char **argv);
 147
 148 /*
 149  *      APIs for those hosting the ESP module
 150  */
 151 extern int                      espOpen(const Esp *control);
 152 extern void                     espClose(void);
 153 extern EspRequest       *espCreateRequest(EspHandle webServerRequestHandle,
 154                                                 char *uri, MprVar *envObj);
 155 extern void                     espDestroyRequest(EspRequest *ep);
 156 extern int                      espProcessRequest(EspRequest *ep, const char *docPath,
 157                                                 char *docBuf, char **errMsg);
 158
 159 /*
 160  *      Method invocation
 161  */
 162 extern void                     espDefineCFunction(EspRequest *ep, const char *functionName,
 163                                                 EspCFunction fn, void *thisPtr);
 164 extern void             espDefineFunction(EspRequest *ep, const char *functionName,
 165                                                 char *args, char *body);
 166 extern void                     espDefineStringCFunction(EspRequest *ep,
 167                                                 const char *functionName, EspStringCFunction fn,
 168                                                 void *thisPtr);
 169 extern int                      espRunFunction(EspRequest *ep, MprVar *obj,
 170                                                 char *functionName, MprArray *args);
 171 extern void                     espSetResponseCode(EspRequest *ep, int code);
 172 extern void                     espSetReturn(EspRequest *ep, MprVar value);
 173 extern void             *espGetThisPtr(EspRequest *ep);
 174
 175 /*
 176  *      Utility routines to use in C methods
 177  */
 178 extern void                     espError(EspRequest *ep, const char *fmt, ...) PRINTF_ATTRIBUTE(2,3);
 179 extern int                      espEvalFile(EspRequest *ep, char *path, MprVar *result,
 180                                                 char **emsg);
 181 extern int                      espEvalScript(EspRequest *ep, char *script, MprVar *result,
 182                                                 char **emsg);
 183 extern MprVar           *espGetLocalObject(EspRequest *ep);
 184 extern MprVar           *espGetGlobalObject(EspRequest *ep);
 185 extern EspHandle        espGetRequestHandle(EspRequest *ep);
 186 extern MprVar           *espGetResult(EspRequest *ep);
 187 extern EjsId            espGetScriptHandle(EspRequest *ep);
 188 extern void                     espRedirect(EspRequest *ep, int code, char *url);
 189 extern void                     espSetHeader(EspRequest *ep, char *header,
 190                                                 bool allowMultiple);
 191 extern void                     espSetReturnString(EspRequest *ep, const char *str);
 192 extern int                      espWrite(EspRequest *ep, char *buf, int size);
 193 extern int                      espWriteString(EspRequest *ep, char *buf);
 194 extern int                      espWriteFmt(EspRequest *ep, char *fmt, ...) PRINTF_ATTRIBUTE(2,3);
 195
 196 /*
 197  *      ESP array[] variable access (set will update/create)
 198  */
 199 extern int                      espGetVar(EspRequest *ep, EspEnvType oType, char *var,
 200                                                 MprVar *value);
 201 extern char                     *espGetStringVar(EspRequest *ep, EspEnvType oType,
 202                                                 char *var, char *defaultValue);
 203 extern void                     espSetVar(EspRequest *ep, EspEnvType oType, char *var,
 204                                                 MprVar value);
 205 extern void                     espSetStringVar(EspRequest *ep, EspEnvType oType,
 206                                                 const char *var, const char *value);
 207 extern int                      espUnsetVar(EspRequest *ep, EspEnvType oType, char *var);
 208
 209 /*
 210  *      Object creation and management
 211  */
 212 extern MprVar           espCreateObjVar(char *name, int hashSize);
 213 extern MprVar           espCreateArrayVar(char *name, int size);
 214 extern bool                     espDestroyVar(MprVar *var);
 215 extern MprVar           *espCreateProperty(MprVar *obj, char *property,
 216                                                 MprVar *newValue);
 217 extern MprVar           *espCreatePropertyValue(MprVar *obj, char *property,
 218                                                 MprVar newValue);
 219 extern int                      espDeleteProperty(MprVar *obj, char *property);
 220
 221 /*
 222  *      JavaScript variable management. Set will create/update a property.
 223  *      All return a property reference. GetProperty will optionally return the
 224  *      property in value.
 225  */
 226 extern MprVar           *espGetProperty(MprVar *obj, char *property,
 227                                                 MprVar *value);
 228 extern MprVar           *espSetProperty(MprVar *obj, char *property,
 229                                                 MprVar *newValue);
 230 extern MprVar           *espSetPropertyValue(MprVar *obj, char *property,
 231                                                 MprVar newValue);
 232
 233 #if 0
 234 /*
 235  *      Low-level direct read and write of properties.
 236  *      FUTURE:  -- Read is not (dest, src). MUST WARN IN DOC ABOUT COPY/READ
 237  *      Will still cause triggers to run.
 238  */
 239 extern int                      espReadProperty(MprVar *dest, MprVar *prop);
 240 extern int                      espWriteProperty(MprVar *prop, MprVar *newValue);
 241 extern int                      espWritePropertyValue(MprVar *prop, MprVar newValue);
 242 #endif
 243
 244
 245 /*
 246  *      Access JavaScript variables by their full name. Can use "." or "[]". For
 247  *      example: "global.request['REQUEST_URI']"
 248  *      For Read/write, the variables must exist.
 249  */
 250 extern int                      espCopyVar(EspRequest *ep, char *var, MprVar *value,
 251                                                 int copyDepth);
 252 extern int                      espDeleteVar(EspRequest *ep, char *var);
 253 extern int                      espReadVar(EspRequest *ep, char *var, MprVar *value);
 254 extern int                      espWriteVar(EspRequest *ep, char *var, MprVar *value);
 255 extern int                      espWriteVarValue(EspRequest *ep, char *var, MprVar value);
 256
 257 /*
 258  *      Object property enumeration
 259  */
 260 extern MprVar           *espGetFirstProperty(MprVar *obj, int includeFlags);
 261 extern MprVar           *espGetNextProperty(MprVar *obj, MprVar *currentProperty,
 262                                                 int includeFlags);
 263 extern int                      espGetPropertyCount(MprVar *obj, int includeFlags);
 264
 265 #ifdef  __cplusplus
 266 }
 267 #endif
 268 /******************************************************************************/
 269 #endif /* _h_ESP_h */
 270
 271 /*
 272  * Local variables:
 273  * tab-width: 4
 274  * c-basic-offset: 4
 275  * End:
 276  * vim:tw=78
 277  * vim600: sw=4 ts=4 fdm=marker
 278  * vim<600: sw=4 ts=4
 279  */