Adding upstream version 4:7.4.7.upstream/4%7.4.7upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 389 insertions, 0 deletions

diff --git a/include/uno/environment.h b/include/uno/environment.h
new file mode 100644
index 000000000..700d9c18e
--- /dev/null
+++ b/include/uno/environment.h
@@ -0,0 +1,389 @@
+/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
+/*
+ * This file is part of the LibreOffice project.
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * This file incorporates work covered by the following license notice:
+ *
+ *   Licensed to the Apache Software Foundation (ASF) under one or more
+ *   contributor license agreements. See the NOTICE file distributed
+ *   with this work for additional information regarding copyright
+ *   ownership. The ASF licenses this file to you under the Apache
+ *   License, Version 2.0 (the "License"); you may not use this file
+ *   except in compliance with the License. You may obtain a copy of
+ *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
+ */
+
+/*
+ * This file is part of LibreOffice published API.
+ */
+#ifndef INCLUDED_UNO_ENVIRONMENT_H
+#define INCLUDED_UNO_ENVIRONMENT_H
+
+#include "cppu/cppudllapi.h"
+#include "rtl/ustring.h"
+
+#include <stdarg.h>
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif
+
+struct _uno_ExtEnvironment;
+struct _typelib_InterfaceTypeDescription;
+
+#if defined( _WIN32)
+#pragma pack(push, 8)
+#endif
+
+/** The binary specification of a UNO environment.
+*/
+typedef struct SAL_DLLPUBLIC_RTTI _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 a UNO environment supporting interface registration.
+*/
+typedef struct SAL_DLLPUBLIC_RTTI _uno_ExtEnvironment
+{
+    /** inherits all members of a 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( _WIN32)
+#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"
+
+#ifdef DISABLE_DYNLOADING
+/* We link statically and have just the C++ environment */
+void SAL_CALL CPPU_ENV_uno_initEnvironment( uno_Environment * Env )
+     SAL_THROW_EXTERN_C();
+
+/* We might also have the Java environment */
+void SAL_CALL java_uno_initEnvironment( uno_Environment * Env )
+     SAL_THROW_EXTERN_C();
+#endif
+
+/** 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)
+*/
+CPPU_DLLPUBLIC 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
+*/
+CPPU_DLLPUBLIC 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
+*/
+CPPU_DLLPUBLIC 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
+*/
+CPPU_DLLPUBLIC void SAL_CALL uno_dumpEnvironment(
+    void * stream, uno_Environment * pEnv, const char * pFilter )
+    SAL_THROW_EXTERN_C();
+/** Dumps out environment information, i.e. registered interfaces.
+
+    @param stream       output stream (FILE *)
+    @param pEnvDcp      descriptor of environment to be dumped
+    @param pFilter      if not null, filters output
+*/
+CPPU_DLLPUBLIC void SAL_CALL uno_dumpEnvironmentByName(
+    void * stream, rtl_uString * pEnvDcp, const 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
+*/
+CPPU_DLLPUBLIC 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
+ */
+CPPU_DLLPUBLIC 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
+*/
+CPPU_DLLPUBLIC 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
+*/
+CPPU_DLLPUBLIC 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 pReason                 the reason, if it is not valid
+    @return                        1 == valid, 0 == invalid
+    @since UDK 3.2.7
+*/
+CPPU_DLLPUBLIC int SAL_CALL uno_Environment_isValid(uno_Environment * pEnv, rtl_uString ** pReason)
+    SAL_THROW_EXTERN_C();
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif
+
+/* vim:set shiftwidth=4 softtabstop=4 expandtab: */