Beesnest/Interfaces/DcAdapter.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_ADAPTER
#define __IDC_ADAPTER

#include "BufferHolder.h"

/**
 * This is the interface (abstract class) for all the adapters that will be ever
 * written for the Beesnest project. To write an implementation of this
 * interface, inherit from it and implement all the functions. Then put your
 * new adapter in a dynamically loaded library (DLL for windoes, sa for Linux)
 * with a specific format.
 * <p>
 * An adapter is a server to the Beesnest system, which in turn is a server for
 * an HTTP client.
 * <p>
 * An object of this class will be passed just to one thread at a time. However
 * if you do not prevent it (using the <b>IsMultiUse</b> function) different
 * threads might use different objects of this adapter at the same time.
 * <p>
 * The library that hosts the implementation of an IdcAdapter has to have at
 * last one function: <br>
 *
 * <b> bool GetAdapter (IdcAdapter** pp_adapter,
 *                      const char* name,
 *                      bool (*pGetParam)(const char*, char*, int)) </b>
 * <br>
 * This function will return a pointer to the implementation of the adapter.
 * 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 used to access the server configuration
 * database. In this function the first "C" style string is the name of the
 * parameter you want to retrieve, the second string is a pre-allocated buffer
 * for the parameter value, and the last int is the length of this buffer. This
 * function will return True if the parameter exist, otherwise it will return
 * False. You are welcome to use this function and add your adapter
 * configuration data to the Beesnest configuration files.
 * <p>
 * If the name of an adapter object is "MyAdapter", then this object has to (or
 * can) read it's configuration from "Adapters->MyAdapter".
 * <p>
 * All interfaces use BufferHolder to pass strings or buffers.
 * <p>
 * You have to have a member string variable in the implementation of this
 * interface, that will hold the results from the Read function. Then you can
 * return a BufferHolder that holds this string to the user. The user MUST not
 * try to change this string. If you want to let the user to clear this string,
 * in some point (to clear memory space), set a Write call like Write("done")
 * that will do that.
 * <p>
 * You can throw a BufferHolder from Read or from Write. The buffer holder has
 * to point to an inner class string, that must be alive at least until the next
 * call to one of the class functions, or until the Destructor is called.<br>
 * It is not defined what the script engine will do with this exception. It
 * might let the script writer handle it, or it might stop the processing of
 * the script (and the page), and put the content of the BufferHolder in the
 * page the user will get. use it just in extreme cases. You should NOT throw
 * an exception from the constructor. This kind of exception might break the
 * Beesnest application. If you cannot initialize the adapter, you should throw
 * an exception from the first call to Read or Write.
 */
class IdcAdapter
{

public:

    /**
     * The Destructor is very important in an adapter implementation. Do not
     * count on the user to release anything. In some situations the system may
     * just delete the adapter without any advance notice, and the Destructor
     * has to make sure the adapter closes itself nicely.
     */
    virtual ~IdcAdapter () {}

    /**
     * Reads some data from the adapter.
     * <p>
     * @param address The address (or name) of data to read.
     * @return (BufferHolder) Holds the result string. This string has to stay
     *  alive at least until the next call to Read (or to the Destructor).
     * @throw (BufferHolder) A pointer to an inner string. You have to keep this
     *  string alive at least until the next call to this adapter (or until the
     *  call to the Destructor)
     */
    virtual BufferHolder Read (BufferHolder address) throw (BufferHolder) = 0;

    /**
     * Writes some data to the adapter.
     * <p>
     * @param address The address (or name) of data to write.
     * @param value The value to write to this address (Note that it might be
     * empty!).
     * @return (bool) True on success or False if the action failed.
     * @throw (BufferHolder) A pointer to an inner string. You have to keep this
     *  string alive at least until the next call to this adapter (or until the
     *  call to the Destructor)
     */
    virtual bool Write (BufferHolder address, BufferHolder value)
        throw (BufferHolder) = 0;

    /**
     * If you do not want more then one object from this adapter to exist at the
     * same time, return False from this function. This will overwrite what
     * ever the user sets in the configuration files.
     */
    virtual bool IsMultiUse ()
    { return true; }

};

#endif      // __IDC_ADAPTER