include/uno/environment.h

   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( _WIN32)
  36 #pragma pack(push, 8)
  37 #endif
  38
  39 /** The binary specification of a UNO environment.
  40 */
  41 typedef struct SAL_DLLPUBLIC_RTTI _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 a UNO environment supporting interface registration.
 132 */
 133 typedef struct SAL_DLLPUBLIC_RTTI _uno_ExtEnvironment
 134 {
 135     /** inherits all members of a 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( _WIN32)
 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 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      descriptor 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 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: */