include/osl/module.h

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 #ifndef INCLUDED_OSL_MODULE_H
  21 #define INCLUDED_OSL_MODULE_H
  22
  23 #include "sal/config.h"
  24
  25 #include "rtl/ustring.h"
  26 #include "sal/saldllapi.h"
  27
  28 #ifdef __cplusplus
  29 extern "C" {
  30 #endif
  31
  32 #ifdef SAL_DLLPREFIX
  33 #define SAL_MODULENAME(name) SAL_DLLPREFIX name SAL_DLLEXTENSION
  34 #else
  35 #define SAL_MODULENAME(name) name SAL_DLLEXTENSION
  36 #endif
  37
  38 #if defined(_WIN32)
  39 #define SAL_MODULENAME_WITH_VERSION(name, version) name version SAL_DLLEXTENSION
  40
  41 #elif defined(SAL_UNX)
  42 #if defined(MACOSX)
  43 #define SAL_MODULENAME_WITH_VERSION(name, version) SAL_DLLPREFIX name ".dylib." version
  44 #else
  45 #define SAL_MODULENAME_WITH_VERSION(name, version) SAL_DLLPREFIX name SAL_DLLEXTENSION "." version
  46 #endif
  47
  48 #endif
  49
  50 #define SAL_LOADMODULE_DEFAULT    0x00000
  51 #define SAL_LOADMODULE_LAZY       0x00001
  52 #define SAL_LOADMODULE_NOW        0x00002
  53 #define SAL_LOADMODULE_GLOBAL     0x00100
  54
  55 typedef void* oslModule;
  56
  57 /** Generic Function pointer type that will be used as symbol address.
  58
  59     @see osl_getFunctionSymbol.
  60     @see osl_getModuleURLFromFunctionAddress.
  61 */
  62 typedef void ( SAL_CALL *oslGenericFunction )( void );
  63
  64 #ifndef DISABLE_DYNLOADING
  65
  66 /** Load a shared library or module.
  67
  68     @param[in] strModuleName denotes the name of the module to be loaded.
  69     @param[in] nRtldMode denotes the mode.
  70
  71     @returns NULL if the module could not be loaded, otherwise a handle to the module.
  72 */
  73 SAL_DLLPUBLIC oslModule SAL_CALL osl_loadModule(rtl_uString *strModuleName, sal_Int32 nRtldMode);
  74
  75 /** Load a shared library or module.
  76
  77     @param[in] pModuleName denotes the name of the module to be loaded.
  78     @param[in] nRtldMode denotes the mode.
  79
  80     @return NULL if the module could not be loaded, otherwise a handle to the module.
  81
  82     @since UDK 3.6
  83 */
  84 SAL_DLLPUBLIC 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[in] baseModule must point to a function that is part of the code of some loaded module;
  89                         must not be NULL.
  90     @param[in] relativePath a relative URL; must not be NULL.
  91     @param[in] mode the SAL_LOADMODULE_xxx flags.
  92
  93     @return a non-NULL handle to the loaded module, or NULL if an error occurred.
  94
  95     @since UDK 3.2.8
  96 */
  97 SAL_DLLPUBLIC oslModule SAL_CALL osl_loadModuleRelative(
  98     oslGenericFunction baseModule, rtl_uString * relativePath, sal_Int32 mode);
  99
 100 /** Load a module located relative to some other module.
 101
 102     @param[in] baseModule must point to a function that is part of the code of some loaded module;
 103                         must not be NULL.
 104     @param[in] relativePath a relative URL containing only ASCII (0x01--7F) characters;
 105                         must not be NULL.
 106     @param[in] mode     the SAL_LOADMODULE_xxx flags.
 107
 108     @return a non-NULL handle to the loaded module, or NULL if an error occurred.
 109
 110     @since LibreOffice 3.5
 111 */
 112 SAL_DLLPUBLIC oslModule SAL_CALL osl_loadModuleRelativeAscii(
 113     oslGenericFunction baseModule, char const * relativePath, sal_Int32 mode);
 114     /* This function is guaranteed not to call into
 115        FullTextEncodingDataSingleton in sal/textenc/textenc.cxx, so can be used
 116        in its implementation without running into circles. */
 117
 118 #endif
 119
 120 /** Retrieve the handle of an already loaded module.
 121
 122     This function can be used to search for a function symbol in the process address space.
 123     Do not use the returned handle as an argument to osl_unloadModule. On Unix platforms,
 124     pModuleName gets ignored and the special handle RTLD_DEFAULT is returned.
 125
 126     @param[in] pModuleName  denotes the name of the module to search for.
 127                             @attention Ignored on Unix.
 128     @param[out] pResult     a pointer to a oslModule that is updated with the
 129                             requested module handle on success.
 130
 131     @retval sal_True if the module handle could be retrieved and has been copied to *pResult.
 132     @retval sal_False if the module has not been loaded yet.
 133
 134     @see osl_getFunctionSymbol
 135     @see osl_getAsciiFunctionSymbol
 136 */
 137 SAL_DLLPUBLIC sal_Bool SAL_CALL osl_getModuleHandle(rtl_uString *pModuleName, oslModule *pResult);
 138
 139 #ifndef DISABLE_DYNLOADING
 140
 141 /** Release the module
 142 */
 143 SAL_DLLPUBLIC void SAL_CALL osl_unloadModule(oslModule Module);
 144
 145 #endif
 146
 147 /** lookup the specified symbol name.
 148
 149     @param[in] Module the handle of the Module.
 150     @param[in] strSymbolName Name of the function that will be looked up.
 151
 152     @return address of the symbol or NULL if lookup failed.
 153
 154     @see osl_getFunctionSymbol
 155 */
 156 SAL_DLLPUBLIC void* SAL_CALL osl_getSymbol( oslModule Module, rtl_uString *strSymbolName);
 157
 158 /** Lookup the specified function symbol name.
 159
 160     osl_getFunctionSymbol is an alternative function for osl_getSymbol.
 161     Use Function pointer as symbol address to conceal type conversion.
 162
 163     @param[in] Module the handle of the Module.
 164     @param[in] ustrFunctionSymbolName Unicode name of the function that will be looked up.
 165
 166     @retval function-address on success
 167     @retval NULL lookup failed or the parameter are invalid
 168
 169     @see osl_getSymbol
 170     @see osl_getAsciiFunctionSymbol
 171 */
 172 SAL_DLLPUBLIC oslGenericFunction SAL_CALL osl_getFunctionSymbol(
 173         oslModule Module, rtl_uString *ustrFunctionSymbolName );
 174
 175 /** Lookup the specified function symbol name.
 176
 177     osl_getAsciiFunctionSymbol is an alternative function for osl_getFunctionSymbol.
 178     It expects the C-style function name string to contain ascii characters only.
 179
 180     @param Module
 181     [in] a module handle as returned by osl_loadModule or osl_getModuleHandle
 182
 183     @param pSymbol
 184     [in] Name of the function that will be looked up.
 185
 186     @retval function-address on success
 187     @retval NULL lookup failed or the parameter are invalid
 188
 189     @see osl_getModuleHandle
 190     @see osl_getFunctionSymbol
 191 */
 192 SAL_DLLPUBLIC oslGenericFunction SAL_CALL osl_getAsciiFunctionSymbol(
 193         oslModule Module, const sal_Char *pSymbol );
 194
 195 /** Lookup URL of module which is mapped at the specified address.
 196
 197     @param[in] pv       specifies an address in the process memory space.
 198     @param[out] pustrURL receives the URL of the module that is mapped at pv.
 199     @return sal_True on success, sal_False if no module can be found at the specified address.
 200 */
 201 SAL_DLLPUBLIC sal_Bool SAL_CALL osl_getModuleURLFromAddress(
 202         void *pv, rtl_uString **pustrURL );
 203
 204 /** Lookup URL of module which is mapped at the specified function address.
 205
 206     osl_getModuleURLFromFunctionAddress is an alternative function for osl_getModuleURLFromAddress.
 207     Use Function pointer as symbol address to conceal type conversion.
 208
 209     @param[in] pf       function address in oslGenericFunction format.
 210     @param[out] pustrFunctionURL receives the URL of the module that is mapped at pf.
 211
 212     @retval sal_True on success
 213     @retval sal_False no module can be found at the specified function address or parameter is somewhat invalid
 214
 215     @see osl_getModuleURLFromAddress
 216 */
 217 SAL_DLLPUBLIC sal_Bool SAL_CALL osl_getModuleURLFromFunctionAddress(
 218         oslGenericFunction pf, rtl_uString **pustrFunctionURL );
 219
 220 #ifdef __cplusplus
 221 }
 222 #endif
 223
 224 #endif // INCLUDED_OSL_MODULE_H
 225
 226 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */