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 @param nRtldMode mode defined by logically OR-ing of SAL_LOADMODULE_* flags. 70 @return NULL if the module could not be loaded, otherwise a handle to the module. 71 */ 72 oslModule SAL_CALL osl_loadModule(rtl_uString *strModuleName, sal_Int32 nRtldMode); 73 /** Load a shared library or module. 74 @param pModuleName denotes the name of the module to be loaded. 75 @param nRtldMode mode defined by logically OR-ing of SAL_LOADMODULE_* flags. 76 @return NULL if the module could not be loaded, otherwise a handle to the module. 77 */ 78 oslModule SAL_CALL osl_loadAsciiModule( const sal_Char* pModuleName, sal_Int32 nRtldMode); 79 80 /** Load a module located relative to some other module. 81 82 @param baseModule 83 must point to a function that is part of the code of some loaded module; 84 must not be NULL. 85 86 @param relativePath 87 a relative URL; must not be NULL. 88 89 @param nRtldMode mode defined by logically OR-ing of SAL_LOADMODULE_* flags. 90 91 @return 92 a non-NULL handle to the loaded module, or NULL if an error occurred. 93 94 @since UDK 3.2.8 95 */ 96 oslModule SAL_CALL osl_loadModuleRelative( 97 oslGenericFunction baseModule, rtl_uString* relativePath, sal_Int32 nRtldMode); 98 /** Load a module located relative to some other module. 99 100 @param baseModule 101 must point to a function that is part of the code of some loaded module; 102 must not be NULL. 103 104 @param relativePath 105 a relative URL; must not be NULL. 106 107 @param nRtldMode mode defined by logically OR-ing of SAL_LOADMODULE_* flags. 108 109 @return 110 a non-NULL handle to the loaded module, or NULL if an error occurred. 111 */ 112 oslModule SAL_CALL osl_loadAsciiModuleRelative( 113 oslGenericFunction baseModule, const sal_Char* relativePath, sal_Int32 nRtldMode); 114 115 /** Retrieve the handle of an already loaded module. 116 117 This function can be used to search for a function symbol in the process address space. 118 Do not use the returned handle as an argument to osl_unloadModule. On Unix platforms, 119 pModuleName gets ignored and the special handle RTLD_DEFAULT is returned. 120 121 @param pModuleName 122 [in] denotes the name of the module to search for. Ignored on Unix 123 124 @param pResult 125 [out] a pointer to a oslModule that is updated with the requested module handle 126 on success. 127 128 @return 129 sal_True if the module handle could be retrieved and has been copied to *pResult. 130 sal_False if the module has not been loaded yet. 131 132 @see osl_getFunctionSymbol 133 @see osl_getAsciiFunctionSymbol 134 */ 135 sal_Bool SAL_CALL osl_getModuleHandle(rtl_uString *pModuleName, oslModule *pResult); 136 137 /** Release the module 138 */ 139 void SAL_CALL osl_unloadModule(oslModule Module); 140 141 /** lookup the specified symbol name. 142 @return address of the symbol or NULL if lookup failed. 143 */ 144 void* SAL_CALL osl_getSymbol( oslModule Module, rtl_uString *strSymbolName); 145 146 /** Lookup the specified function symbol name. 147 148 osl_getFunctionSymbol is an alternative function for osl_getSymbol. 149 Use Function pointer as symbol address to conceal type conversion. 150 151 @param Module 152 [in] the handle of the Module. 153 154 @param ustrFunctionSymbolName 155 [in] Name of the function that will be looked up. 156 157 @return 158 <dl> 159 <dt>Function address.</dt> 160 <dd>on success</dd> 161 <dt>NULL</dt> 162 <dd>lookup failed or the parameter are invalid.</dd> 163 </dl> 164 165 @see osl_getSymbol 166 @see osl_getAsciiFunctionSymbol 167 */ 168 oslGenericFunction SAL_CALL osl_getFunctionSymbol( oslModule Module, rtl_uString *ustrFunctionSymbolName ); 169 170 /** Lookup the specified function symbol name. 171 172 osl_getAsciiFunctionSymbol is an alternative function for osl_getFunctionSymbol. 173 It expects the C-style function name string to contain ascii characters only. 174 175 @param Module 176 [in] a module handle as returned by osl_loadModule or osl_getModuleHandle 177 178 @param pSymbolName 179 [in] Name of the function that will be looked up. 180 181 @return 182 <dl> 183 <dt>Function address.</dt> 184 <dd>on success</dd> 185 <dt>NULL</dt> 186 <dd>lookup failed or the parameter are invalid.</dd> 187 </dl> 188 189 @see osl_getModuleHandle 190 @see osl_getFunctionSymbol 191 */ 192 oslGenericFunction SAL_CALL osl_getAsciiFunctionSymbol(oslModule Module, const sal_Char *pSymbolName); 193 194 195 /** Lookup URL of module which is mapped at the specified address. 196 @param pv specifies an address in the process memory space. 197 @param pustrURL receives the URL of the module that is mapped at pv. 198 @return sal_True on success, sal_False if no module can be found at the specified address. 199 */ 200 sal_Bool SAL_CALL osl_getModuleURLFromAddress( void *pv, rtl_uString **pustrURL ); 201 202 /** Lookup URL of module which is mapped at the specified function address. 203 204 osl_getModuleURLFromFunctionAddress is an alternative function for osl_getModuleURLFromAddress. 205 Use Function pointer as symbol address to conceal type conversion. 206 207 @param pf 208 [in] function address in oslGenericFunction format. 209 210 @param pustrFunctionURL 211 [out] receives the URL of the module that is mapped at pf. 212 213 @return 214 <dl> 215 <dt>sal_True</dt> 216 <dd>on success</dd> 217 <dt>sal_False</dt> 218 <dd>no module can be found at the specified function address or parameter is somewhat invalid.</dd> 219 </dl> 220 221 @see osl_getModuleURLFromAddress 222 */ 223 sal_Bool SAL_CALL osl_getModuleURLFromFunctionAddress( oslGenericFunction pf, rtl_uString **pustrFunctionURL ); 224 225 #ifdef __cplusplus 226 } 227 #endif 228 229 #endif /* _OSL_MODULE_H_ */ 230