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