1 /************************************************************************* 2 * 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * Copyright 2000, 2010 Oracle and/or its affiliates. 6 * 7 * OpenOffice.org - a multi-platform office productivity suite 8 * 9 * This file is part of OpenOffice.org. 10 * 11 * OpenOffice.org is free software: you can redistribute it and/or modify 12 * it under the terms of the GNU Lesser General Public License version 3 13 * only, as published by the Free Software Foundation. 14 * 15 * OpenOffice.org is distributed in the hope that it will be useful, 16 * but WITHOUT ANY WARRANTY; without even the implied warranty of 17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 18 * GNU Lesser General Public License version 3 for more details 19 * (a copy is included in the LICENSE file that accompanied this code). 20 * 21 * You should have received a copy of the GNU Lesser General Public License 22 * version 3 along with OpenOffice.org. If not, see 23 * <http://www.openoffice.org/license.html> 24 * for a copy of the LGPLv3 License. 25 * 26 ************************************************************************/ 27 #ifndef _UNO_ENVIRONMENT_H_ 28 #define _UNO_ENVIRONMENT_H_ 29 30 #include <sal/types.h> 31 #include <rtl/ustring.h> 32 33 #include <stdarg.h> 34 35 #ifdef __cplusplus 36 extern "C" 37 { 38 #endif 39 40 struct _uno_ExtEnvironment; 41 struct _typelib_InterfaceTypeDescription; 42 43 #if defined( SAL_W32) 44 #pragma pack(push, 8) 45 #elif defined(SAL_OS2) 46 #pragma pack(push, 8) 47 #endif 48 49 /** The binary specification of an UNO environment. 50 */ 51 typedef struct _uno_Environment 52 { 53 /** reserved for future use (0 if not used) 54 */ 55 void * pReserved; 56 57 /** type name of environment 58 */ 59 rtl_uString * pTypeName; 60 61 /** free context pointer to be used for specific classes of environments (e.g., a jvm pointer) 62 */ 63 void * pContext; 64 65 /** pointer to extended environment (interface registration functionality), if supported 66 */ 67 struct _uno_ExtEnvironment * pExtEnv; 68 69 /** Acquires this environment. 70 71 @param pEnv this environment 72 */ 73 void (SAL_CALL * acquire)( struct _uno_Environment * pEnv ); 74 75 /** Releases this environment; last release of environment will revoke the environment from 76 runtime. 77 78 @param pEnv this environment 79 */ 80 void (SAL_CALL * release)( struct _uno_Environment * pEnv ); 81 82 /** Acquires this environment weakly. You can only harden a weakly held environment if it 83 is still acquired hard (acquire()). 84 85 @param pEnv this environment 86 */ 87 void (SAL_CALL * acquireWeak)( struct _uno_Environment * pEnv ); 88 89 /** Releases this environment weakly in correspondence to acquireWeak(). 90 91 @param pEnv this environment 92 */ 93 void (SAL_CALL * releaseWeak)( struct _uno_Environment * pEnv ); 94 95 /** Makes hard reference out of weak referenced environment. You can only harden a weakly 96 held environment if it is still acquired hard (acquire()). 97 98 @param ppHardEnv inout hard referenced environment (has to be released via release()) 99 @param pEnv environment (may be weak referenced) 100 */ 101 void (SAL_CALL * harden)( 102 struct _uno_Environment ** ppHardEnv, 103 struct _uno_Environment * pEnv ); 104 105 /** Call this function to EXPLICITLY dispose this environment (e.g., release all 106 interfaces). You may want to call this function before shutting down due to a runtime error. 107 108 @param pEnv this environment 109 */ 110 void (SAL_CALL * dispose)( struct _uno_Environment * pEnv ); 111 112 /* ===== the following part will be late initialized by a matching bridge ===== * 113 * ===== and is NOT for public use. ===== */ 114 115 /** CALLBACK function pointer: Disposing callback function pointer that can be set to get 116 signalled before the environment is destroyed. 117 118 @param pEnv environment that is being disposed 119 */ 120 void (SAL_CALL * environmentDisposing)( struct _uno_Environment * pEnv ); 121 } uno_Environment; 122 123 /** Generic function pointer declaration to free a proxy object if it is not needed by the 124 environment anymore. 125 Any proxy object must register itself on first acquire() call and revoke itself on last 126 release() call. This can happen several times because the environment caches proxy objects 127 until the environment explicitly frees the proxy object calling this function. 128 129 @param pEnv environment 130 @param pProxy proxy pointer 131 */ 132 typedef void (SAL_CALL * uno_freeProxyFunc)( struct _uno_ExtEnvironment * pEnv, void * pProxy ); 133 134 /** Generic function pointer declaration to allocate memory. Used with getRegisteredInterfaces(). 135 136 @param nBytes amount of memory in bytes 137 @return pointer to allocated memory 138 */ 139 typedef void * (SAL_CALL * uno_memAlloc)( sal_Size nBytes ); 140 141 /** The binary specification of an UNO environment supporting interface registration. 142 */ 143 typedef struct _uno_ExtEnvironment 144 { 145 /** inherits all members of an uno_Environment 146 */ 147 uno_Environment aBase; 148 149 /** Registers an interface of this environment. 150 151 @param pEnv this environment 152 @param ppInterface inout parameter of interface to be registered 153 @param pOId object id of interface 154 @param pTypeDescr type description of interface 155 */ 156 void (SAL_CALL * registerInterface)( 157 struct _uno_ExtEnvironment * pEnv, 158 void ** ppInterface, 159 rtl_uString * pOId, 160 struct _typelib_InterfaceTypeDescription * pTypeDescr ); 161 162 /** Registers a proxy interface of this environment that can be reanimated and is freed 163 explicitly by this environment. 164 165 @param pEnv this environment 166 @param ppInterface inout parameter of interface to be registered 167 @param freeProxy function to free proxy object 168 @param pOId object id of interface 169 @param pTypeDescr type description of interface 170 */ 171 void (SAL_CALL * registerProxyInterface)( 172 struct _uno_ExtEnvironment * pEnv, 173 void ** ppProxy, 174 uno_freeProxyFunc freeProxy, 175 rtl_uString * pOId, 176 struct _typelib_InterfaceTypeDescription * pTypeDescr ); 177 178 /** Revokes an interface from this environment. You have to revoke any interface that has 179 been registered via this method. 180 181 @param pEnv this environment 182 @param pInterface interface to be revoked 183 */ 184 void (SAL_CALL * revokeInterface)( 185 struct _uno_ExtEnvironment * pEnv, 186 void * pInterface ); 187 188 /** Provides the object id of a given interface. 189 190 @param ppOut inout oid 191 @param pInterface interface of object 192 */ 193 void (SAL_CALL * getObjectIdentifier)( 194 struct _uno_ExtEnvironment * pEnv, 195 rtl_uString ** ppOId, 196 void * pInterface ); 197 198 /** Retrieves an interface identified by its object id and type from this environment. 199 Interfaces are retrieved in the same order as they are registered. 200 201 @param pEnv this environment 202 @param ppInterface inout parameter for the registered interface; (0) if none was found 203 @param pOId object id of interface to be retrieved 204 @param pTypeDescr type description of interface to be retrieved 205 */ 206 void (SAL_CALL * getRegisteredInterface)( 207 struct _uno_ExtEnvironment * pEnv, 208 void ** ppInterface, 209 rtl_uString * pOId, 210 struct _typelib_InterfaceTypeDescription * pTypeDescr ); 211 212 /** Returns all currently registered interfaces of this environment. The memory block 213 allocated might be slightly larger than (*pnLen * sizeof(void *)). 214 215 @param pEnv this environment 216 @param pppInterfaces out param; pointer to array of interface pointers 217 @param pnLen out param; length of array 218 @param memAlloc function for allocating memory that is passed back 219 */ 220 void (SAL_CALL * getRegisteredInterfaces)( 221 struct _uno_ExtEnvironment * pEnv, 222 void *** pppInterfaces, 223 sal_Int32 * pnLen, 224 uno_memAlloc memAlloc ); 225 226 /* ===== the following part will be late initialized by a matching bridge ===== */ 227 228 /** Computes an object id of the given interface; is called by the environment implementation. 229 230 @param pEnv corresponding environment 231 @param ppOId out param: computed id 232 @param pInterface an interface 233 */ 234 void (SAL_CALL * computeObjectIdentifier)( 235 struct _uno_ExtEnvironment * pEnv, 236 rtl_uString ** ppOId, void * pInterface ); 237 238 /** Function to acquire an interface. 239 240 @param pEnv corresponding environment 241 @param pInterface an interface 242 */ 243 void (SAL_CALL * acquireInterface)( 244 struct _uno_ExtEnvironment * pEnv, 245 void * pInterface ); 246 247 /** Function to release an interface. 248 249 @param pEnv corresponding environment 250 @param pInterface an interface 251 */ 252 void (SAL_CALL * releaseInterface)( 253 struct _uno_ExtEnvironment * pEnv, 254 void * pInterface ); 255 256 } uno_ExtEnvironment; 257 258 #if defined( SAL_W32) || defined(SAL_OS2) 259 #pragma pack(pop) 260 #endif 261 262 /** Function exported by some bridge library providing acquireInterface(), releaseInterface(); 263 may set a disposing callback. 264 265 @param pEnv environment to be initialized 266 */ 267 typedef void (SAL_CALL * uno_initEnvironmentFunc)( uno_Environment * pEnv ); 268 #define UNO_INIT_ENVIRONMENT "uno_initEnvironment" 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 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 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 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 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 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 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 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 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 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 rtl_uString ** pReason the reason, if it is not valid 373 @return 1 == valid, 0 == invalid 374 @since UDK 3.2.7 375 */ 376 int SAL_CALL uno_Environment_isValid(uno_Environment * pEnv, rtl_uString ** pReason) 377 SAL_THROW_EXTERN_C(); 378 379 380 381 #ifdef __cplusplus 382 } 383 #endif 384 385 #endif 386