From: Vadim Zeitlin Date: Mon, 4 Aug 2003 14:05:00 +0000 (+0000) Subject: added Unload(handle); updated the docs X-Git-Url: https://git.saurik.com/wxWidgets.git/commitdiff_plain/169948a05ff0707ecddc12f9e26d2a0a994fa0ae?ds=inline added Unload(handle); updated the docs git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@22578 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- diff --git a/docs/latex/wx/dynlib.tex b/docs/latex/wx/dynlib.tex index 2e7fc08b18..c9da6923b0 100644 --- a/docs/latex/wx/dynlib.tex +++ b/docs/latex/wx/dynlib.tex @@ -12,57 +12,122 @@ \section{\class{wxDynamicLibrary}}\label{wxdynamiclibrary} wxDynamicLibrary is a class representing dynamically loadable library -(Windows DLL, shared library under Unix etc.). It is implemented as a wrapper -to \helpref{wxDllLoader}{wxdllloader}. +(Windows DLL, shared library under Unix etc.). Just create an object of +this class to load a library and don't worry about unloading it -- it will be +done in the objects destructor automatically. -\wxheading{See also} +% deprecated now... +% +%\wxheading{See also} +% +%\helpref{wxDllLoader}{wxdllloader} -\helpref{wxDllLoader}{wxdllloader} \membersection{wxDynamicLibrary::wxDynamicLibrary}\label{wxdynamiclibrarywxdynamiclibrary} \func{}{wxDynamicLibrary}{\void} -\func{}{wxDynamicLibrary}{\param{const wxString\& }{name}} +\func{}{wxDynamicLibrary}{\param{const wxString\& }{name}, \param{int }{flags = wxDL\_DEFAULT}} Constructor. Second form calls \helpref{Load}{wxdynamiclibraryload}. + +\membersection{wxDynamicLibrary::CanonicalizeName}\label{wxdynamiclibrarycanonicalizename} + +\func{wxString}{CanonicalizeName}{\param{const wxString\& }{name}, \param{wxDynamicLibraryCategory cat = wxDL\_LIBRARY}} + +Returns the platform-specific full name for the library called \arg{name}. E.g. +it adds a {\tt ".dll"} extension under Windows and {\tt "lib"} prefix and +{\tt ".so"}, {\tt ".sl"} or maybe {\tt ".dylib"} extension under Unix. + +The possible values for \arg{cat} are: +\begin{twocollist} + \twocolitem{wxDL\_LIBRARY}{normal library} + \twocolitem{wxDL\_MODULE}{a loadable module or plugin} +\end{twocollist} + +\wxheading{See also} + +\helpref{CanonicalizePluginName}{wxdynamiclibrarycanonicalizepluginname} + + +\membersection{wxDynamicLibrary::CanonicalizePluginName}\label{wxdynamiclibrarycanonicalizepluginname} + +\func{wxString}{CanonicalizePluginName}{\param{const wxString\& }{name}, \param{wxPluginCategory cat = wxDL\_PLUGIN\_GUI}} + +This function does the same thing as +\helpref{CanonicalizeName}{wxdynamiclibrarycanonicalizename} but for wxWindows +plugins. The only difference is that compiler and version information are added +to the name to ensure that the plugin which is going to be loaded will be +compatible with the main program. + +The possible values for \arg{cat} are: +\begin{twocollist} + \twocolitem{wxDL\_PLUGIN\_GUI}{plugin which uses GUI classes (default)} + \twocolitem{wxDL\_PLUGIN\_BASE}{plugin which only uses wxBase} +\end{twocollist} + + \membersection{wxDynamicLibrary::Detach}\label{wxdynamiclibrarydetach} \func{wxDllType}{Detach}{\void} Detaches this object from its library handle, i.e. the object will not unload the library any longer in its destructor but it is now the callers -responsability to do this. +responsability to do this using \helpref{Unload}{wxdynamiclibraryunload}. + + +\membersection{wxDynamicLibrary::GetSymbol}\label{wxdynamiclibrarygetsymbol} + +\constfunc{void*}{GetSymbol}{\param{const wxString\& }{name}} + +Returns pointer to symbol {\it name} in the library or NULL if the library +contains no such symbol. + +\wxheading{See also} + +\helpref{wxDYNLIB\_FUNCTION}{wxdynlibfunction} + \membersection{wxDynamicLibrary::IsLoaded}\label{wxdynamiclibraryisloaded} \constfunc{bool}{IsLoaded}{\void} -Returns true if the library was successfully loaded, false otherwise. +Returns \true if the library was successfully loaded, \false otherwise. + \membersection{wxDynamicLibrary::Load}\label{wxdynamiclibraryload} -\func{bool}{Load}{\param{const wxString\& }{name}} +\func{bool}{Load}{\param{const wxString\& }{name}, \param{int }{flags = wxDL\_DEFAULT}} -Loads DLL into memory. +Loads DLL with the given \arg{name} into memory. The \arg{flags} argument can +be a combination of the following bits: +\begin{twocollist} +\twocolitem{wxDL\_LAZY}{equivalent of RTLD\_LAZY under Unix, ignored elsewhere} +\twocolitem{wxDL\_NOW}{equivalent of RTLD\_NOW under Unix, ignored elsewhere} +\twocolitem{wxDL\_GLOBAL}{equivalent of RTLD\_GLOBAL under Unix, ignored elsewhere} +\twocolitem{wxDL\_VERBATIM}{don't try to append the appropriate extension to +the library name (this is done by default).} +\end{twocollist} -Returns true if the library was successfully loaded, false otherwise. +Returns \true if the library was successfully loaded, \false otherwise. -\membersection{wxDynamicLibrary::Unload}\label{wxdynamiclibraryunload} +\wxheading{See also} -\func{void}{Unload}{\void} +\helpref{}{} -Unloads the library from memory. -\membersection{wxDynamicLibrary::GetSymbol}\label{wxdynamiclibrarygetsymbol} +\membersection{wxDynamicLibrary::Unload}\label{wxdynamiclibraryunload} -\constfunc{void*}{GetSymbol}{\param{const wxString\& }{name}} +\func{void}{Unload}{\void} -Returns pointer to symbol {\it name} in the library or NULL if the library -contains no such symbol. +\func{static void}{Unload}{\param{wxDllType }{handle}} -\wxheading{See also} +Unloads the library from memory. wxDynamicLibrary object automatically calls +this method from its destructor if it had been successfully loaded. -\helpref{wxDYNLIB\_FUNCTION}{wxdynlibfunction} +The second version is only used if you need to keep the library in memory +during a longer period of time than the scope of the wxDynamicLibrary object. +In this case you may call \helpref{Detach}{wxdynamiclibrarydetach} and store +the handle somewhere and call this static method later to unload it. diff --git a/include/wx/dynlib.h b/include/wx/dynlib.h index d718cb6b9a..52f9ddc03b 100644 --- a/include/wx/dynlib.h +++ b/include/wx/dynlib.h @@ -141,8 +141,11 @@ public: // doing this wxDllType Detach() { wxDllType h = m_handle; m_handle = 0; return h; } + // unload the given library handle (presumably returned by Detach() before) + static void Unload(wxDllType handle); + // unload the library, also done automatically in dtor - void Unload(); + void Unload() { if ( IsLoaded() ) { Unload(m_handle); m_handle = 0; } } // Return the raw handle from dlopen and friends. wxDllType GetLibHandle() const { return m_handle; } @@ -168,8 +171,9 @@ public: // return name of wxWindows plugin (adds compiler and version info // to the filename): - static wxString CanonicalizePluginName(const wxString& name, - wxPluginCategory cat); + static wxString + CanonicalizePluginName(const wxString& name, + wxPluginCategory cat = wxDL_PLUGIN_GUI); // return plugin directory on platforms where it makes sense and empty // string on others: