diff options
Diffstat (limited to 'cppu/inc/uno/environment.h')
| -rw-r--r-- | cppu/inc/uno/environment.h | 385 |
1 files changed, 385 insertions, 0 deletions
diff --git a/cppu/inc/uno/environment.h b/cppu/inc/uno/environment.h new file mode 100644 index 000000000000..f959aa2571f4 --- /dev/null +++ b/cppu/inc/uno/environment.h @@ -0,0 +1,385 @@ +/************************************************************************* + * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright 2000, 2010 Oracle and/or its affiliates. + * + * OpenOffice.org - a multi-platform office productivity suite + * + * This file is part of OpenOffice.org. + * + * OpenOffice.org is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License version 3 + * only, as published by the Free Software Foundation. + * + * OpenOffice.org is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License version 3 for more details + * (a copy is included in the LICENSE file that accompanied this code). + * + * You should have received a copy of the GNU Lesser General Public License + * version 3 along with OpenOffice.org. If not, see + * <http://www.openoffice.org/license.html> + * for a copy of the LGPLv3 License. + * + ************************************************************************/ +#ifndef _UNO_ENVIRONMENT_H_ +#define _UNO_ENVIRONMENT_H_ + +#include <sal/types.h> +#include <rtl/ustring.h> + +#include <stdarg.h> + +#ifdef __cplusplus +extern "C" +{ +#endif + +struct _uno_ExtEnvironment; +struct _typelib_InterfaceTypeDescription; + +#if defined( SAL_W32) +#pragma pack(push, 8) +#elif defined(SAL_OS2) +#pragma pack(push, 8) +#endif + +/** The binary specification of an UNO environment. +*/ +typedef struct _uno_Environment +{ + /** reserved for future use (0 if not used) + */ + void * pReserved; + + /** type name of environment + */ + rtl_uString * pTypeName; + + /** free context pointer to be used for specific classes of environments (e.g., a jvm pointer) + */ + void * pContext; + + /** pointer to extended environment (interface registration functionality), if supported + */ + struct _uno_ExtEnvironment * pExtEnv; + + /** Acquires this environment. + + @param pEnv this environment + */ + void (SAL_CALL * acquire)( struct _uno_Environment * pEnv ); + + /** Releases this environment; last release of environment will revoke the environment from + runtime. + + @param pEnv this environment + */ + void (SAL_CALL * release)( struct _uno_Environment * pEnv ); + + /** Acquires this environment weakly. You can only harden a weakly held environment if it + is still acquired hard (acquire()). + + @param pEnv this environment + */ + void (SAL_CALL * acquireWeak)( struct _uno_Environment * pEnv ); + + /** Releases this environment weakly in correspondence to acquireWeak(). + + @param pEnv this environment + */ + void (SAL_CALL * releaseWeak)( struct _uno_Environment * pEnv ); + + /** Makes hard reference out of weak referenced environment. You can only harden a weakly + held environment if it is still acquired hard (acquire()). + + @param ppHardEnv inout hard referenced environment (has to be released via release()) + @param pEnv environment (may be weak referenced) + */ + void (SAL_CALL * harden)( + struct _uno_Environment ** ppHardEnv, + struct _uno_Environment * pEnv ); + + /** Call this function to EXPLICITLY dispose this environment (e.g., release all + interfaces). You may want to call this function before shutting down due to a runtime error. + + @param pEnv this environment + */ + void (SAL_CALL * dispose)( struct _uno_Environment * pEnv ); + + /* ===== the following part will be late initialized by a matching bridge ===== * + * ===== and is NOT for public use. ===== */ + + /** CALLBACK function pointer: Disposing callback function pointer that can be set to get + signalled before the environment is destroyed. + + @param pEnv environment that is being disposed + */ + void (SAL_CALL * environmentDisposing)( struct _uno_Environment * pEnv ); +} uno_Environment; + +/** Generic function pointer declaration to free a proxy object if it is not needed by the + environment anymore. + Any proxy object must register itself on first acquire() call and revoke itself on last + release() call. This can happen several times because the environment caches proxy objects + until the environment explicitly frees the proxy object calling this function. + + @param pEnv environment + @param pProxy proxy pointer +*/ +typedef void (SAL_CALL * uno_freeProxyFunc)( struct _uno_ExtEnvironment * pEnv, void * pProxy ); + +/** Generic function pointer declaration to allocate memory. Used with getRegisteredInterfaces(). + + @param nBytes amount of memory in bytes + @return pointer to allocated memory +*/ +typedef void * (SAL_CALL * uno_memAlloc)( sal_Size nBytes ); + +/** The binary specification of an UNO environment supporting interface registration. +*/ +typedef struct _uno_ExtEnvironment +{ + /** inherits all members of an uno_Environment + */ + uno_Environment aBase; + + /** Registers an interface of this environment. + + @param pEnv this environment + @param ppInterface inout parameter of interface to be registered + @param pOId object id of interface + @param pTypeDescr type description of interface + */ + void (SAL_CALL * registerInterface)( + struct _uno_ExtEnvironment * pEnv, + void ** ppInterface, + rtl_uString * pOId, + struct _typelib_InterfaceTypeDescription * pTypeDescr ); + + /** Registers a proxy interface of this environment that can be reanimated and is freed + explicitly by this environment. + + @param pEnv this environment + @param ppInterface inout parameter of interface to be registered + @param freeProxy function to free proxy object + @param pOId object id of interface + @param pTypeDescr type description of interface + */ + void (SAL_CALL * registerProxyInterface)( + struct _uno_ExtEnvironment * pEnv, + void ** ppProxy, + uno_freeProxyFunc freeProxy, + rtl_uString * pOId, + struct _typelib_InterfaceTypeDescription * pTypeDescr ); + + /** Revokes an interface from this environment. You have to revoke any interface that has + been registered via this method. + + @param pEnv this environment + @param pInterface interface to be revoked + */ + void (SAL_CALL * revokeInterface)( + struct _uno_ExtEnvironment * pEnv, + void * pInterface ); + + /** Provides the object id of a given interface. + + @param ppOut inout oid + @param pInterface interface of object + */ + void (SAL_CALL * getObjectIdentifier)( + struct _uno_ExtEnvironment * pEnv, + rtl_uString ** ppOId, + void * pInterface ); + + /** Retrieves an interface identified by its object id and type from this environment. + Interfaces are retrieved in the same order as they are registered. + + @param pEnv this environment + @param ppInterface inout parameter for the registered interface; (0) if none was found + @param pOId object id of interface to be retrieved + @param pTypeDescr type description of interface to be retrieved + */ + void (SAL_CALL * getRegisteredInterface)( + struct _uno_ExtEnvironment * pEnv, + void ** ppInterface, + rtl_uString * pOId, + struct _typelib_InterfaceTypeDescription * pTypeDescr ); + + /** Returns all currently registered interfaces of this environment. The memory block + allocated might be slightly larger than (*pnLen * sizeof(void *)). + + @param pEnv this environment + @param pppInterfaces out param; pointer to array of interface pointers + @param pnLen out param; length of array + @param memAlloc function for allocating memory that is passed back + */ + void (SAL_CALL * getRegisteredInterfaces)( + struct _uno_ExtEnvironment * pEnv, + void *** pppInterfaces, + sal_Int32 * pnLen, + uno_memAlloc memAlloc ); + + /* ===== the following part will be late initialized by a matching bridge ===== */ + + /** Computes an object id of the given interface; is called by the environment implementation. + + @param pEnv corresponding environment + @param ppOId out param: computed id + @param pInterface an interface + */ + void (SAL_CALL * computeObjectIdentifier)( + struct _uno_ExtEnvironment * pEnv, + rtl_uString ** ppOId, void * pInterface ); + + /** Function to acquire an interface. + + @param pEnv corresponding environment + @param pInterface an interface + */ + void (SAL_CALL * acquireInterface)( + struct _uno_ExtEnvironment * pEnv, + void * pInterface ); + + /** Function to release an interface. + + @param pEnv corresponding environment + @param pInterface an interface + */ + void (SAL_CALL * releaseInterface)( + struct _uno_ExtEnvironment * pEnv, + void * pInterface ); + +} uno_ExtEnvironment; + +#if defined( SAL_W32) || defined(SAL_OS2) +#pragma pack(pop) +#endif + +/** Function exported by some bridge library providing acquireInterface(), releaseInterface(); + may set a disposing callback. + + @param pEnv environment to be initialized +*/ +typedef void (SAL_CALL * uno_initEnvironmentFunc)( uno_Environment * pEnv ); +#define UNO_INIT_ENVIRONMENT "uno_initEnvironment" + +/** Gets a specific environment. If the specified environment does not exist, then a default one + is created and registered. The environment revokes itself on last release() call. + + @param ppEnv inout parameter of environment; given environment will be released + @param pEnvDcp descriptor of environment + @param pContext some context pointer (e.g., to distinguish java vm; set 0 if not needed) +*/ +void SAL_CALL uno_getEnvironment( + uno_Environment ** ppEnv, rtl_uString * pEnvDcp, void * pContext ) + SAL_THROW_EXTERN_C(); + +/** Gets all specified environments. Caller has to release returned environments and free allocated + memory. + + @param pppEnvs out param; pointer to array of environments + @param pnLen out param; length of array + @param memAlloc function for allocating memory that is passed back + @param pEnvDcp descriptor of environments; 0 defaults to all +*/ +void SAL_CALL uno_getRegisteredEnvironments( + uno_Environment *** pppEnvs, sal_Int32 * pnLen, uno_memAlloc memAlloc, + rtl_uString * pEnvDcp ) + SAL_THROW_EXTERN_C(); + +/** Creates an environment. The new environment is anonymous (NOT publicly registered/ accessible). + + @param ppEnv out parameter of environment; given environment will be released + @param pEnvDcp descriptor of environment + @param pContext context pointer (e.g., to distinguish java vm); set 0 if not needed +*/ +void SAL_CALL uno_createEnvironment( + uno_Environment ** ppEnv, rtl_uString * pEnvDcp, void * pContext ) + SAL_THROW_EXTERN_C(); + +/** Dumps out environment information, i.e. registered interfaces. + + @param stream output stream (FILE *) + @param pEnv environment to be dumped + @param pFilter if not null, filters output +*/ +void SAL_CALL uno_dumpEnvironment( + void * stream, uno_Environment * pEnv, const sal_Char * pFilter ) + SAL_THROW_EXTERN_C(); +/** Dumps out environment information, i.e. registered interfaces. + + @param stream output stream (FILE *) + @param pEnvDcp descritpro of environment to be dumped + @param pFilter if not null, filters output +*/ +void SAL_CALL uno_dumpEnvironmentByName( + void * stream, rtl_uString * pEnvDcp, const sal_Char * pFilter ) + SAL_THROW_EXTERN_C(); + + + +/** Returns the current Environment. + In case no Environment has explicitly been entered, a purpose free + default environment gets returned (e.g. the "uno" or "gcc3" Environment). + + @param ppEnv inout parameter; a given environment will be released + @param pTypeName the optional type of the environment, falls back to "uno" + @since UDK 3.2.7 +*/ +void SAL_CALL uno_getCurrentEnvironment(uno_Environment ** ppEnv, rtl_uString * pTypeName) + SAL_THROW_EXTERN_C(); + +/** Typedef for variable argument function. + */ +typedef void SAL_CALL uno_EnvCallee(va_list * pParam); + +/** Invoke the passed function in the given environment. + + @param pEnv the target environment + @param pCallee the function to call + @param pParam the parameter pointer passed to the function + @since UDK 3.2.7 + */ +void SAL_CALL uno_Environment_invoke_v(uno_Environment * pEnv, uno_EnvCallee * pCallee, va_list * pParam) + SAL_THROW_EXTERN_C(); + +/** Invoke the passed function in the given environment. + + @param pEnv the target environment + @param pCallee the function to call + @param ... the parameters passed to the function + @since UDK 3.2.7 +*/ +void SAL_CALL uno_Environment_invoke (uno_Environment * pEnv, uno_EnvCallee * pCallee, ...) + SAL_THROW_EXTERN_C(); + +/** Enter an environment explicitly. + + @param pEnv the environment to enter; NULL leaves all environments + @since UDK 3.2.7 +*/ +void SAL_CALL uno_Environment_enter(uno_Environment * pEnv) + SAL_THROW_EXTERN_C(); + +/** Check if a particular environment is currently valid, so + that objects of that environment might be called. + + @param pEnv the environment + @param rtl_uString ** pReason the reason, if it is not valid + @return 1 == valid, 0 == invalid + @since UDK 3.2.7 +*/ +int SAL_CALL uno_Environment_isValid(uno_Environment * pEnv, rtl_uString ** pReason) + SAL_THROW_EXTERN_C(); + + + +#ifdef __cplusplus +} +#endif + +#endif |