This is the interface for a scripting engine Beesnest will get. More...
#include <DcEngine.h>
Public Member Functions | |
| virtual | ~IdcEngine () |
| Destructor. | |
| virtual void | Prepare (IdcRequest *preq, IdcResponse *pres, IdcAdaptersSet *pset)=0 |
| Initialize the engine for this page. | |
| virtual bool | Process (BufferHolder code, BufferHolder &result, int size_limit)=0 |
| This function processes (a part of) a script. | |
| virtual bool | IsStorable () |
| If you want Beesnest to be able to keep an instance of this script engine over multiple pages, just return True from this function. | |
| virtual void | Stored () |
| If this engine is "Storable", this function will be called when Beesnest stores it. | |
| virtual void | NextIsCompiled () |
| virtual bool | GetCompiledScript (BufferHolder &comp) |
Detailed Description
This is the interface for a scripting engine Beesnest will get.
It uses IdcResponse, IdcRequest and IdcAdaptersSet ( you don't implement these three interfaces, Beesnest does).
When the system first gets an engine it calls the Prepare function. This will pass the engine a Request, Response and an Adapters Set objects. The data needs to be passed just once for every request. Note that if the user is not logged in, the Adapters Set pointer will be NULL.
For every (part of a) buffer that needs to be processed by this engine, the system will call the Process function. The engine will process the buffer and will put the result buffer in a reference to a BufferHolder (as a pointer to it's own inner string). The engine will get the buffer size limit as well.
IMPORTANT: The returned BufferHolder has to point to a string that will continue to exist after Process returns. Either a class member string or a dynamically allocated string. You can clear/delete this string when Stored is called (or in the Destructor). Beesnest will not try to change or delete the returned buffer! It will crush the program if it does!
An engine has to return with a False value if the buffer size goes over the limit. Whenever you have an error it is your responsibility to put in the returned buffer an error message to the client, and return False.
The library that hosts the implementation of an IdcEngine has to have at last one function:
bool GetEngine (IdcEngine** pp_engine, const char* name, bool (*pGetParam)(const char*, char*, int))
This function will return a pointer to the implementation of the engine. The name is for identifying this object. the class has to save this name as a class member, and use it to find the path for its part in the configuration database. The last parameter is a pointer to a function of Beesnest (ExtGetParam). This function is for accessing the server configuration database. In this function the first "C" style string is the name of the parameter you want to get, the second string is a pre-allocated buffer to the parameter value, and the last int is the length of this buffer. This function will return True if the parameter exists, otherwise it will return False. You welcome to use this function and add your engine configuration data to the configuration files.
Other optional functions of the engine library can be:
void Init (); and void Term (); These functions, if exist, will be called when the first instance of an engine is loaded, and just before Beesnest exits. Do any global initialization/termination you need with these functions.
If the name of an engine object is "MyEngine", then this object has to (or can) read its configuration from "Engines->MyEngine".
For a logged in user, the Beesnest system can store an engine. It means That a programmer can create a script or a program that will execute over several pages. All the data and code that exist when the script started, will still exist when the script continue to execute on another page! If you want your engine to be "Storable" you need to set the function IsStorable to return True. This function is already implemented, and it just returns False. When Beesnest stores an engine it calls the Stored function. (Beesnest call IsStorable before every time it stores an engine, so you can use this function to let it know when not to store the engine). Beesnest does not store the engine if the returned value from Process was False.
All interfaces uses BufferHolder to pass strings or buffers.
Definition at line 86 of file DcEngine.h.
Constructor & Destructor Documentation
| virtual IdcEngine::~IdcEngine | ( | ) | [inline, virtual] |
Destructor.
IMPORTANT: In order to implement a script engine you HAVE to be able to close the interpreter in a clean way in the Destructor. You will not have any knowledge about what did the interpreter do, and when did Beesnest is going to call this Destructor. all you know is that the script is not running any more!
Definition at line 96 of file DcEngine.h.
Member Function Documentation
| virtual bool IdcEngine::GetCompiledScript | ( | BufferHolder & | comp ) | [inline, virtual] |
Definition at line 171 of file DcEngine.h.
| virtual bool IdcEngine::IsStorable | ( | ) | [inline, virtual] |
If you want Beesnest to be able to keep an instance of this script engine over multiple pages, just return True from this function.
The user can still turn this feature off from the engine configuration file (Engines->Engine-Name->Sortable). Beesnest call this function before every time it stores the script engine, so if from some reason, you want to reset the engine (like after an error), return False from this function
Reimplemented in BnPython.
Definition at line 143 of file DcEngine.h.
| virtual void IdcEngine::NextIsCompiled | ( | ) | [inline, virtual] |
Definition at line 170 of file DcEngine.h.
| virtual void IdcEngine::Prepare | ( | IdcRequest * | preq, |
| IdcResponse * | pres, | ||
| IdcAdaptersSet * | pset | ||
| ) | [pure virtual] |
Initialize the engine for this page.
If you have errors here (cannot initialize the engine) just return False from the first call to the Process function, and put some message in the returned buffer.
- Parameters:
-
preq Pointer to the page Request object. pres Pointer to the page Response object. pset Pointer to the user's Adapters Set object. This will be NULL if the client is not logged in!
Implemented in BnPython.
| virtual bool IdcEngine::Process | ( | BufferHolder | code, |
| BufferHolder & | result, | ||
| int | size_limit | ||
| ) | [pure virtual] |
This function processes (a part of) a script.
- Parameters:
-
code The Buffer Holder that holds the buffer to process. Don't try to change this buffer! Note that this buffer WILL NOT end with NULL! result Reference to a Buffer Holder that the result HTML will be in. If this holder will not point to NULL and the buffer will not be empty, after calling this function, Beesnest will add it to the response, (replacing the "code" string). Beesnest doesn't try to delete this buffer! size_limit The maximum returned buffer size. If you reach this limit, you should return from this function with False value (but put some message in 'result'), 0 is unlimited.
- Returns:
- (bool) False when you have errors. Put some error message in 'result'. If the returned value is False, Beesnest will still sent this buffer to the client (with everything that came before it). But it will stop to process the page (for the next pieces of scripts).
- Exceptions:
-
int This function can throw an integer value. Beesnest just print this value to the console/log end exit the current thread. If you get an exception from IdcResponse.Flush, you have to throw an exception.
Implemented in BnPython.
| virtual void IdcEngine::Stored | ( | ) | [inline, virtual] |
If this engine is "Storable", this function will be called when Beesnest stores it.
You can use it to remove the string you return a pointer to in Process, from memory. Do not remove this string before the call to Stored or the call to the Destructor.
After storing an engine the pointers to the Request, Response and Adapters Set objects should be considered as invalid. The system will set these pointers again, when it take the adapter out of the storage. You can "play it safe" and set them to NULL in this function (although no one can access them when the engine is in storage).
Reimplemented in BnPython.
Definition at line 157 of file DcEngine.h.
The documentation for this class was generated from the following file:
- Beesnest/Interfaces/DcEngine.h
