|
imebra
build 2011-09-18_22-24-41
|
|
imebra
build 2011-09-18_22-24-41
|
Imebra is not distributed as a dynamic module and probably will never be. This is due to the CPP language used to build the library and to the different conventions used by different compilers when they deal with the C++ function names.
Because of this, all the Imebra source files must be linked to your project by you. If you use the same C++ compiler to build your application and the Imebra library then you could create a dynamic module that includes the Imebra library.
The following sections describes how to include the Imebra source code in your project and how to call its functions.
Imebra heavily uses the stl library; if your development environment doesn't provide a modern stl, try to install stlport (http://www.stlport.org).
Imebra also needs the standard C library.
The path to the window.h file must be in the list of paths searched by the "include" statement.
The library uses the functions TryEnterCriticalSection() and SwitchToThread() which require the definition of the symbol _WIN32_WINNT in the C++ preprocessor. _WIN32_WINNT has to be set to 0x0400 or greater.
Imebra uses the iconv and the pthreads libraries. Please take care of updating the list of paths searched by the "include" statement. The following headers are necessary:
The application must be linked to the iconv and the pthread libraries.
Imebra is part of the Puntoexe Library and all its source code files are located in subfolders of the "library" directory, included in the distribution package.
The first step to add the Imebra library to your project is to add all the files in the following directories to your project:
The files in those directories are cpp source files. You must disable the use of the precompiled header for all the imebra source files.
The files in the following directories are header files and don't need to be included in your project, but nothing harmful happen if you do include them (please note that EVC4 needs them):
The compiler must support the RTTI.
If you are compiling the application on Windows, define the preprocessor symbol WIN32 in your project's properties.
If you are compiling the application for Windows NT, 2000, XP or Vista, then define the preprocessor symbol _WIN32_WINNT to 0x0400 or greater.
Please check that all the following tasks have been performed:
If you want to call or reference an Imebra class or function you have to include the Imebra header to all the files that intend to deal with Imebra.
For your convenience, a single include file called "imebra.h" is available in the directory "library/imebra/include". The "imebra.h" file includes all the main header files used by the Imebra sources.
If your compiler supports the precompiled headers, then a better place where to include "imebra.h" could be the source file used to generate the precompiled headers (usually "stdafx.h" in the Microsoft Visual C++ compiler).
Most of the Imebra classes derive from the object puntoexe::baseObject. This object has a reference counter that keeps track of he number of variables that reference it. When the reference counter reaches 0 it means that no variable is referencing the object and it can be deleted.
Your application should not try to increase/decrease the reference counter "manually" by using the addRef() and release() methods, but it should use the smart pointer provided by Imebra (see The Imebra smart pointer).
Most of the Imebra functions use a smart pointer in order to count the references to an object.
The smart pointer is declared in the namespace puntoexe and is a class called ptr (puntoexe::ptr).
Why does Imebra use a custom implementation of the smart pointer when there are already some out there? Because the pointer is used also to track object that should be removed but in practice are not; for instance, the puntoexe::memory classes sometime are not deleted when they counter reaches 0, but they are stored in puntoexe::memoryPool and reused later. Each Imebra object can veto its deletion by returning false when a call to puntoexe::baseObject::preDelete() is made.
So, your application should use puntoexe::ptr instead of increasing/decreasing the reference counters "manually" by calling puntoexe::baseObject::addRef() and puntoexe::baseObject::release().
All the base services classes of the Imebra library are declared in the namespace puntoexe, while the normal classes are in the namespace puntoexe::imebra.
So, to create a dataSet, you should use the following line:
puntoexe::ptr<puntoexe::imebra::dataSet> myDataset(new puntoexe::imebra::dataSet);
Or you could use the C++ statement "using" in order to declare the namespace that your application is going to use.
When an error occurs the Imebra library throws an exception. Some exceptions are catched and solved by the library, but some of them could reach your application.
In this case, your application should catch the exception and try to resolve the error or display a message to the user or, in the worst case, quit.
All the Imebra exceptions are tracked by the statically allocated object puntoexe::exceptionsManager. This object follows an exception while it travels through all the functions until it finally reach your application: when your application catches an Imebra exception it MUST query the puntoexe::exceptionsManager in order to retrieve extended informations related to the exception.
The informations returned by puntoexe::exceptionsManager include the complete stack dump at the moment of the creation of the exception and the reason of the error. Those informations could be logged somewhere by your application, specially if the exception cannot be handled and the application will quit.
Please note that your application MUST query puntoexe::exceptionsManager for the extend informations even if they are not used.
