Branch data 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 _UNO_ENVIRONMENT_H_
20 : : #define _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 : 18432 : 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 one kind of environment */
262 : : void SAL_CALL CPPU_ENV_uno_initEnvironment( uno_Environment * Env )
263 : : SAL_THROW_EXTERN_C();
264 : : #endif
265 : :
266 : : /** Gets a specific environment. If the specified environment does not exist, then a default one
267 : : is created and registered. The environment revokes itself on last release() call.
268 : :
269 : : @param ppEnv inout parameter of environment; given environment will be released
270 : : @param pEnvDcp descriptor of environment
271 : : @param pContext some context pointer (e.g., to distinguish java vm; set 0 if not needed)
272 : : */
273 : : CPPU_DLLPUBLIC void SAL_CALL uno_getEnvironment(
274 : : uno_Environment ** ppEnv, rtl_uString * pEnvDcp, void * pContext )
275 : : SAL_THROW_EXTERN_C();
276 : :
277 : : /** Gets all specified environments. Caller has to release returned environments and free allocated
278 : : memory.
279 : :
280 : : @param pppEnvs out param; pointer to array of environments
281 : : @param pnLen out param; length of array
282 : : @param memAlloc function for allocating memory that is passed back
283 : : @param pEnvDcp descriptor of environments; 0 defaults to all
284 : : */
285 : : CPPU_DLLPUBLIC void SAL_CALL uno_getRegisteredEnvironments(
286 : : uno_Environment *** pppEnvs, sal_Int32 * pnLen, uno_memAlloc memAlloc,
287 : : rtl_uString * pEnvDcp )
288 : : SAL_THROW_EXTERN_C();
289 : :
290 : : /** Creates an environment. The new environment is anonymous (NOT publicly registered/ accessible).
291 : :
292 : : @param ppEnv out parameter of environment; given environment will be released
293 : : @param pEnvDcp descriptor of environment
294 : : @param pContext context pointer (e.g., to distinguish java vm); set 0 if not needed
295 : : */
296 : : CPPU_DLLPUBLIC void SAL_CALL uno_createEnvironment(
297 : : uno_Environment ** ppEnv, rtl_uString * pEnvDcp, void * pContext )
298 : : SAL_THROW_EXTERN_C();
299 : :
300 : : /** Dumps out environment information, i.e. registered interfaces.
301 : :
302 : : @param stream output stream (FILE *)
303 : : @param pEnv environment to be dumped
304 : : @param pFilter if not null, filters output
305 : : */
306 : : CPPU_DLLPUBLIC void SAL_CALL uno_dumpEnvironment(
307 : : void * stream, uno_Environment * pEnv, const sal_Char * pFilter )
308 : : SAL_THROW_EXTERN_C();
309 : : /** Dumps out environment information, i.e. registered interfaces.
310 : :
311 : : @param stream output stream (FILE *)
312 : : @param pEnvDcp descritpro of environment to be dumped
313 : : @param pFilter if not null, filters output
314 : : */
315 : : CPPU_DLLPUBLIC void SAL_CALL uno_dumpEnvironmentByName(
316 : : void * stream, rtl_uString * pEnvDcp, const sal_Char * pFilter )
317 : : SAL_THROW_EXTERN_C();
318 : :
319 : :
320 : :
321 : : /** Returns the current Environment.
322 : : In case no Environment has explicitly been entered, a purpose free
323 : : default environment gets returned (e.g. the "uno" or "gcc3" Environment).
324 : :
325 : : @param ppEnv inout parameter; a given environment will be released
326 : : @param pTypeName the optional type of the environment, falls back to "uno"
327 : : @since UDK 3.2.7
328 : : */
329 : : CPPU_DLLPUBLIC void SAL_CALL uno_getCurrentEnvironment(uno_Environment ** ppEnv, rtl_uString * pTypeName)
330 : : SAL_THROW_EXTERN_C();
331 : :
332 : : /** Typedef for variable argument function.
333 : : */
334 : : typedef void SAL_CALL uno_EnvCallee(va_list * pParam);
335 : :
336 : : /** Invoke the passed function in the given environment.
337 : :
338 : : @param pEnv the target environment
339 : : @param pCallee the function to call
340 : : @param pParam the parameter pointer passed to the function
341 : : @since UDK 3.2.7
342 : : */
343 : : CPPU_DLLPUBLIC void SAL_CALL uno_Environment_invoke_v(uno_Environment * pEnv, uno_EnvCallee * pCallee, va_list * pParam)
344 : : SAL_THROW_EXTERN_C();
345 : :
346 : : /** Invoke the passed function in the given environment.
347 : :
348 : : @param pEnv the target environment
349 : : @param pCallee the function to call
350 : : @param ... the parameters passed to the function
351 : : @since UDK 3.2.7
352 : : */
353 : : CPPU_DLLPUBLIC void SAL_CALL uno_Environment_invoke (uno_Environment * pEnv, uno_EnvCallee * pCallee, ...)
354 : : SAL_THROW_EXTERN_C();
355 : :
356 : : /** Enter an environment explicitly.
357 : :
358 : : @param pEnv the environment to enter; NULL leaves all environments
359 : : @since UDK 3.2.7
360 : : */
361 : : CPPU_DLLPUBLIC void SAL_CALL uno_Environment_enter(uno_Environment * pEnv)
362 : : SAL_THROW_EXTERN_C();
363 : :
364 : : /** Check if a particular environment is currently valid, so
365 : : that objects of that environment might be called.
366 : :
367 : : @param pEnv the environment
368 : : @param pReason the reason, if it is not valid
369 : : @return 1 == valid, 0 == invalid
370 : : @since UDK 3.2.7
371 : : */
372 : : CPPU_DLLPUBLIC int SAL_CALL uno_Environment_isValid(uno_Environment * pEnv, rtl_uString ** pReason)
373 : : SAL_THROW_EXTERN_C();
374 : :
375 : : #ifdef __cplusplus
376 : : }
377 : : #endif
378 : :
379 : : #endif
380 : :
381 : : /* vim:set shiftwidth=4 softtabstop=4 expandtab: */
|
