This is the interface (abstract class) for all the adapters that will be ever written for the Beesnest project. More...

#include <DcAdapter.h>

Inheritance diagram for IdcAdapter:

Public Member Functions
virtual	~IdcAdapter ()
	The Destructor is very important in an adapter implementation.
virtual BufferHolder	Read (BufferHolder address)=0 throw (BufferHolder)
	Reads some data from the adapter.
virtual bool	Write (BufferHolder address, BufferHolder value)=0 throw (BufferHolder)
	Writes some data to the adapter.
virtual bool	IsMultiUse ()
	If you do not want more then one object from this adapter to exist at the same time, return False from this function.

Detailed Description

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.

An adapter is a server to the Beesnest system, which in turn is a server for an HTTP client.

An object of this class will be passed just to one thread at a time. However if you do not prevent it (using the IsMultiUse function) different threads might use different objects of this adapter at the same time.

The library that hosts the implementation of an IdcAdapter has to have at last one function:

bool GetAdapter (IdcAdapter** pp_adapter, const char* name, bool (*pGetParam)(const char*, char*, int))
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.

If the name of an adapter object is "MyAdapter", then this object has to (or can) read it's configuration from "Adapters->MyAdapter".

All interfaces use BufferHolder to pass strings or buffers.

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.

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.
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.

Definition at line 69 of file DcAdapter.h.

Constructor & Destructor Documentation

virtual IdcAdapter::~IdcAdapter ( ) [inline, virtual]

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.

Definition at line 80 of file DcAdapter.h.

Member Function Documentation

virtual bool IdcAdapter::IsMultiUse ( ) [inline, virtual]

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.

Reimplemented in BnSerialPort, and BnSQLite.

Definition at line 113 of file DcAdapter.h.

virtual BufferHolder IdcAdapter::Read ( BufferHolder address ) throw (BufferHolder) [pure virtual]

Reads some data from the adapter.

Parameters:

address The address (or name) of data to read.

Returns:: (BufferHolder) Holds the result string. This string has to stay alive at least until the next call to Read (or to the Destructor).

Exceptions:

(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)

Implemented in BnSerialPort, and BnSQLite.

virtual bool IdcAdapter::Write	(	BufferHolder	address,
		BufferHolder	value
	)		throw (BufferHolder) `[pure virtual]`

Writes some data to the adapter.