sal/inc/osl/module.h

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: module.h,v $
  10  * $Revision: 1.18 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30
  31 /** @HTML */
  32
  33 #ifndef _OSL_MODULE_H_
  34 #define _OSL_MODULE_H_
  35
  36 #       include <rtl/ustring.h>
  37 #       include <rtl/tencinfo.h>
  38
  39 #ifdef __cplusplus
  40 extern "C" {
  41 #endif
  42
  43 #ifdef SAL_DLLPREFIX
  44 #define SAL_MODULENAME(name) SAL_DLLPREFIX name SAL_DLLEXTENSION
  45 #else
  46 #define SAL_MODULENAME(name) name SAL_DLLEXTENSION
  47 #endif
  48
  49 #if defined(SAL_W32) || defined(SAL_OS2)
  50 #define SAL_MODULENAME_WITH_VERSION(name, version) name version SAL_DLLEXTENSION
  51
  52 #elif defined(SAL_UNX)
  53 #if defined(MACOSX)
  54 #define SAL_MODULENAME_WITH_VERSION(name, version) SAL_DLLPREFIX name ".dylib." version
  55 #else
  56 #define SAL_MODULENAME_WITH_VERSION(name, version) SAL_DLLPREFIX name SAL_DLLEXTENSION "." version
  57 #endif
  58
  59 #endif
  60
  61 #define SAL_LOADMODULE_DEFAULT    0x00000
  62 #define SAL_LOADMODULE_LAZY       0x00001
  63 #define SAL_LOADMODULE_NOW        0x00002
  64 #define SAL_LOADMODULE_GLOBAL     0x00100
  65
  66 typedef void* oslModule;
  67
  68 /** Generic Function pointer type that will be used as symbol address.
  69     @see osl_getFunctionSymbol.
  70     @see osl_getModuleURLFromFunctionAddress.
  71 */
  72 typedef void ( SAL_CALL *oslGenericFunction )( void );
  73
  74 /** Load a shared library or module.
  75     @param strModuleName denotes the name of the module to be loaded.
  76     @return NULL if the module could not be loaded, otherwise a handle to the module.
  77 */
  78 oslModule SAL_CALL osl_loadModule(rtl_uString *strModuleName, sal_Int32 nRtldMode);
  79
  80 /** Load a shared library or module.
  81     @param pModuleName denotes the name of the module to be loaded.
  82     @return NULL if the module could not be loaded, otherwise a handle to the module.
  83 */
  84 oslModule SAL_CALL osl_loadModuleAscii(const sal_Char *pModuleName, sal_Int32 nRtldMode);
  85
  86 /** Load a module located relative to some other module.
  87
  88     @param baseModule
  89     must point to a function that is part of the code of some loaded module;
  90     must not be NULL.
  91
  92     @param relativePath
  93     a relative URL; must not be NULL.
  94
  95     @param mode
  96     the SAL_LOADMODULE_xxx flags.
  97
  98     @return
  99     a non-NULL handle to the loaded module, or NULL if an error occurred.
 100
 101     @since UDK 3.2.8
 102 */
 103 oslModule SAL_CALL osl_loadModuleRelative(
 104     oslGenericFunction baseModule, rtl_uString * relativePath, sal_Int32 mode);
 105
 106 /** Retrieve the handle of an already loaded module.
 107
 108     This function can be used to search for a function symbol in the process address space.
 109     Do not use the returned handle as an argument to osl_unloadModule. On Unix platforms,
 110     pModuleName gets ignored and the special handle RTLD_DEFAULT is returned.
 111
 112     @param pModuleName
 113     [in] denotes the name of the module to search for. Ignored on Unix
 114
 115     @param pResult
 116     [out] a pointer to a oslModule that is updated with the requested module handle
 117     on success.
 118
 119     @return
 120     sal_True if the module handle could be retrieved and has been copied to *pResult.
 121     sal_False if the module has not been loaded yet.
 122
 123     @see osl_getFunctionSymbol
 124     @see osl_getAsciiFunctionSymbol
 125 */
 126 sal_Bool SAL_CALL osl_getModuleHandle(rtl_uString *pModuleName, oslModule *pResult);
 127
 128 /** Release the module
 129 */
 130 void SAL_CALL osl_unloadModule(oslModule Module);
 131
 132 /** lookup the specified symbol name.
 133     @return address of the symbol or NULL if lookup failed.
 134 */
 135 void* SAL_CALL osl_getSymbol( oslModule Module, rtl_uString *strSymbolName);
 136
 137 /** Lookup the specified function symbol name.
 138
 139     osl_getFunctionSymbol is an alternative function for osl_getSymbol.
 140     Use Function pointer as symbol address to conceal type conversion.
 141
 142     @param Module
 143     [in] the handle of the Module.
 144
 145     @param ustrFunctionSymbolName
 146     [in] Name of the function that will be looked up.
 147
 148     @return
 149     <dl>
 150     <dt>Function address.</dt>
 151     <dd>on success</dd>
 152     <dt>NULL</dt>
 153     <dd>lookup failed or the parameter are invalid.</dd>
 154     </dl>
 155
 156     @see osl_getSymbol
 157     @see osl_getAsciiFunctionSymbol
 158 */
 159 oslGenericFunction SAL_CALL osl_getFunctionSymbol( oslModule Module, rtl_uString *ustrFunctionSymbolName );
 160
 161 /** Lookup the specified function symbol name.
 162
 163     osl_getAsciiFunctionSymbol is an alternative function for osl_getFunctionSymbol.
 164     It expects the C-style function name string to contain ascii characters only.
 165
 166     @param Module
 167     [in] a module handle as returned by osl_loadModule or osl_getModuleHandle
 168
 169     @param pFunctionSymbolName
 170     [in] Name of the function that will be looked up.
 171
 172     @return
 173     <dl>
 174     <dt>Function address.</dt>
 175     <dd>on success</dd>
 176     <dt>NULL</dt>
 177     <dd>lookup failed or the parameter are invalid.</dd>
 178     </dl>
 179
 180     @see osl_getModuleHandle
 181     @see osl_getFunctionSymbol
 182 */
 183 oslGenericFunction SAL_CALL osl_getAsciiFunctionSymbol(oslModule Module, const sal_Char *pSymbol);
 184
 185
 186 /** Lookup URL of module which is mapped at the specified address.
 187     @param pv specifies an address in the process memory space.
 188     @param pustrURL receives the URL of the module that is mapped at pv.
 189     @return sal_True on success, sal_False if no module can be found at the specified address.
 190 */
 191 sal_Bool SAL_CALL osl_getModuleURLFromAddress( void *pv, rtl_uString **pustrURL );
 192
 193 /** Lookup URL of module which is mapped at the specified function address.
 194
 195     osl_getModuleURLFromFunctionAddress is an alternative function for osl_getModuleURLFromAddress.
 196     Use Function pointer as symbol address to conceal type conversion.
 197
 198     @param pf
 199     [in] function address in oslGenericFunction format.
 200
 201     @param pustrFunctionURL
 202     [out] receives the URL of the module that is mapped at pf.
 203
 204     @return
 205     <dl>
 206     <dt>sal_True</dt>
 207     <dd>on success</dd>
 208     <dt>sal_False</dt>
 209     <dd>no module can be found at the specified function address or parameter is somewhat invalid.</dd>
 210     </dl>
 211
 212     @see osl_getModuleURLFromAddress
 213 */
 214 sal_Bool SAL_CALL osl_getModuleURLFromFunctionAddress( oslGenericFunction pf, rtl_uString **pustrFunctionURL );
 215
 216 #ifdef __cplusplus
 217 }
 218 #endif
 219
 220 #endif  /* _OSL_MODULE_H_  */