00001 /* 00002 Copyright 2007 Erez Bibi (erezbibi@users.sourceforge.net) 00003 This file is part of Beesnest. 00004 Beesnest is released under the GNU General Public License. 00005 But this file is in the public domain, you can do whatever you want with it. 00006 */ 00007 00008 #ifndef __IDC_ADAPTERS_SET 00009 #define __IDC_ADAPTERS_SET 00010 00011 #include "BufferHolder.h" 00012 00013 /** 00014 * This interface is implemented by Beesnest!<br> 00015 * 00016 * This abstract class is the interface for <b>CdcAdaptersSet</b>. 00017 * <b>IdcEngine</b> can use this interface to create, use and release adapters. 00018 * An adapter can be either already created and saved in this set for the user, 00019 * or it can be newly created from the Adapters Bank. IdcEngine will get just 00020 * the adapter ID, and will use it when Reading, Writing or Releasing the 00021 * adapter. When the engine exits (when it is done with a script) it must call 00022 * <b>AdapterDone</b> on all the adapters IDs it used and didn't release. 00023 * <p> 00024 * The Read and Write functions might throw a BufferHolder exception. It is not 00025 * defined what the script engine should do with these exceptions. If the script 00026 * language support exceptions, the best thing will be to catch them and throw 00027 * a proper exception in the script itself (so the script writer can handle it). 00028 * If the script language does not support exceptions, the engine should probably 00029 * catch the exception print it on the page, and return (from Process) with 00030 * value of False. If the engine will ignore these exceptions, the thread will 00031 * abort, and the user will not get any response, that also might results in the 00032 * script interpreter doesn't close cleanly. So DO NOT ignore these exceptions! 00033 * You should copy the string this BufferHolder points to immediately (the 00034 * string should be valid until the next call to this adapter), remember that 00035 * this string does not have to end with NULL. 00036 * 00037 * <p> 00038 * All interfaces uses BufferHolder to pass strings or buffers. 00039 */ 00040 class IdcAdaptersSet 00041 { 00042 public: 00043 00044 /** 00045 * Empty virtual Destructor. 00046 */ 00047 virtual ~IdcAdaptersSet() {} 00048 00049 /** 00050 * Returns an ID of an adapter from the type 'name', or 0 if the user cannot 00051 * get this adapter at the moment. 00052 * <p> 00053 * @param name The desired adapter name. 00054 * @return (uint) The adapter ID or 0 if the user cannot get this adapter. 00055 */ 00056 virtual unsigned int GetAdapter (BufferHolder name) = 0; 00057 00058 /** 00059 * This function releases an adapter. If the adapter is "Storable", it will 00060 * not be saved for the user any more. 00061 * <p> 00062 * @param AID The adapter ID. 00063 * @param cf The engine does not use this parameter. 00064 */ 00065 virtual void ReleaseAdapter (unsigned int AID, bool cf = false) = 0; 00066 00067 /** 00068 * When an engine exits (done with a script) it must call this function on 00069 * every adapter ID it has (got with GetAdapter and didn't release). If 00070 * the adapter is not "Storable", the class will release (delete) it. If the 00071 * adapter is "Storable", the class will mark it as free, set the Start Idle 00072 * time (for the release idles thread), but keep the adapter in its memory. 00073 * <p> 00074 * @param AID The ID of the adapter an engine is done with. 00075 */ 00076 virtual void AdapterDone (unsigned int AID) = 0; 00077 00078 /** 00079 * This is the function that calls the adapter Read function. 00080 * <p> 00081 * @param AID The adapter ID. 00082 * @param address The address (or name) to read from. 00083 * @return (BufferHolder) Holds the result string or an empty string. 00084 * @throw (BufferHolder) Just pass an exception from the adapter. 00085 */ 00086 virtual BufferHolder Read (unsigned int AID, BufferHolder address) 00087 throw (BufferHolder) = 0; 00088 00089 /** 00090 * This is the function that calls the adapter Write function. When using 00091 * this function, you should make <b>value</b> optional in the script, and 00092 * pass this function an empty BufferHolder if it is missing (initialize a 00093 * BufferHolder with NULL will create it empty). 00094 * <p> 00095 * @param AID The adapter ID. 00096 * @param address The address (or name) to write to. 00097 * @param value The string to write to this address (Optional). 00098 * @return (bool) True on success. 00099 * @throw (BufferHolder) Just pass an exception from the adapter. 00100 */ 00101 virtual bool Write (unsigned int AID, BufferHolder address, BufferHolder value) 00102 throw (BufferHolder) = 0; 00103 }; 00104 00105 #endif /* __IDC_ADAPTERS_SET */ 00106
1.7.2