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

Generated on Wed Jun 4 21:45:46 2008 for libs11n-1.2.7 by  doxygen 1.5.3