LCOV - code coverage report
Current view: top level - include/uno - environment.h (source / functions) Hit Total Coverage
Test: commit e02a6cb2c3e2b23b203b422e4e0680877f232636 Lines: 1 1 100.0 %
Date: 2014-04-14 Functions: 1 1 100.0 %
Legend: Lines: hit not hit

          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 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( 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           3 : 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 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 sal_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      descritpro 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 sal_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: */

Generated by: LCOV version 1.10