wxdllloader

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 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 dll and shared library/object will both be used in the documentation to refer to the same thing: a .dll file under windows or .so or .sl one under unix.

example of using this class to dynamically load the strlen() function:

#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);
    }

no base class

include files

<wx/dynlib.h>

data structures

this header defines a platform-dependent wxdlltype typedef which stores a handle to a loaded dlls on the given platform.

members

wxdllloader::getdllext
wxdllloader::getprogramhandle
wxdllloader::getsymbol
wxdllloader::loadlibrary
wxdllloader::unloadlibrary

wxdllloader::getdllext

static wxstring getdllext()

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 ".dll" under windows or (usually) ".so" under unix.

wxdllloader::getprogramhandle

wxdlltype getprogramhandle()

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).

nb: this function is unix specific. it will always fail under windows or os/2.

wxdllloader::getsymbol

void * getsymbol(wxdlltype dllhandle, const wxstring& name)

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.

parameters

dllhandle

valid handle previously returned by loadlibrary

name

name of the symbol.

wxdllloader::loadlibrary

wxdlltype loadlibrary(const wxstring & libname, bool* success = null)

this function loads a shared library into memory, with 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 success parameter to test if it is valid. if the handle is valid, the library must be unloaded later with unloadlibrary.

parameters

libname

name of the shared object to load.

success

may point to a bool variable which will be set to true or false; may also be null.

wxdllloader::unloadlibrary

void unloadlibrary(wxdlltype dllhandle)

this function unloads the shared library. the handle dllhandle must have been returned by loadlibrary previously.