framework/inc/dispatch/interceptionhelper.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 #pragma once
  21
  22 #include <com/sun/star/frame/XDispatchProviderInterception.hpp>
  23 #include <com/sun/star/frame/XDispatchProviderInterceptor.hpp>
  24 #include <com/sun/star/frame/XDispatchProvider.hpp>
  25 #include <com/sun/star/frame/XDispatch.hpp>
  26 #include <com/sun/star/frame/XFrame.hpp>
  27 #include <com/sun/star/frame/DispatchDescriptor.hpp>
  28
  29 #include <rtl/ref.hxx>
  30 #include <tools/wldcrd.hxx>
  31 #include <cppuhelper/implbase.hxx>
  32 #include <cppuhelper/weakref.hxx>
  33
  34 #include <deque>
  35 #include <string_view>
  36
  37 namespace framework{
  38
  39 class DispatchProvider;
  40
  41 /** @short      implements a helper to support interception with additional functionality.
  42
  43     @descr      This helper implements the complete XDispatchProviderInterception interface with
  44                 master/slave functionality AND using of optional features like registration of URL pattern!
  45
  46     @attention  Don't use this class as direct member - use it dynamically. Do not derive from this class.
  47                 We hold a weakreference to our owner not to our superclass.
  48  */
  49 class InterceptionHelper final : public  ::cppu::WeakImplHelper<
  50                                      css::frame::XDispatchProvider,
  51                                      css::frame::XDispatchProviderInterception,
  52                                      css::lang::XEventListener >
  53 {
  54
  55     // structs, helper
  56
  57     /** @short bind an interceptor component to its URL pattern registration. */
  58     struct InterceptorInfo
  59     {
  60         /** @short reference to the interceptor component. */
  61         css::uno::Reference< css::frame::XDispatchProvider > xInterceptor;
  62
  63         /** @short it's registration for URL patterns.
  64
  65             @descr If the interceptor component does not support the optional interface
  66                    XInterceptorInfo, it will be registered for one pattern "*" by default.
  67                    That would make it possible to handle it in the same manner then real
  68                    registered interceptor objects and we must not implement any special code. */
  69         css::uno::Sequence< OUString > lURLPattern;
  70     };
  71
  72     /** @short implements a list of items of type InterceptorInfo, and provides some special
  73                functions on it.
  74
  75         @descr Because interceptor objects can be registered for URL patterns,
  76                it supports a wildcard search on all list items.
  77      */
  78     class InterceptorList : public ::std::deque< InterceptorInfo >
  79     {
  80         public:
  81
  82             /** @short search for an interceptor inside this list using it's reference.
  83
  84                 @param xInterceptor
  85                         points to the interceptor object, which should be located inside this list.
  86
  87                 @return An iterator object, which points directly to the located item inside this list.
  88                         In case no interceptor could be found, it points to the end of this list!
  89               */
  90             iterator findByReference(const css::uno::Reference< css::frame::XDispatchProviderInterceptor >& xInterceptor)
  91             {
  92                 iterator pIt;
  93                 for (pIt=begin(); pIt!=end(); ++pIt)
  94                 {
  95                     if (pIt->xInterceptor == xInterceptor)
  96                         return pIt;
  97                 }
  98                 return end();
  99             }
 100
 101             /** @short search for an interceptor inside this list using it's reference.
 102
 103                 @param sURL
 104                         URL which should match with a registered pattern.
 105
 106                 @return An iterator object, which points directly to the located item inside this list.
 107                         In case no interceptor could be found, it points to the end of this list!
 108               */
 109             iterator findByPattern(std::u16string_view sURL)
 110             {
 111                 for (iterator pIt=begin(); pIt!=end(); ++pIt)
 112                 {
 113                     for (const OUString& pattern : pIt->lURLPattern)
 114                     {
 115                         WildCard aPattern(pattern);
 116                         if (aPattern.Matches(sURL))
 117                             return pIt;
 118                     }
 119                 }
 120                 return end();
 121             }
 122     };
 123
 124     // member
 125
 126     private:
 127
 128         /** @short reference to the frame, which uses this instance to implement its own interception.
 129
 130             @descr We hold a weak reference only, to make disposing operations easy. */
 131         css::uno::WeakReference< css::frame::XFrame > m_xOwnerWeak;
 132
 133         /** @short this interception helper implements the top level master of an interceptor list ...
 134                    but this member is the lowest possible slave! */
 135         rtl::Reference< DispatchProvider > m_xSlave;
 136
 137         /** @short contains all registered interceptor objects. */
 138         InterceptorList m_lInterceptionRegs;
 139
 140     // native interface
 141
 142     public:
 143
 144         /** @short creates a new interception helper instance.
 145
 146             @param xOwner
 147                     points to the frame, which use this instances to support its own interception interfaces.
 148
 149             @param xSlave
 150                     an outside creates dispatch provider, which has to be used here as lowest slave "interceptor".
 151          */
 152         InterceptionHelper(const css::uno::Reference< css::frame::XFrame >&            xOwner,
 153                            rtl::Reference< DispatchProvider >  xSlave);
 154
 155     private:
 156
 157         /** @short standard destructor.
 158
 159             @descr This method destruct an instance of this class and clear some member.
 160                    This method is protected, because it's not allowed to use this class as a direct member!
 161                    You MUST use a dynamical instance (pointer). That's the reason for a protected dtor.
 162          */
 163         virtual ~InterceptionHelper() override;
 164
 165     // uno interface
 166
 167     public:
 168
 169         // XDispatchProvider
 170
 171         /** @short  query for a dispatch, which implements the requested feature.
 172
 173             @descr  We search inside our list of interception registrations, to locate
 174                     any interested interceptor. In case no interceptor exists or nobody is
 175                     interested on this URL our lowest slave will be used.
 176
 177             @param  aURL
 178                         describes the requested dispatch functionality.
 179
 180             @param  sTargetFrameName
 181                         the name of the target frame or a special name like "_blank", "_top" ...
 182                         Won't be used here ... but may by one of our registered interceptor objects
 183                         or our slave.
 184
 185             @param  nSearchFlags
 186                         optional search parameter for targeting, if sTargetFrameName isn't a special one.
 187
 188             @return A valid dispatch object, if any interceptor or at least our slave is interested on the given URL;
 189                     or NULL otherwise.
 190          */
 191         virtual css::uno::Reference< css::frame::XDispatch > SAL_CALL queryDispatch(const css::util::URL&  aURL            ,
 192                                                                                     const OUString& sTargetFrameName,
 193                                                                                           sal_Int32        nSearchFlags    ) override;
 194
 195         // XDispatchProvider
 196
 197         /** @short implements an optimized queryDispatch() for remote.
 198
 199             @descr It capsulate more than one queryDispatch() requests and return a list of dispatch objects
 200                    as result. Because both lists (in and out) correspond together, it's not allowed to
 201                    pack it - means suppress NULL references!
 202
 203             @param lDescriptor
 204                     a list of queryDispatch() arguments.
 205
 206             @return A list of dispatch objects.
 207          */
 208         virtual css::uno::Sequence< css::uno::Reference< css::frame::XDispatch > > SAL_CALL queryDispatches(const css::uno::Sequence< css::frame::DispatchDescriptor >& lDescriptor) override;
 209
 210         // XDispatchProviderInterception
 211
 212         /** @short      register an interceptor.
 213
 214             @descr      Somebody can register himself to intercept all or some special dispatches.
 215                         It's depend from his supported interfaces. If he implement XInterceptorInfo
 216                         he his called for some special URLs only - otherwise we call it for every request!
 217
 218             @attention  We don't check for double registrations here!
 219
 220             @param      xInterceptor
 221                         reference to interceptor, which wishes to be registered here.
 222
 223             @throw      A RuntimeException if the given reference is NULL!
 224          */
 225         virtual void SAL_CALL registerDispatchProviderInterceptor(const css::uno::Reference< css::frame::XDispatchProviderInterceptor >& xInterceptor) override;
 226
 227         // XDispatchProviderInterception
 228
 229         /** @short      release an interceptor.
 230
 231             @descr      Remove the registered interceptor from our internal list
 232                         and delete all special information about it.
 233
 234             @param      xInterceptor
 235                         reference to the interceptor, which wishes to be deregistered.
 236
 237             @throw      A RuntimeException if the given reference is NULL!
 238          */
 239         virtual void SAL_CALL releaseDispatchProviderInterceptor( const css::uno::Reference< css::frame::XDispatchProviderInterceptor >& xInterceptor ) override;
 240
 241         // XEventListener
 242
 243         /** @short      Is called from our owner frame, in case he will be disposed.
 244
 245             @descr      We have to release all references to him then.
 246                         Normally we will die by ref count too...
 247          */
 248         virtual void SAL_CALL disposing(const css::lang::EventObject& aEvent) override;
 249
 250         const rtl::Reference<DispatchProvider> & GetSlave() const { return m_xSlave; }
 251
 252 }; // class InterceptionHelper
 253
 254 } // namespace framework
 255
 256 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */