cppu/inc/uno/environment.h

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