plugin.hpp

Go to the documentation of this file.
00001 #ifndef plugin_PLUGIN_HPP_INCLUDED
00002 #define plugin_PLUGIN_HPP_INCLUDED 1
00003 
00004 #include <s11n.net/s11n/plugin/path_finder.hpp>
00005 #include <s11n.net/s11n/plugin/plugin_config.hpp>
00006 
00007 //Added by Damien to make Windows compile work
00008 //#include <s11n.net/s11n/export.hpp> // S11N_EXPORT_API
00009 // ^^^ removed by stephan because it breaks the build tree on Unix
00010 // platforms because the plugins dir must be built before the s11n
00011 // dir, but export.hpp is not put in place until the s11n subdir is
00012 // built. The reason for that structure is to cause circular deps like
00013 // this one to explicitly break the build, so at least it did what it
00014 // was supposed to. :)
00015 #if !defined(S11N_EXPORT_API)
00016 #ifdef WIN32
00017 #  ifdef S11N_EXPORTS
00018 #    define S11N_EXPORT_API __declspec(dllexport)
00019 #  else
00020 #    define S11N_EXPORT_API __declspec(dllimport)
00021 #  endif
00022 #else
00023 #    define S11N_EXPORT_API
00024 #endif
00025 #endif
00026 
00027 namespace s11n {
00028     /**
00029        The plugin namespace encapsulates the braindeadly basic API
00030        for loading plugins.
00031 
00032        This namespace is an optional component of the s11n framework,
00033        as it requires some platform-specific calls to open DLLs.
00034 
00035        Some behaviours in this API are defined as "platform
00036        specific", essentially meaning a combination of two things:
00037 
00038        a) Your operating system.
00039 
00040        b) The DLL loader this API is configured to use.
00041 
00042        If you don't know which DLL loader is built with your copy
00043        of this library, there are ways to find out:
00044            
00045        a) Under Win32, plugins using the native LoadModule()
00046        function, and are thus always enabled. Win32 plugins are,
00047        however, currently completely untested.
00048 
00049        b) Unix: look in plugin_config.hpp. If
00050        s11n_CONFIG_HAVE_LIBLTDL is set to a true value (not zero)
00051        then this library is built with libltdl. If
00052        s11n_CONFIG_HAVE_LIBLTDL is true, libdl is used (libltdl
00053        trumps libdl). If neither are true, your tree was built
00054        without plugins support.  Using ldd to find out which DLL
00055        lib is used is not really accurate because libdl or libltdl
00056        might be linked in to your app for reasons unrelated to
00057        this library.
00058 
00059     */
00060     namespace plugin
00061     {
00062         /**
00063            The shared lookup path for plugins. It is
00064            initialized to contain a path and list of
00065            extensions defined in plugin_config.hpp.
00066         */
00067         path_finder & path();
00068 
00069         /**
00070            Returns path().find( basename ).
00071         */
00072         //Added by Damien to make Windows compile work
00073       S11N_EXPORT_API std::string find( const std::string & basename );
00074 
00075         /**
00076            Uses find(basename) to search for a file and, if
00077            successful, opens it using a platforms-specific DLL
00078            opener.  It does not manipulate the DLL except to
00079            open it. The handle to the DLL is lost: it will be
00080            closed by the OS when the application exits. (The
00081            reasons for this are documented in the paper
00082            entitled "Classloading in C++", available from
00083            http://s11n.net/papers/.)
00084 
00085            Returns the path to the DLL, or an empty string on
00086            error. There is currently no way of knowing what
00087            the error might have been.
00088 
00089            The path() is used to find the DLL. If basename is
00090            an absolute path to an existing file, it will be
00091            used as-is, which means that a client-specified
00092            path_finder object may be used to find DLLs, and
00093            then pass them to this function to do the
00094            platform-specific work of opening the DLL.
00095         */
00096         //Added by Damien to make Windows compile work
00097       S11N_EXPORT_API std::string open( const std::string & basename );
00098 
00099         /**
00100            Called immediately after open() fails, it returns a
00101            platforms-specific error string.
00102 
00103            On platforms using libdl or libltdl, this function
00104            returns the result of calling dlerror() or
00105            lt_dlerror(), respectively.  On Windows platforms
00106            it always returns an empty string (anyone now how
00107            to get such error strings from Windows?).
00108 
00109            Calling this twice in a row will, without calling
00110            open() in between always cause an empty string to
00111            be returned on the second call. See the man pages
00112            for dlerror() or lt_dlerror() for more details on
00113            this, though this function also behaves that way
00114            under Win32.
00115 
00116         */
00117         //Added by Damien to make Windows compile work
00118       S11N_EXPORT_API std::string dll_error();
00119 
00120     } // namespace plugin
00121 } // namespace s11n
00122 
00123 
00124 #endif // plugin_PLUGIN_HPP_INCLUDED

Generated on Sat Mar 20 12:29:24 2010 for libs11n-1.2.10 by  doxygen 1.6.1