summaryrefslogtreecommitdiff
path: root/cppu/inc/uno/environment.h
blob: f959aa2571f437764cc1edb397262fb287aead48 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
/*************************************************************************
 *
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * Copyright 2000, 2010 Oracle and/or its affiliates.
 *
 * OpenOffice.org - a multi-platform office productivity suite
 *
 * This file is part of OpenOffice.org.
 *
 * OpenOffice.org is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License version 3
 * only, as published by the Free Software Foundation.
 *
 * OpenOffice.org is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License version 3 for more details
 * (a copy is included in the LICENSE file that accompanied this code).
 *
 * You should have received a copy of the GNU Lesser General Public License
 * version 3 along with OpenOffice.org.  If not, see
 * <http://www.openoffice.org/license.html>
 * for a copy of the LGPLv3 License.
 *
 ************************************************************************/
#ifndef _UNO_ENVIRONMENT_H_
#define _UNO_ENVIRONMENT_H_

#include <sal/types.h>
#include <rtl/ustring.h>

#include <stdarg.h>

#ifdef __cplusplus
extern "C"
{
#endif

struct _uno_ExtEnvironment;
struct _typelib_InterfaceTypeDescription;

#if defined( SAL_W32)
#pragma pack(push, 8)
#elif defined(SAL_OS2)
#pragma pack(push, 8)
#endif

/** The binary specification of an UNO environment.
*/
typedef struct _uno_Environment
{
    /** reserved for future use (0 if not used)
    */
    void *              pReserved;

    /** type name of environment
    */
    rtl_uString *       pTypeName;

    /** free context pointer to be used for specific classes of environments (e.g., a jvm pointer)
    */
    void *              pContext;

    /** pointer to extended environment (interface registration functionality), if supported
    */
    struct _uno_ExtEnvironment * pExtEnv;

    /** Acquires this environment.

        @param pEnv this environment
    */
    void (SAL_CALL * acquire)( struct _uno_Environment * pEnv );

    /** Releases this environment; last release of environment will revoke the environment from
        runtime.

        @param pEnv this environment
    */
    void (SAL_CALL * release)( struct _uno_Environment * pEnv );

    /** Acquires this environment weakly.  You can only harden a weakly held environment if it
        is still acquired hard (acquire()).

        @param pEnv this environment
    */
    void (SAL_CALL * acquireWeak)( struct _uno_Environment * pEnv );

    /** Releases this environment weakly in correspondence to acquireWeak().

        @param pEnv this environment
    */
    void (SAL_CALL * releaseWeak)( struct _uno_Environment * pEnv );

    /** Makes hard reference out of weak referenced environment. You can only harden a weakly
        held environment if it is still acquired hard (acquire()).

        @param ppHardEnv inout hard referenced environment (has to be released via release())
        @param pEnv environment (may be weak referenced)
    */
    void (SAL_CALL * harden)(
        struct _uno_Environment ** ppHardEnv,
        struct _uno_Environment * pEnv );

    /** Call this function to EXPLICITLY dispose this environment (e.g., release all
        interfaces). You may want to call this function before shutting down due to a runtime error.

        @param pEnv this environment
    */
    void (SAL_CALL * dispose)( struct _uno_Environment * pEnv );

    /* ===== the following part will be late initialized by a matching bridge ===== *
     * ===== and is NOT for public use.                                       ===== */

    /** CALLBACK function pointer: Disposing callback function pointer that can be set to get
                                   signalled before the environment is destroyed.

        @param pEnv environment that is being disposed
    */
    void (SAL_CALL * environmentDisposing)( struct _uno_Environment * pEnv );
} uno_Environment;

/** Generic function pointer declaration to free a proxy object if it is not needed by the
    environment anymore.
    Any proxy object must register itself on first acquire() call and revoke itself on last
    release() call. This can happen several times because the environment caches proxy objects
    until the environment explicitly frees the proxy object calling this function.

    @param pEnv environment
    @param pProxy proxy pointer
*/
typedef void (SAL_CALL * uno_freeProxyFunc)( struct _uno_ExtEnvironment * pEnv, void * pProxy );

/** Generic function pointer declaration to allocate memory. Used with getRegisteredInterfaces().

    @param nBytes amount of memory in bytes
    @return pointer to allocated memory
*/
typedef void * (SAL_CALL * uno_memAlloc)( sal_Size nBytes );

/** The binary specification of an UNO environment supporting interface registration.
*/
typedef struct _uno_ExtEnvironment
{
    /** inherits all members of an uno_Environment
    */
    uno_Environment aBase;

    /** Registers an interface of this environment.

        @param pEnv         this environment
        @param ppInterface  inout parameter of interface to be registered
        @param pOId         object id of interface
        @param pTypeDescr   type description of interface
    */
    void (SAL_CALL * registerInterface)(
        struct _uno_ExtEnvironment * pEnv,
        void ** ppInterface,
        rtl_uString * pOId,
        struct _typelib_InterfaceTypeDescription * pTypeDescr );

    /** Registers a proxy interface of this environment that can be reanimated and is freed
        explicitly by this environment.

        @param pEnv         this environment
        @param ppInterface  inout parameter of interface to be registered
        @param freeProxy    function to free proxy object
        @param pOId         object id of interface
        @param pTypeDescr   type description of interface
    */
    void (SAL_CALL * registerProxyInterface)(
        struct _uno_ExtEnvironment * pEnv,
        void ** ppProxy,
        uno_freeProxyFunc freeProxy,
        rtl_uString * pOId,
        struct _typelib_InterfaceTypeDescription * pTypeDescr );

    /** Revokes an interface from this environment. You have to revoke any interface that has
        been registered via this method.

        @param pEnv         this environment
        @param pInterface   interface to be revoked
    */
    void (SAL_CALL * revokeInterface)(
        struct _uno_ExtEnvironment * pEnv,
        void * pInterface );

    /** Provides the object id of a given interface.

        @param ppOut        inout oid
        @param pInterface   interface of object
    */
    void (SAL_CALL * getObjectIdentifier)(
        struct _uno_ExtEnvironment * pEnv,
        rtl_uString ** ppOId,
        void * pInterface );

    /** Retrieves an interface identified by its object id and type from this environment.
        Interfaces are retrieved in the same order as they are registered.

        @param pEnv         this environment
        @param ppInterface  inout parameter for the registered interface; (0) if none was found
        @param pOId         object id of interface to be retrieved
        @param pTypeDescr   type description of interface to be retrieved
    */
    void (SAL_CALL * getRegisteredInterface)(
        struct _uno_ExtEnvironment * pEnv,
        void ** ppInterface,
        rtl_uString * pOId,
        struct _typelib_InterfaceTypeDescription * pTypeDescr );

    /** Returns all currently registered interfaces of this environment. The memory block
        allocated might be slightly larger than (*pnLen * sizeof(void *)).

        @param pEnv         this environment
        @param pppInterfaces out param; pointer to array of interface pointers
        @param pnLen        out param; length of array
        @param memAlloc     function for allocating memory that is passed back
    */
    void (SAL_CALL * getRegisteredInterfaces)(
        struct _uno_ExtEnvironment * pEnv,
        void *** pppInterfaces,
        sal_Int32 * pnLen,
        uno_memAlloc memAlloc );

    /* ===== the following part will be late initialized by a matching bridge ===== */

    /** Computes an object id of the given interface; is called by the environment implementation.

        @param pEnv         corresponding environment
        @param ppOId        out param: computed id
        @param pInterface   an interface
    */
    void (SAL_CALL * computeObjectIdentifier)(
        struct _uno_ExtEnvironment * pEnv,
        rtl_uString ** ppOId, void * pInterface );

    /** Function to acquire an interface.

        @param pEnv         corresponding environment
        @param pInterface   an interface
    */
    void (SAL_CALL * acquireInterface)(
        struct _uno_ExtEnvironment * pEnv,
        void * pInterface );

    /** Function to release an interface.

        @param pEnv         corresponding environment
        @param pInterface   an interface
    */
    void (SAL_CALL * releaseInterface)(
        struct _uno_ExtEnvironment * pEnv,
        void * pInterface );

} uno_ExtEnvironment;

#if defined( SAL_W32) ||  defined(SAL_OS2)
#pragma pack(pop)
#endif

/** Function exported by some bridge library providing acquireInterface(), releaseInterface();
    may set a disposing callback.

    @param pEnv environment to be initialized
*/
typedef void (SAL_CALL * uno_initEnvironmentFunc)( uno_Environment * pEnv );
#define UNO_INIT_ENVIRONMENT "uno_initEnvironment"

/** Gets a specific environment. If the specified environment does not exist, then a default one
    is created and registered. The environment revokes itself on last release() call.

    @param ppEnv        inout parameter of environment; given environment will be released
    @param pEnvDcp      descriptor of environment
    @param pContext     some context pointer (e.g., to distinguish java vm; set 0 if not needed)
*/
void SAL_CALL uno_getEnvironment(
    uno_Environment ** ppEnv, rtl_uString * pEnvDcp, void * pContext )
    SAL_THROW_EXTERN_C();

/** Gets all specified environments. Caller has to release returned environments and free allocated
    memory.

    @param pppEnvs      out param; pointer to array of environments
    @param pnLen        out param; length of array
    @param memAlloc     function for allocating memory that is passed back
    @param pEnvDcp      descriptor of environments; 0 defaults to all
*/
void SAL_CALL uno_getRegisteredEnvironments(
    uno_Environment *** pppEnvs, sal_Int32 * pnLen, uno_memAlloc memAlloc,
    rtl_uString * pEnvDcp )
    SAL_THROW_EXTERN_C();

/** Creates an environment. The new environment is anonymous (NOT publicly registered/ accessible).

    @param ppEnv        out parameter of environment; given environment will be released
    @param pEnvDcp      descriptor of environment
    @param pContext     context pointer (e.g., to distinguish java vm); set 0 if not needed
*/
void SAL_CALL uno_createEnvironment(
    uno_Environment ** ppEnv, rtl_uString * pEnvDcp, void * pContext )
    SAL_THROW_EXTERN_C();

/** Dumps out environment information, i.e. registered interfaces.

    @param stream       output stream (FILE *)
    @param pEnv         environment to be dumped
    @param pFilter      if not null, filters output
*/
void SAL_CALL uno_dumpEnvironment(
    void * stream, uno_Environment * pEnv, const sal_Char * pFilter )
    SAL_THROW_EXTERN_C();
/** Dumps out environment information, i.e. registered interfaces.

    @param stream       output stream (FILE *)
    @param pEnvDcp      descritpro of environment to be dumped
    @param pFilter      if not null, filters output
*/
void SAL_CALL uno_dumpEnvironmentByName(
    void * stream, rtl_uString * pEnvDcp, const sal_Char * pFilter )
    SAL_THROW_EXTERN_C();



/** Returns the current Environment.
    In case no Environment has explicitly been entered, a purpose free
    default environment gets returned (e.g. the "uno" or "gcc3" Environment).

    @param ppEnv      inout parameter; a given environment will be released
    @param pTypeName  the optional type of the environment, falls back to "uno"
    @since UDK 3.2.7
*/
void SAL_CALL uno_getCurrentEnvironment(uno_Environment ** ppEnv, rtl_uString * pTypeName)
    SAL_THROW_EXTERN_C();

/** Typedef for variable argument function.
 */
typedef void SAL_CALL uno_EnvCallee(va_list * pParam);

/** Invoke the passed function in the given environment.

    @param pEnv     the target environment
    @param pCallee  the function to call
    @param pParam   the parameter pointer passed to the function
    @since UDK 3.2.7
 */
void SAL_CALL uno_Environment_invoke_v(uno_Environment * pEnv, uno_EnvCallee * pCallee, va_list * pParam)
    SAL_THROW_EXTERN_C();

/** Invoke the passed function in the given environment.

    @param pEnv     the target environment
    @param pCallee  the function to call
    @param ...      the parameters passed to the function
    @since UDK 3.2.7
*/
void SAL_CALL uno_Environment_invoke (uno_Environment * pEnv, uno_EnvCallee * pCallee, ...)
    SAL_THROW_EXTERN_C();

/** Enter an environment explicitly.

    @param pEnv    the environment to enter; NULL leaves all environments
    @since UDK 3.2.7
*/
void SAL_CALL uno_Environment_enter(uno_Environment * pEnv)
    SAL_THROW_EXTERN_C();

/** Check if a particular environment is currently valid, so
    that objects of that environment might be called.

    @param pEnv                    the environment
    @param rtl_uString ** pReason  the reason, if it is not valid
    @return                        1 == valid, 0 == invalid
    @since UDK 3.2.7
*/
int SAL_CALL uno_Environment_isValid(uno_Environment * pEnv, rtl_uString ** pReason)
    SAL_THROW_EXTERN_C();



#ifdef __cplusplus
}
#endif

#endif