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