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