include/comphelper/proxyaggregation.hxx

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 #ifndef INCLUDED_COMPHELPER_PROXYAGGREGATION_HXX
  21 #define INCLUDED_COMPHELPER_PROXYAGGREGATION_HXX
  22
  23 #include <cppuhelper/implbase1.hxx>
  24 #include <cppuhelper/interfacecontainer.h>
  25 #include <cppuhelper/basemutex.hxx>
  26 #include <comphelper/uno3.hxx>
  27 #include <cppuhelper/compbase_ex.hxx>
  28 #include <comphelper/comphelperdllapi.h>
  29
  30 namespace com::sun::star::uno {
  31     class XComponentContext;
  32 }
  33 namespace com::sun::star::uno { class XAggregation; }
  34 namespace com::sun::star::lang { class XComponent; }
  35
  36 /* class hierarchy herein:
  37
  38          +-------------------+          helper class for aggregating the proxy to another object
  39          | OProxyAggregation |          - not ref counted
  40          +-------------------+          - no UNO implementation, i.e. not derived from XInterface
  41                    ^                      (neither direct nor indirect)
  42                    |
  43                    |
  44   +----------------------------------+  helper class for aggregating a proxy to an XComponent
  45   | OComponentProxyAggregationHelper |  - life time coupling: if the inner component (the "aggregate")
  46   +----------------------------------+    is disposed, the outer (the delegator) is disposed, too, and
  47                    ^                      vice versa
  48                    |                    - UNO based, implementing XEventListener
  49                    |
  50      +----------------------------+     component aggregating another XComponent
  51      | OComponentProxyAggregation |     - life time coupling as above
  52      +----------------------------+     - ref-counted
  53                                         - implements an XComponent itself
  54
  55   If you need to
  56
  57   - wrap a foreign object which is a XComponent
  58     => use OComponentProxyAggregation
  59        - call componentAggregateProxyFor in your ctor
  60        - call implEnsureDisposeInDtor in your dtor
  61
  62   - wrap a foreign object which is a XComponent, but already have ref-counting mechanisms
  63     inherited from somewhere else
  64     => use OComponentProxyAggregationHelper
  65        - override dispose - don't forget to call the base class' dispose!
  66        - call componentAggregateProxyFor in your ctor
  67
  68   - wrap a foreign object which is no XComponent
  69     => use OProxyAggregation
  70        - call baseAggregateProxyFor in your ctor
  71 */
  72
  73
  74 namespace comphelper
  75 {
  76
  77
  78     //= OProxyAggregation
  79
  80     /** helper class for aggregating a proxy for a foreign object
  81     */
  82     class OProxyAggregation
  83     {
  84     private:
  85         css::uno::Reference< css::uno::XAggregation >             m_xProxyAggregate;
  86         css::uno::Reference< css::lang::XTypeProvider >           m_xProxyTypeAccess;
  87         css::uno::Reference< css::uno::XComponentContext >        m_xContext;
  88
  89     protected:
  90         const css::uno::Reference< css::uno::XComponentContext >& getComponentContext() const
  91         {
  92             return m_xContext;
  93         }
  94
  95     protected:
  96         OProxyAggregation( const css::uno::Reference< css::uno::XComponentContext >& _rxContext );
  97         ~OProxyAggregation();
  98
  99         /// to be called from within your ctor
 100         void baseAggregateProxyFor(
 101             const css::uno::Reference< css::uno::XInterface >& _rxComponent,
 102             oslInterlockedCount& _rRefCount,
 103             ::cppu::OWeakObject& _rDelegator
 104         );
 105
 106         // XInterface and XTypeProvider
 107         /// @throws css::uno::RuntimeException
 108         css::uno::Any SAL_CALL queryAggregation( const css::uno::Type& _rType );
 109         /// @throws css::uno::RuntimeException
 110         css::uno::Sequence< css::uno::Type > SAL_CALL getTypes(  );
 111
 112     private:
 113         OProxyAggregation( const OProxyAggregation& ) = delete;
 114         OProxyAggregation& operator=( const OProxyAggregation& ) = delete;
 115     };
 116
 117
 118     //= OComponentProxyAggregationHelper
 119
 120     /** a helper class for aggregating a proxy to an XComponent
 121
 122         <p>The object couples the life time of itself and the component: if one of the both
 123         dies (in a sense of being disposed), the other one dies, too.</p>
 124
 125         <p>The class itself does not implement XComponent so you need to forward any XComponent::dispose
 126         calls which your derived class gets to the dispose method of this class.</p>
 127     */
 128
 129     class OComponentProxyAggregationHelper :public ::cppu::ImplHelper1 <   css::lang::XEventListener
 130                                                                         >
 131                                             ,private OProxyAggregation
 132     {
 133     private:
 134         typedef ::cppu::ImplHelper1 <   css::lang::XEventListener
 135                                     >   BASE;   // prevents some MSVC problems
 136
 137     protected:
 138         css::uno::Reference< css::lang::XComponent >
 139                                             m_xInner;
 140         ::cppu::OBroadcastHelper&           m_rBHelper;
 141
 142     protected:
 143         // OProxyAggregation
 144         using OProxyAggregation::getComponentContext;
 145
 146         // XInterface
 147         css::uno::Any SAL_CALL queryInterface( const css::uno::Type& _rType ) override;
 148
 149         // XTypeProvider
 150         DECLARE_XTYPEPROVIDER( )
 151
 152     protected:
 153         OComponentProxyAggregationHelper(
 154             const css::uno::Reference< css::uno::XComponentContext >& _rxContext,
 155             ::cppu::OBroadcastHelper& _rBHelper
 156         );
 157         virtual ~OComponentProxyAggregationHelper( );
 158
 159         /// to be called from within your ctor
 160         void componentAggregateProxyFor(
 161             const css::uno::Reference< css::lang::XComponent >& _rxComponent,
 162             oslInterlockedCount& _rRefCount,
 163             ::cppu::OWeakObject& _rDelegator
 164         );
 165
 166         // XEventListener
 167         virtual void SAL_CALL disposing( const css::lang::EventObject& Source ) override;
 168
 169         // XComponent
 170         /// @throws css::uno::RuntimeException
 171         virtual void SAL_CALL dispose() = 0;
 172
 173     private:
 174         OComponentProxyAggregationHelper( const OComponentProxyAggregationHelper& ) = delete;
 175         OComponentProxyAggregationHelper& operator=( const OComponentProxyAggregationHelper& ) = delete;
 176     };
 177
 178
 179     //= OComponentProxyAggregation
 180
 181     class COMPHELPER_DLLPUBLIC OComponentProxyAggregation : public cppu::BaseMutex
 182                                         ,public cppu::WeakComponentImplHelperBase
 183                                         ,public OComponentProxyAggregationHelper
 184     {
 185     protected:
 186         OComponentProxyAggregation(
 187             const css::uno::Reference< css::uno::XComponentContext >& _rxContext,
 188             const css::uno::Reference< css::lang::XComponent >& _rxComponent
 189         );
 190
 191         virtual ~OComponentProxyAggregation() override;
 192
 193         // XInterface
 194         DECLARE_XINTERFACE()
 195         // XTypeProvider
 196         DECLARE_XTYPEPROVIDER()
 197
 198         // OComponentHelper
 199         virtual void SAL_CALL disposing() override;
 200
 201         // XEventListener
 202         virtual void SAL_CALL disposing( const css::lang::EventObject& _rSource ) override;
 203
 204         // XComponent/OComponentProxyAggregationHelper
 205         virtual void SAL_CALL dispose() override;
 206
 207     private:
 208         OComponentProxyAggregation( const OComponentProxyAggregation& ) = delete;
 209         OComponentProxyAggregation& operator=( const OComponentProxyAggregation& ) = delete;
 210     };
 211
 212
 213 }   // namespace comphelper
 214
 215
 216 #endif // INCLUDED_COMPHELPER_PROXYAGGREGATION_HXX
 217
 218 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */