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