Line data Source code
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 : #ifndef INCLUDED_UNO_ENVIRONMENT_H
20 : #define INCLUDED_UNO_ENVIRONMENT_H
21 :
22 : #include <cppu/cppudllapi.h>
23 : #include <rtl/ustring.h>
24 :
25 : #include <stdarg.h>
26 :
27 : #ifdef __cplusplus
28 : extern "C"
29 : {
30 : #endif
31 :
32 : struct _uno_ExtEnvironment;
33 : struct _typelib_InterfaceTypeDescription;
34 :
35 : #if defined( SAL_W32)
36 : #pragma pack(push, 8)
37 : #endif
38 :
39 : /** The binary specification of an UNO environment.
40 : */
41 : typedef struct _uno_Environment
42 : {
43 : /** reserved for future use (0 if not used)
44 : */
45 : void * pReserved;
46 :
47 : /** type name of environment
48 : */
49 : rtl_uString * pTypeName;
50 :
51 : /** free context pointer to be used for specific classes of environments (e.g., a jvm pointer)
52 : */
53 : void * pContext;
54 :
55 : /** pointer to extended environment (interface registration functionality), if supported
56 : */
57 : struct _uno_ExtEnvironment * pExtEnv;
58 :
59 : /** Acquires this environment.
60 :
61 : @param pEnv this environment
62 : */
63 : void (SAL_CALL * acquire)( struct _uno_Environment * pEnv );
64 :
65 : /** Releases this environment; last release of environment will revoke the environment from
66 : runtime.
67 :
68 : @param pEnv this environment
69 : */
70 : void (SAL_CALL * release)( struct _uno_Environment * pEnv );
71 :
72 : /** Acquires this environment weakly. You can only harden a weakly held environment if it
73 : is still acquired hard (acquire()).
74 :
75 : @param pEnv this environment
76 : */
77 : void (SAL_CALL * acquireWeak)( struct _uno_Environment * pEnv );
78 :
79 : /** Releases this environment weakly in correspondence to acquireWeak().
80 :
81 : @param pEnv this environment
82 : */
83 : void (SAL_CALL * releaseWeak)( struct _uno_Environment * pEnv );
84 :
85 : /** Makes hard reference out of weak referenced environment. You can only harden a weakly
86 : held environment if it is still acquired hard (acquire()).
87 :
88 : @param ppHardEnv inout hard referenced environment (has to be released via release())
89 : @param pEnv environment (may be weak referenced)
90 : */
91 : void (SAL_CALL * harden)(
92 : struct _uno_Environment ** ppHardEnv,
93 : struct _uno_Environment * pEnv );
94 :
95 : /** Call this function to EXPLICITLY dispose this environment (e.g., release all
96 : interfaces). You may want to call this function before shutting down due to a runtime error.
97 :
98 : @param pEnv this environment
99 : */
100 : void (SAL_CALL * dispose)( struct _uno_Environment * pEnv );
101 :
102 : /* ===== the following part will be late initialized by a matching bridge ===== *
103 : * ===== and is NOT for public use. ===== */
104 :
105 : /** CALLBACK function pointer: Disposing callback function pointer that can be set to get
106 : signalled before the environment is destroyed.
107 :
108 : @param pEnv environment that is being disposed
109 : */
110 : void (SAL_CALL * environmentDisposing)( struct _uno_Environment * pEnv );
111 : } uno_Environment;
112 :
113 : /** Generic function pointer declaration to free a proxy object if it is not needed by the
114 : environment anymore.
115 : Any proxy object must register itself on first acquire() call and revoke itself on last
116 : release() call. This can happen several times because the environment caches proxy objects
117 : until the environment explicitly frees the proxy object calling this function.
118 :
119 : @param pEnv environment
120 : @param pProxy proxy pointer
121 : */
122 : typedef void (SAL_CALL * uno_freeProxyFunc)( struct _uno_ExtEnvironment * pEnv, void * pProxy );
123 :
124 : /** Generic function pointer declaration to allocate memory. Used with getRegisteredInterfaces().
125 :
126 : @param nBytes amount of memory in bytes
127 : @return pointer to allocated memory
128 : */
129 : typedef void * (SAL_CALL * uno_memAlloc)( sal_Size nBytes );
130 :
131 : /** The binary specification of an UNO environment supporting interface registration.
132 : */
133 3 : typedef struct _uno_ExtEnvironment
134 : {
135 : /** inherits all members of an uno_Environment
136 : */
137 : uno_Environment aBase;
138 :
139 : /** Registers an interface of this environment.
140 :
141 : @param pEnv this environment
142 : @param ppInterface inout parameter of interface to be registered
143 : @param pOId object id of interface
144 : @param pTypeDescr type description of interface
145 : */
146 : void (SAL_CALL * registerInterface)(
147 : struct _uno_ExtEnvironment * pEnv,
148 : void ** ppInterface,
149 : rtl_uString * pOId,
150 : struct _typelib_InterfaceTypeDescription * pTypeDescr );
151 :
152 : /** Registers a proxy interface of this environment that can be reanimated and is freed
153 : explicitly by this environment.
154 :
155 : @param pEnv this environment
156 : @param ppInterface inout parameter of interface to be registered
157 : @param freeProxy function to free proxy object
158 : @param pOId object id of interface
159 : @param pTypeDescr type description of interface
160 : */
161 : void (SAL_CALL * registerProxyInterface)(
162 : struct _uno_ExtEnvironment * pEnv,
163 : void ** ppProxy,
164 : uno_freeProxyFunc freeProxy,
165 : rtl_uString * pOId,
166 : struct _typelib_InterfaceTypeDescription * pTypeDescr );
167 :
168 : /** Revokes an interface from this environment. You have to revoke any interface that has
169 : been registered via this method.
170 :
171 : @param pEnv this environment
172 : @param pInterface interface to be revoked
173 : */
174 : void (SAL_CALL * revokeInterface)(
175 : struct _uno_ExtEnvironment * pEnv,
176 : void * pInterface );
177 :
178 : /** Provides the object id of a given interface.
179 :
180 : @param ppOut inout oid
181 : @param pInterface interface of object
182 : */
183 : void (SAL_CALL * getObjectIdentifier)(
184 : struct _uno_ExtEnvironment * pEnv,
185 : rtl_uString ** ppOId,
186 : void * pInterface );
187 :
188 : /** Retrieves an interface identified by its object id and type from this environment.
189 : Interfaces are retrieved in the same order as they are registered.
190 :
191 : @param pEnv this environment
192 : @param ppInterface inout parameter for the registered interface; (0) if none was found
193 : @param pOId object id of interface to be retrieved
194 : @param pTypeDescr type description of interface to be retrieved
195 : */
196 : void (SAL_CALL * getRegisteredInterface)(
197 : struct _uno_ExtEnvironment * pEnv,
198 : void ** ppInterface,
199 : rtl_uString * pOId,
200 : struct _typelib_InterfaceTypeDescription * pTypeDescr );
201 :
202 : /** Returns all currently registered interfaces of this environment. The memory block
203 : allocated might be slightly larger than (*pnLen * sizeof(void *)).
204 :
205 : @param pEnv this environment
206 : @param pppInterfaces out param; pointer to array of interface pointers
207 : @param pnLen out param; length of array
208 : @param memAlloc function for allocating memory that is passed back
209 : */
210 : void (SAL_CALL * getRegisteredInterfaces)(
211 : struct _uno_ExtEnvironment * pEnv,
212 : void *** pppInterfaces,
213 : sal_Int32 * pnLen,
214 : uno_memAlloc memAlloc );
215 :
216 : /* ===== the following part will be late initialized by a matching bridge ===== */
217 :
218 : /** Computes an object id of the given interface; is called by the environment implementation.
219 :
220 : @param pEnv corresponding environment
221 : @param ppOId out param: computed id
222 : @param pInterface an interface
223 : */
224 : void (SAL_CALL * computeObjectIdentifier)(
225 : struct _uno_ExtEnvironment * pEnv,
226 : rtl_uString ** ppOId, void * pInterface );
227 :
228 : /** Function to acquire an interface.
229 :
230 : @param pEnv corresponding environment
231 : @param pInterface an interface
232 : */
233 : void (SAL_CALL * acquireInterface)(
234 : struct _uno_ExtEnvironment * pEnv,
235 : void * pInterface );
236 :
237 : /** Function to release an interface.
238 :
239 : @param pEnv corresponding environment
240 : @param pInterface an interface
241 : */
242 : void (SAL_CALL * releaseInterface)(
243 : struct _uno_ExtEnvironment * pEnv,
244 : void * pInterface );
245 :
246 : } uno_ExtEnvironment;
247 :
248 : #if defined( SAL_W32)
249 : #pragma pack(pop)
250 : #endif
251 :
252 : /** Function exported by some bridge library providing acquireInterface(), releaseInterface();
253 : may set a disposing callback.
254 :
255 : @param pEnv environment to be initialized
256 : */
257 : typedef void (SAL_CALL * uno_initEnvironmentFunc)( uno_Environment * pEnv );
258 : #define UNO_INIT_ENVIRONMENT "uno_initEnvironment"
259 :
260 : #ifdef DISABLE_DYNLOADING
261 : /* We link statically and have just the C++ environment */
262 : void SAL_CALL CPPU_ENV_uno_initEnvironment( uno_Environment * Env )
263 : SAL_THROW_EXTERN_C();
264 :
265 : /* We might also have the Java environment */
266 : void SAL_CALL java_uno_initEnvironment( uno_Environment * Env )
267 : SAL_THROW_EXTERN_C();
268 : #endif
269 :
270 : /** Gets a specific environment. If the specified environment does not exist, then a default one
271 : is created and registered. The environment revokes itself on last release() call.
272 :
273 : @param ppEnv inout parameter of environment; given environment will be released
274 : @param pEnvDcp descriptor of environment
275 : @param pContext some context pointer (e.g., to distinguish java vm; set 0 if not needed)
276 : */
277 : CPPU_DLLPUBLIC void SAL_CALL uno_getEnvironment(
278 : uno_Environment ** ppEnv, rtl_uString * pEnvDcp, void * pContext )
279 : SAL_THROW_EXTERN_C();
280 :
281 : /** Gets all specified environments. Caller has to release returned environments and free allocated
282 : memory.
283 :
284 : @param pppEnvs out param; pointer to array of environments
285 : @param pnLen out param; length of array
286 : @param memAlloc function for allocating memory that is passed back
287 : @param pEnvDcp descriptor of environments; 0 defaults to all
288 : */
289 : CPPU_DLLPUBLIC void SAL_CALL uno_getRegisteredEnvironments(
290 : uno_Environment *** pppEnvs, sal_Int32 * pnLen, uno_memAlloc memAlloc,
291 : rtl_uString * pEnvDcp )
292 : SAL_THROW_EXTERN_C();
293 :
294 : /** Creates an environment. The new environment is anonymous (NOT publicly registered/ accessible).
295 :
296 : @param ppEnv out parameter of environment; given environment will be released
297 : @param pEnvDcp descriptor of environment
298 : @param pContext context pointer (e.g., to distinguish java vm); set 0 if not needed
299 : */
300 : CPPU_DLLPUBLIC void SAL_CALL uno_createEnvironment(
301 : uno_Environment ** ppEnv, rtl_uString * pEnvDcp, void * pContext )
302 : SAL_THROW_EXTERN_C();
303 :
304 : /** Dumps out environment information, i.e. registered interfaces.
305 :
306 : @param stream output stream (FILE *)
307 : @param pEnv environment to be dumped
308 : @param pFilter if not null, filters output
309 : */
310 : CPPU_DLLPUBLIC void SAL_CALL uno_dumpEnvironment(
311 : void * stream, uno_Environment * pEnv, const sal_Char * pFilter )
312 : SAL_THROW_EXTERN_C();
313 : /** Dumps out environment information, i.e. registered interfaces.
314 :
315 : @param stream output stream (FILE *)
316 : @param pEnvDcp descritpro of environment to be dumped
317 : @param pFilter if not null, filters output
318 : */
319 : CPPU_DLLPUBLIC void SAL_CALL uno_dumpEnvironmentByName(
320 : void * stream, rtl_uString * pEnvDcp, const sal_Char * pFilter )
321 : SAL_THROW_EXTERN_C();
322 :
323 :
324 :
325 : /** Returns the current Environment.
326 : In case no Environment has explicitly been entered, a purpose free
327 : default environment gets returned (e.g. the "uno" or "gcc3" Environment).
328 :
329 : @param ppEnv inout parameter; a given environment will be released
330 : @param pTypeName the optional type of the environment, falls back to "uno"
331 : @since UDK 3.2.7
332 : */
333 : CPPU_DLLPUBLIC void SAL_CALL uno_getCurrentEnvironment(uno_Environment ** ppEnv, rtl_uString * pTypeName)
334 : SAL_THROW_EXTERN_C();
335 :
336 : /** Typedef for variable argument function.
337 : */
338 : typedef void SAL_CALL uno_EnvCallee(va_list * pParam);
339 :
340 : /** Invoke the passed function in the given environment.
341 :
342 : @param pEnv the target environment
343 : @param pCallee the function to call
344 : @param pParam the parameter pointer passed to the function
345 : @since UDK 3.2.7
346 : */
347 : CPPU_DLLPUBLIC void SAL_CALL uno_Environment_invoke_v(uno_Environment * pEnv, uno_EnvCallee * pCallee, va_list * pParam)
348 : SAL_THROW_EXTERN_C();
349 :
350 : /** Invoke the passed function in the given environment.
351 :
352 : @param pEnv the target environment
353 : @param pCallee the function to call
354 : @param ... the parameters passed to the function
355 : @since UDK 3.2.7
356 : */
357 : CPPU_DLLPUBLIC void SAL_CALL uno_Environment_invoke (uno_Environment * pEnv, uno_EnvCallee * pCallee, ...)
358 : SAL_THROW_EXTERN_C();
359 :
360 : /** Enter an environment explicitly.
361 :
362 : @param pEnv the environment to enter; NULL leaves all environments
363 : @since UDK 3.2.7
364 : */
365 : CPPU_DLLPUBLIC void SAL_CALL uno_Environment_enter(uno_Environment * pEnv)
366 : SAL_THROW_EXTERN_C();
367 :
368 : /** Check if a particular environment is currently valid, so
369 : that objects of that environment might be called.
370 :
371 : @param pEnv the environment
372 : @param pReason the reason, if it is not valid
373 : @return 1 == valid, 0 == invalid
374 : @since UDK 3.2.7
375 : */
376 : CPPU_DLLPUBLIC int SAL_CALL uno_Environment_isValid(uno_Environment * pEnv, rtl_uString ** pReason)
377 : SAL_THROW_EXTERN_C();
378 :
379 : #ifdef __cplusplus
380 : }
381 : #endif
382 :
383 : #endif
384 :
385 : /* vim:set shiftwidth=4 softtabstop=4 expandtab: */
|
