r6989: - added support for esp style includes (which include a esp file, instead...
[samba.git] / source / 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        "web_server/ejs/ejs.h"
40 #include        "web_server/esp/espEnv.h"
41 #include        "web_server/ejs/var.h"
42 #include        "web_server/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         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         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, char *name, char *value, 
105                                 int lifetime, 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(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, char *functionName, 
163                                                 EspCFunction fn, void *thisPtr);
164 extern void             espDefineFunction(EspRequest *ep, 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, ...);
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, 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, ...);
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  */