xref: /trunk/main/sal/inc/osl/module.h (revision d92161c4)
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"
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