mac paths updated

[wxWidgets.git] / interface / dynlib.h

diff --git a/interface/dynlib.h b/interface/dynlib.h
index 2ca03051776d9416f7752adda4de7c2d90660243..3392ef4f1910ab5075bffff91b956c0bad03cfc0 100644 (file)
--- a/interface/dynlib.h
+++ b/interface/dynlib.h
@@ -1,6 +1,6 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        dynlib.h
 /////////////////////////////////////////////////////////////////////////////
 // Name:        dynlib.h

-// Purpose:     interface of wxDynamicLibraryDetails
+// Purpose:     interface of wxDynamicLibrary and wxDynamicLibraryDetails

 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license


@@ -10,14 +10,14 @@
     @class wxDynamicLibraryDetails
     @wxheader{dynlib.h}
 
     @class wxDynamicLibraryDetails
     @wxheader{dynlib.h}
 

-    This class is used for the objects returned by
-    wxDynamicLibrary::ListLoaded method and
-    contains the information about a single module loaded into the address space of
-    the current process. A module in this context may be either a dynamic library
-    or the main program itself.
+    This class is used for the objects returned by the
+    wxDynamicLibrary::ListLoaded() method and contains the information about a
+    single module loaded into the address space of the current process. A
+    module in this context may be either a dynamic library or the main program
+    itself.

 
     @library{wxbase}
 
     @library{wxbase}

