Beesnest/Interfaces/DcEngine.h

Go to the documentation of this file.

/*
Copyright 2007 Erez Bibi (erezbibi@users.sourceforge.net)
This file is part of Beesnest.
Beesnest is released under the GNU General Public License.
But this file is in the public domain, you can do whatever you want with it.
*/

#ifndef __IDC_ENGINE
#define __IDC_ENGINE

#include "BufferHolder.h"
#include "DcRequest.h"
#include "DcResponse.h"
#include "DcAdaptersSet.h"

/**
 * This is the interface for a scripting engine Beesnest will get. It uses
 * <b>IdcResponse</b>, <b>IdcRequest</b> and <b>IdcAdaptersSet</b> ( you don't
 * implement these three interfaces, Beesnest does). <br>
 *
 * When the system first gets an engine it calls the <b>Prepare</b> 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.
 * <p>
 * For every (part of a) buffer that needs to be processed by this engine, the
 * system will call the <b>Process</b> 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.
 * <p>
 * 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
 * <b>Stored</b> 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!
 * <p>
 * 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.
 * <p>
 * The library that hosts the implementation of an IdcEngine has to have at last
 * one function: <br>
 * <b> bool GetEngine (IdcEngine** pp_engine,
 *                      const char* name,
 *                      bool (*pGetParam)(const char*, char*, int)) </b>
 * <br>
 * 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.
 * <p>
 * Other optional functions of the engine library can be:<br>
 * <b> void Init (); </b> and <b> void Term (); </b> 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.
 * <p>
 * If the name of an engine object is "MyEngine", then this object has to (or
 * can) read its configuration from "Engines->MyEngine".
 *
 * <p>
 * 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 <b>IsStorable</b> to
 * return True. This function is already implemented, and it just returns False.
 * When Beesnest stores an engine it calls the <b>Stored</b> 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.
 *
 * <p>
 * All interfaces uses BufferHolder to pass strings or buffers.
 */
class IdcEngine
{
public:
    /**
     * 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!
     */
    virtual ~IdcEngine () {}

    /**
     * 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.
     * <p>
     * @param preq Pointer to the page Request object.
     * @param pres Pointer to the page Response object.
     * @param pset Pointer to the user's Adapters Set object. This will be NULL
     *  if the client is not logged in!
     */
    virtual void Prepare (IdcRequest* preq, IdcResponse* pres,
        IdcAdaptersSet* pset) = 0;

    /**
     * This function processes (a part of) a script.
     * <p>
     * @param 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!
     * @param 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!
     * @param 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.
     * @return (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).
     * @throw 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.
     */
    virtual bool Process (BufferHolder code, BufferHolder& result,
        int size_limit) = 0;

    /**
     * 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
     */
    virtual bool IsStorable () { return false; }

    /**
     * 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.
     * <p>
     * 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).
     */
    virtual void Stored () {}

    /*
    The next two function are for the next version of Beesnest. I'm not calling
    them in this version (1.0).
    The first function will let the engine know that in the next call to Process,
    the "code" variable will be an already compiled script.
    The next function will ask for a (pointer to) a compiled version of the last
    script that was processed. If the engine doesn't have a compiled version, it
    will return False.
    The first function will never be called with an engine that return False
    for the second function call.
    */
    virtual void NextIsCompiled () {}
    virtual bool GetCompiledScript (BufferHolder& comp) { return false; }
};

#endif /* __IDC_ENGINE */