1 /************************************************************** 2 * 3 * Licensed to the Apache Software Foundation (ASF) under one 4 * or more contributor license agreements. See the NOTICE file 5 * distributed with this work for additional information 6 * regarding copyright ownership. The ASF licenses this file 7 * to you under the Apache License, Version 2.0 (the 8 * "License"); you may not use this file except in compliance 9 * with the License. You may obtain a copy of the License at 10 * 11 * http://www.apache.org/licenses/LICENSE-2.0 12 * 13 * Unless required by applicable law or agreed to in writing, 14 * software distributed under the License is distributed on an 15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 16 * KIND, either express or implied. See the License for the 17 * specific language governing permissions and limitations 18 * under the License. 19 * 20 *************************************************************/ 21 22 23 24 /** @HTML */ 25 26 #ifndef _OSL_MODULE_H_ 27 #define _OSL_MODULE_H_ 28 29 # include <rtl/ustring.h> 30 # include <rtl/tencinfo.h> 31 32 #ifdef __cplusplus 33 extern "C" { 34 #endif 35 36 #ifdef SAL_DLLPREFIX 37 #define SAL_MODULENAME(name) SAL_DLLPREFIX name SAL_DLLEXTENSION 38 #else 39 #define SAL_MODULENAME(name) name SAL_DLLEXTENSION 40 #endif 41 42 #if defined(SAL_W32) || defined(SAL_OS2) 43 #define SAL_MODULENAME_WITH_VERSION(name, version) name version SAL_DLLEXTENSION 44 45 #elif defined(SAL_UNX) 46 #if defined(MACOSX) 47 #define SAL_MODULENAME_WITH_VERSION(name, version) SAL_DLLPREFIX name ".dylib." version 48 #else 49 #define SAL_MODULENAME_WITH_VERSION(name, version) SAL_DLLPREFIX name SAL_DLLEXTENSION "." version 50 #endif 51 52 #endif 53 54 #define SAL_LOADMODULE_DEFAULT 0x00000 55 #define SAL_LOADMODULE_LAZY 0x00001 56 #define SAL_LOADMODULE_NOW 0x00002 57 #define SAL_LOADMODULE_GLOBAL 0x00100 58 59 typedef void* oslModule; 60 61 /** Generic Function pointer type that will be used as symbol address. 62 @see osl_getFunctionSymbol. 63 @see osl_getModuleURLFromFunctionAddress. 64 */ 65 typedef void ( SAL_CALL *oslGenericFunction )( void ); 66 67 /** Load a shared library or module. 68 @param strModuleName denotes the name of the module to be loaded. 69 @return NULL if the module could not be loaded, otherwise a handle to the module. 70 */ 71 oslModule SAL_CALL osl_loadModule(rtl_uString *strModuleName, sal_Int32 nRtldMode); 72 73 /** Load a module located relative to some other module. 74 75 @param baseModule 76 must point to a function that is part of the code of some loaded module; 77 must not be NULL. 78 79 @param relativePath 80 a relative URL; must not be NULL. 81 82 @param mode 83 the SAL_LOADMODULE_xxx flags. 84 85 @return 86 a non-NULL handle to the loaded module, or NULL if an error occurred. 87 88 @since UDK 3.2.8 89 */ 90 oslModule SAL_CALL osl_loadModuleRelative( 91 oslGenericFunction baseModule, rtl_uString * relativePath, sal_Int32 mode); 92 93 /** Retrieve the handle of an already loaded module. 94 95 This function can be used to search for a function symbol in the process address space. 96 Do not use the returned handle as an argument to osl_unloadModule. On Unix platforms, 97 pModuleName gets ignored and the special handle RTLD_DEFAULT is returned. 98 99 @param pModuleName 100 [in] denotes the name of the module to search for. Ignored on Unix 101 102 @param pResult 103 [out] a pointer to a oslModule that is updated with the requested module handle 104 on success. 105 106 @return 107 sal_True if the module handle could be retrieved and has been copied to *pResult. 108 sal_False if the module has not been loaded yet. 109 110 @see osl_getFunctionSymbol 111 @see osl_getAsciiFunctionSymbol 112 */ 113 sal_Bool SAL_CALL osl_getModuleHandle(rtl_uString *pModuleName, oslModule *pResult); 114 115 /** Release the module 116 */ 117 void SAL_CALL osl_unloadModule(oslModule Module); 118 119 /** lookup the specified symbol name. 120 @return address of the symbol or NULL if lookup failed. 121 */ 122 void* SAL_CALL osl_getSymbol( oslModule Module, rtl_uString *strSymbolName); 123 124 /** Lookup the specified function symbol name. 125 126 osl_getFunctionSymbol is an alternative function for osl_getSymbol. 127 Use Function pointer as symbol address to conceal type conversion. 128 129 @param Module 130 [in] the handle of the Module. 131 132 @param ustrFunctionSymbolName 133 [in] Name of the function that will be looked up. 134 135 @return 136 <dl> 137 <dt>Function address.</dt> 138 <dd>on success</dd> 139 <dt>NULL</dt> 140 <dd>lookup failed or the parameter are invalid.</dd> 141 </dl> 142 143 @see osl_getSymbol 144 @see osl_getAsciiFunctionSymbol 145 */ 146 oslGenericFunction SAL_CALL osl_getFunctionSymbol( oslModule Module, rtl_uString *ustrFunctionSymbolName ); 147 148 /** Lookup the specified function symbol name. 149 150 osl_getAsciiFunctionSymbol is an alternative function for osl_getFunctionSymbol. 151 It expects the C-style function name string to contain ascii characters only. 152 153 @param Module 154 [in] a module handle as returned by osl_loadModule or osl_getModuleHandle 155 156 @param pFunctionSymbolName 157 [in] Name of the function that will be looked up. 158 159 @return 160 <dl> 161 <dt>Function address.</dt> 162 <dd>on success</dd> 163 <dt>NULL</dt> 164 <dd>lookup failed or the parameter are invalid.</dd> 165 </dl> 166 167 @see osl_getModuleHandle 168 @see osl_getFunctionSymbol 169 */ 170 oslGenericFunction SAL_CALL osl_getAsciiFunctionSymbol(oslModule Module, const sal_Char *pSymbol); 171 172 173 /** Lookup URL of module which is mapped at the specified address. 174 @param pv specifies an address in the process memory space. 175 @param pustrURL receives the URL of the module that is mapped at pv. 176 @return sal_True on success, sal_False if no module can be found at the specified address. 177 */ 178 sal_Bool SAL_CALL osl_getModuleURLFromAddress( void *pv, rtl_uString **pustrURL ); 179 180 /** Lookup URL of module which is mapped at the specified function address. 181 182 osl_getModuleURLFromFunctionAddress is an alternative function for osl_getModuleURLFromAddress. 183 Use Function pointer as symbol address to conceal type conversion. 184 185 @param pf 186 [in] function address in oslGenericFunction format. 187 188 @param pustrFunctionURL 189 [out] receives the URL of the module that is mapped at pf. 190 191 @return 192 <dl> 193 <dt>sal_True</dt> 194 <dd>on success</dd> 195 <dt>sal_False</dt> 196 <dd>no module can be found at the specified function address or parameter is somewhat invalid.</dd> 197 </dl> 198 199 @see osl_getModuleURLFromAddress 200 */ 201 sal_Bool SAL_CALL osl_getModuleURLFromFunctionAddress( oslGenericFunction pf, rtl_uString **pustrFunctionURL ); 202 203 #ifdef __cplusplus 204 } 205 #endif 206 207 #endif /* _OSL_MODULE_H_ */ 208