-    @category{FIXME}
+    @category{appmanagement}

 */
 class wxDynamicLibraryDetails
 {
 */
 class wxDynamicLibraryDetails
 {


@@ -26,33 +26,32 @@ public:
         Retrieves the load address and the size of this module.
 
         @param addr
         Retrieves the load address and the size of this module.
 
         @param addr

-            the pointer to the location to return load address in, may be
-            @NULL
+            The pointer to the location to return load address in, may be
+            @NULL.

         @param len
         @param len

-            pointer to the location to return the size of this module in
-            memory in, may be @NULL
+            Pointer to the location to return the size of this module in
+            memory in, may be @NULL.

 
 

-        @returns @true if the load address and module size were retrieved, @false
-                 if this information is not available.
+        @return @true if the load address and module size were retrieved,
+                 @false if this information is not available.

     */
     bool GetAddress(void** addr, size_t len) const;
 
     /**
     */
     bool GetAddress(void** addr, size_t len) const;
 
     /**

-        Returns the base name of this module, e.g. @c kernel32.dll or
-        @c libc-2.3.2.so.
+        Returns the base name of this module, e.g. @c "kernel32.dll" or
+        @c "libc-2.3.2.so".

     */
     wxString GetName() const;
 
     /**
         Returns the full path of this module if available, e.g.
     */
     wxString GetName() const;
 
     /**
         Returns the full path of this module if available, e.g.

-        @c c:\windows\system32\kernel32.dll or
-        @c /lib/libc-2.3.2.so.
+        @c "c:\windows\system32\kernel32.dll" or @c "/lib/libc-2.3.2.so".

     */
     wxString GetPath() const;
 
     /**
     */
     wxString GetPath() const;
 
     /**

-        Returns the version of this module, e.g. @c 5.2.3790.0 or
-        @c 2.3.2. The returned string is empty if the version information is not
+        Returns the version of this module, e.g. @c "5.2.3790.0" or @c "2.3.2".
+        The returned string is empty if the version information is not

         available.
     */
     wxString GetVersion() const;
         available.
     */
     wxString GetVersion() const;


@@ -61,131 +60,23 @@ public:
 
 
 /**
 
 
 /**

-    @class wxDllLoader
-    @wxheader{dynlib.h}
-
-    @b Deprecation note: This class is deprecated since version 2.4 and is
-    not compiled in by default in version 2.6 and will be removed in 2.8. Please
-    use wxDynamicLibrary instead.
-
-    wxDllLoader is a class providing an interface similar to Unix's @c dlopen(). It
-    is used by the wxLibrary framework and manages the actual
-    loading of shared libraries and the resolving of symbols in them. There are no
-    instances of this class, it simply serves as a namespace for its static member
-    functions.
-
-    Please note that class wxDynamicLibrary provides
-    alternative, friendlier interface to wxDllLoader.
-
-    The terms @e DLL and @e shared library/object will both be used in the
-    documentation to refer to the same thing: a @c .dll file under Windows or
-    @c .so or @c .sl one under Unix.
-
-    Example of using this class to dynamically load the @c strlen() function:
-
-    @code
-    #if defined(__WXMSW__)
-        static const wxChar *LIB_NAME = _T("kernel32");
-        static const wxChar *FUNC_NAME = _T("lstrlenA");
-    #elif defined(__UNIX__)
-        static const wxChar *LIB_NAME = _T("/lib/libc-2.0.7.so");
-        static const wxChar *FUNC_NAME = _T("strlen");
-    #endif
-
-        wxDllType dllHandle = wxDllLoader::LoadLibrary(LIB_NAME);
-        if ( !dllHandle )
-        {
-            ... error ...
-        }
-        else
-        {
-            typedef int (*strlenType)(char *);
-            strlenType pfnStrlen = (strlenType)wxDllLoader::GetSymbol(dllHandle,
-    FUNC_NAME);
-            if ( !pfnStrlen )
-            {
-                ... error ...
-            }
-            else
-            {
-                if ( pfnStrlen("foo") != 3 )
-                {
-                    ... error ...
-                }
-                else
-                {
-                    ... ok! ...
-                }
-            }
-
-            wxDllLoader::UnloadLibrary(dllHandle);
-        }
-    @endcode
-
-    @library{wxbase}
-    @category{appmanagement}
+    Dynamic library category used with wxDynamicLibrary::CanonicalizeName().

 */
 */

-class wxDllLoader
+enum wxDynamicLibraryCategory

 {
 {

-public:
-    /**
-        Returns the string containing the usual extension for shared libraries for the
-        given systems (including the leading dot if not empty).
-        For example, this function will return @c ".dll" under Windows or (usually)
-        @c ".so" under Unix.
-    */
-    static wxString GetDllExt();
-
-    /**
-        This function returns a valid handle for the main program itself. Notice that
-        the @NULL return value is valid for some systems (i.e. doesn't mean that
-        the function failed).
-        @note This function is Unix specific. It will always fail under Windows
-        or OS/2.
-    */
-    wxDllType GetProgramHandle();
-
-    /**
-        This function resolves a symbol in a loaded DLL, such as a variable or
-        function name.
-        Returned value will be @NULL if the symbol was not found in the DLL or if
-        an error occurred.
-
-        @param dllHandle
-            Valid handle previously returned by
-            LoadLibrary
-        @param name
-            Name of the symbol.
-    */
-    void* GetSymbol(wxDllType dllHandle, const wxString& name);
-
-    /**
-        This function loads a shared library into memory, with @a libname being the
-        name of the library: it may be either the full name including path and
-        (platform-dependent) extension, just the basename (no path and no extension)
-        or a basename with extension. In the last two cases, the library will be
-        searched in all standard locations.
-        Returns a handle to the loaded DLL. Use @a success parameter to test if it
-        is valid. If the handle is valid, the library must be unloaded later with
-        UnloadLibrary().
-
-        @param libname
-            Name of the shared object to load.
-        @param success
-            May point to a bool variable which will be set to @true or
-            @false; may also be @NULL.
-    */
-    wxDllType LoadLibrary(const wxString& libname,
-                          bool* success = NULL);
-
-    /**
-        This function unloads the shared library. The handle @a dllhandle must have
-        been returned by LoadLibrary() previously.
-    */
-    void UnloadLibrary(wxDllType dllhandle);
+    wxDL_LIBRARY,   ///< Standard library.
+    wxDL_MODULE     ///< Loadable module/plugin.

 };
 
 };
 

-
+/**
+    Dynamic library plugin category used with
+    wxDynamicLibrary::CanonicalizePluginName().
+*/
+enum wxPluginCategory
+{
+    wxDL_PLUGIN_GUI,    ///< Plugin that uses GUI classes.
+    wxDL_PLUGIN_BASE    ///< wxBase-only plugin.
+};

 
 /**
     @class wxDynamicLibrary
 
 /**
     @class wxDynamicLibrary


@@ -193,40 +84,46 @@ public:
 
     wxDynamicLibrary is a class representing dynamically loadable library
     (Windows DLL, shared library under Unix etc.). Just create an object of
 
     wxDynamicLibrary is a class representing dynamically loadable library
     (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.
+    this class to load a library and don't worry about unloading it -- it will
+    be done in the objects destructor automatically.
+
+    The following flags can be used with wxDynamicLibrary() or Load():
+
+    @beginStyleTable
+    @style{wxDL_LAZY}
+           Equivalent of RTLD_LAZY under Unix, ignored elsewhere.
+    @style{wxDL_NOW}
+           Equivalent of RTLD_NOW under Unix, ignored elsewhere.
+    @style{wxDL_GLOBAL}
+           Equivalent of RTLD_GLOBAL under Unix, ignored elsewhere.
+    @style{wxDL_VERBATIM}
+           Don't try to append the appropriate extension to the library name
+           (this is done by default).
+    @style{wxDL_DEFAULT}
+           Default flags, same as wxDL_NOW currently.
+    @style{wxDL_QUIET}
+           Don't log an error message if the library couldn't be loaded.
+    @endStyleTable

 
     @library{wxbase}
 
     @library{wxbase}

-    @category{FIXME}
-
-    @see wxDynamicLibrary::CanonicalizePluginName
+    @category{appmanagement}

 */
 class wxDynamicLibrary
 {
 public:
 */
 class wxDynamicLibrary
 {
 public:

-    //@{

     /**
     /**

-        Constructor. Second form calls Load().
+        Default constructor.

     */
     wxDynamicLibrary();
     */
     wxDynamicLibrary();

-    wxDynamicLibrary(const wxString& name,
-                     int flags = wxDL_DEFAULT);
-    //@}
-

     /**
     /**

-        Returns the platform-specific full name for the library called @e name. E.g.
-        it adds a @c ".dll" extension under Windows and @c "lib" prefix and
-        @c ".so", @c ".sl" or maybe @c ".dylib" extension under Unix.
-        The possible values for @a cat are:
-
-
-        wxDL_LIBRARY
-
-        normal library
-
-        wxDL_MODULE
+        Constructor. Calls Load() with the given @a name.
+    */
+    wxDynamicLibrary(const wxString& name, int flags = wxDL_DEFAULT);

 
 

-        a loadable module or plugin
+    /**
+        Returns the platform-specific full name for the library called @a name.
+        E.g. it adds a @c ".dll" extension under Windows and @c "lib" prefix
+        and @c ".so", @c ".sl" or @c ".dylib" extension under Unix.

 
         @see CanonicalizePluginName()
     */
 
         @see CanonicalizePluginName()
     */


@@ -234,29 +131,18 @@ public:
                                      wxDynamicLibraryCategory cat = wxDL_LIBRARY);
 
     /**
                                      wxDynamicLibraryCategory cat = wxDL_LIBRARY);
 
     /**

-        This function does the same thing as
-        CanonicalizeName() but for wxWidgets
-        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 @a cat are:
-
-
-        wxDL_PLUGIN_GUI
-
-        plugin which uses GUI classes (default)
-
-        wxDL_PLUGIN_BASE
-
-        plugin which only uses wxBase
+        This function does the same thing as CanonicalizeName() but for
+        wxWidgets 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.

     */
     static wxString CanonicalizePluginName(const wxString& name,
                                            wxPluginCategory cat = wxDL_PLUGIN_GUI);
 
     /**
     */
     static wxString CanonicalizePluginName(const wxString& name,
                                            wxPluginCategory cat = wxDL_PLUGIN_GUI);
 
     /**

-        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
-        responsibility to do this using Unload().
+        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 responsibility to do this using Unload().

     */
     wxDllType Detach();
 
     */
     wxDllType Detach();
 


@@ -267,8 +153,8 @@ public:
     static wxDllType GetProgramHandle();
 
     /**
     static wxDllType GetProgramHandle();
 
     /**

-        Returns pointer to symbol @a name in the library or @NULL if the library
-        contains no such symbol.
+        Returns pointer to symbol @a name in the library or @NULL if the
+        library contains no such symbol.

 
         @see wxDYNLIB_FUNCTION()
     */
 
         @see wxDYNLIB_FUNCTION()
     */


@@ -276,19 +162,19 @@ public:
 
     /**
         This function is available only under Windows as it is only useful when
 
     /**
         This function is available only under Windows as it is only useful when

-        dynamically loading symbols from standard Windows DLLs. Such functions have
-        either @c 'A' (in ANSI build) or @c 'W' (in Unicode, or wide
-        character build) suffix if they take string parameters. Using this function you
-        can use just the base name of the function and the correct suffix is appende
-        automatically depending on the current build. Otherwise, this method is
-        identical to GetSymbol().
+        dynamically loading symbols from standard Windows DLLs. Such functions
+        have either @c 'A' (in ANSI build) or @c 'W' (in Unicode, or wide
+        character build) suffix if they take string parameters. Using this
+        function, you can use just the base name of the function and the
+        correct suffix is appended automatically depending on the current
+        build. Otherwise, this method is identical to GetSymbol().

     */
     void* GetSymbolAorW(const wxString& name) const;
 
     /**
     */
     void* GetSymbolAorW(const wxString& name) const;
 
     /**

-        Returns @true if the symbol with the given @a name is present in the dynamic
-        library, @false otherwise. Unlike GetSymbol(),
-        this function doesn't log an error message if the symbol is not found.
+        Returns @true if the symbol with the given @a name is present in the
+        dynamic library, @false otherwise. Unlike GetSymbol(), this function
+        doesn't log an error message if the symbol is not found.

 
         @since 2.5.4
     */
 
         @since 2.5.4
     */


@@ -300,61 +186,41 @@ public:
     bool IsLoaded() const;
 
     /**
     bool IsLoaded() const;
 
     /**

-        This static method returns an array() containing the details
-        of all modules loaded into the address space of the current project, the array
-        elements are object of @c wxDynamicLibraryDetails class. The array will
-        be empty if an error occurred.
-        This method is currently implemented only under Win32 and Linux and is useful
-        mostly for diagnostics purposes.
+        This static method returns a wxArray containing the details of all
+        modules loaded into the address space of the current project. The array
+        elements are objects of the type: wxDynamicLibraryDetails. The array
+        will be empty if an error occurred.
+
+        This method is currently implemented only under Win32 and Linux and is
+        useful mostly for diagnostics purposes.

     */
     static wxDynamicLibraryDetailsArray ListLoaded();
 
     /**
         Loads DLL with the given @a name into memory. The @a flags argument can
     */
     static wxDynamicLibraryDetailsArray ListLoaded();
 
     /**
         Loads DLL with the given @a name into memory. The @a flags argument can

-        be a combination of the following bits:
-
-        wxDL_LAZY
-
-        equivalent of RTLD_LAZY under Unix, ignored elsewhere
-
-        wxDL_NOW
-
-        equivalent of RTLD_NOW under Unix, ignored elsewhere
-
-        wxDL_GLOBAL
-
-        equivalent of RTLD_GLOBAL under Unix, ignored elsewhere
-
-        wxDL_VERBATIM
-
-        don't try to append the appropriate extension to
-        the library name (this is done by default).
-
-        wxDL_DEFAULT
-
-        default flags, same as wxDL_NOW currently
-
-        wxDL_QUIET
-
-        don't log an error message if the library couldn't be
-        loaded.
+        be a combination of the styles outlined in the class description.

 
         Returns @true if the library was successfully loaded, @false otherwise.
     */
     bool Load(const wxString& name, int flags = wxDL_DEFAULT);
 
 
         Returns @true if the library was successfully loaded, @false otherwise.
     */
     bool Load(const wxString& name, int flags = wxDL_DEFAULT);
 

-    //@{

     /**
     /**

-        Unloads the library from memory. wxDynamicLibrary object automatically calls
-        this method from its destructor if it had been successfully loaded.
-        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 Detach() and store
-        the handle somewhere and call this static method later to unload it.
+        Unloads the library from memory. wxDynamicLibrary object automatically
+        calls this method from its destructor if it had been successfully
+        loaded.

     */
     void Unload();
     */
     void Unload();

+    /**
+        Unloads the library from memory. wxDynamicLibrary object automatically
+        calls this method from its destructor if it had been successfully
+        loaded.
+
+        This version of Unload() 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 Detach() and store
+        the handle somewhere and call this static method later to unload it.
+    */

     static void Unload(wxDllType handle);
     static void Unload(wxDllType handle);

-    //@}

 };
 
 
 };