include/ucbhelper/interceptedinteraction.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_UCBHELPER_INTERCEPTEDINTERACTION_HXX
  21 #define INCLUDED_UCBHELPER_INTERCEPTEDINTERACTION_HXX
  22
  23 #include <vector>
  24
  25 #include <com/sun/star/task/XInteractionHandler.hpp>
  26
  27 #include <cppuhelper/implbase.hxx>
  28 #include <ucbhelper/ucbhelperdllapi.h>
  29
  30 namespace com::sun::star::task { class XInteractionRequest; }
  31
  32
  33 namespace ucbhelper{
  34
  35
  36 /** @short  it wraps any other interaction handler and intercept
  37             its handle() requests.
  38
  39     @descr  This class can be used as:
  40             - instance if special interactions must be suppressed
  41               only
  42             - or as base class if interactions must be modified.
  43  */
  44 // extra struct to work around MSVC linking issue
  45 struct InterceptedInteraction_Base : public ::cppu::WeakImplHelper< css::task::XInteractionHandler > {};
  46
  47 class UCBHELPER_DLLPUBLIC InterceptedInteraction : public InterceptedInteraction_Base
  48 {
  49
  50     // types
  51     public:
  52
  53         struct InterceptedRequest
  54         {
  55
  56             /** @short  marks an Handle as invalid.
  57              */
  58             static const sal_Int32 INVALID_HANDLE = -1;
  59
  60
  61             /** @short  contains the interaction request, which should be intercepted. */
  62             css::uno::Any Request;
  63
  64
  65             /** @short  specify the fix continuation, which must be selected, if the
  66                         interaction could be intercepted successfully.
  67               */
  68             css::uno::Type Continuation;
  69
  70
  71             /** @short  it's a unique identifier, which must be managed by the outside code.
  72
  73                 @descr  If there is a derived class, which overwrites the InterceptedInteraction::intercepted()
  74                         method, it will be called with a reference to an InterceptedRequest struct.
  75                         Then it can use the handle to react without checking the request type again.
  76              */
  77             sal_Int32 Handle;
  78
  79
  80             /** @short  default ctor.
  81
  82                 @descr  Such constructed object can't be used really.
  83                         Might it will crash if it's used!
  84                         Don't forget to initialize all(!) members...
  85              */
  86             InterceptedRequest()
  87             {
  88                 Handle     = INVALID_HANDLE;
  89             }
  90
  91         };
  92
  93
  94         /** @short  represent the different states, which can occur
  95                     as result of an interception.
  96
  97             @see    impl_interceptRequest()
  98          */
  99         enum EInterceptionState
 100         {
 101             /** none of the specified interceptions match the incoming request */
 102             E_NOT_INTERCEPTED,
 103             /** the request could be intercepted - but the specified continuation could not be located.
 104                 That's normally an error of the programmer. May be the interaction request does not use
 105                 the right set of continuations ... or the interception list contains the wrong continuation. */
 106             E_NO_CONTINUATION_FOUND,
 107             /** the request could be intercepted and the specified continuation could be selected successfully. */
 108             E_INTERCEPTED
 109         };
 110
 111
 112     // member
 113     protected:
 114
 115
 116         /** @short  reference to the intercepted interaction handler.
 117
 118             @descr  NULL is allowed for this member!
 119                     All interaction will be aborted then ...
 120                     expecting th handle() was overwritten by
 121                     a derived class.
 122          */
 123         css::uno::Reference< css::task::XInteractionHandler > m_xInterceptedHandler;
 124
 125
 126         /** @short  these list contains the requests, which should be intercepted.
 127          */
 128         ::std::vector< InterceptedRequest > m_lInterceptions;
 129
 130
 131     // native interface
 132     public:
 133
 134
 135         /** @short  initialize a new instance with default values.
 136          */
 137         InterceptedInteraction();
 138
 139
 140         /** @short  initialize a new instance with the interaction handler,
 141                     which should be intercepted.
 142
 143             @attention  If such interaction handler isn't set here,
 144                         all incoming requests will be aborted ...
 145                         if the right continuation is available!
 146
 147             @param  xInterceptedHandler
 148                     the outside interaction handler, which should
 149                     be intercepted here.
 150          */
 151         void setInterceptedHandler(const css::uno::Reference< css::task::XInteractionHandler >& xInterceptedHandler);
 152
 153
 154         /** @short  set a new list of intercepted interactions.
 155
 156             @attention  If the interface method handle() will be overwritten by
 157                         a derived class, the functionality behind these static list
 158                         can't be used.
 159
 160             @param  lInterceptions
 161                     the list of intercepted requests.
 162          */
 163         void setInterceptions(::std::vector< InterceptedRequest >&& lInterceptions);
 164
 165
 166         /** @short  extract a requested continuation from the list of available ones.
 167
 168             @param  lContinuations
 169                     the list of available continuations.
 170
 171             @param  aType
 172                     is used to locate the right continuation,
 173                     by checking its interface type.
 174
 175             @return A valid reference to the continuation, if it could be located...
 176                     or an empty reference otherwise.
 177          */
 178         static css::uno::Reference< css::task::XInteractionContinuation > extractContinuation(
 179                     const css::uno::Sequence< css::uno::Reference< css::task::XInteractionContinuation > >& lContinuations,
 180                     const css::uno::Type&                                                                                             aType         );
 181
 182
 183     // usable for derived classes
 184     protected:
 185
 186
 187         /** @short  can be overwritten by a derived class to handle interceptions
 188                     outside.
 189
 190             @descr  This base implementation checks, if the request could be intercepted
 191                     successfully. Then this method intercepted() is called.
 192                     The default implementation returns "NOT_INTERCEPTED" every time.
 193                     So the method impl_interceptRequest() uses the right continuation automatically.
 194
 195                     If this method was overwritten and something different "NO_INTERCEPTED"
 196                     is returned, the method impl_interceptRequest() will return immediately with
 197                     the result, which is returned by this intercepted() method.
 198                     Then the continuations must be selected inside the intercepted() call!
 199
 200             @param  rRequest
 201                     it points to the intercepted request (means the item of the
 202                     set interception list). e.g. its "Handle" member can be used
 203                     to identify it and react very easy, without the need to check the
 204                     type of the exception ...
 205
 206             @param  xOrgRequest
 207                     points to the original interaction, which was intercepted.
 208                     It provides access to the exception and the list of possible
 209                     continuations.
 210
 211             @return The result of this operation.
 212                     Note: If E_NOT_INTERCEPTED is returned the default handling of the base class
 213                     will be used automatically for this request!
 214          */
 215         virtual EInterceptionState intercepted(const InterceptedRequest&                                                             rRequest   ,
 216                                                const css::uno::Reference< css::task::XInteractionRequest >& xOrgRequest);
 217
 218
 219     // uno interface
 220     public:
 221
 222
 223         /** @short  implements the default handling of this class...
 224                     or can be overwritten by any derived class.
 225
 226             @descr  If no further class is derived from this one
 227                     -> the default implementation is used. Then the
 228                     internal list of requests is used to handle different
 229                     interactions automatically.
 230                     (see impl_interceptRequest())
 231
 232                     If this method was overwritten by a derived implementation
 233                     -> the new implementation has to do everything by itself.
 234                     Of course it can access all members/helpers and work with it.
 235                     But the default implementation is not used automatically then.
 236
 237             @param  xRequest
 238                     the interaction request, which should be intercepted.
 239          */
 240         virtual void SAL_CALL handle(const css::uno::Reference< css::task::XInteractionRequest >& xRequest) override;
 241
 242
 243     // helper
 244     private:
 245
 246
 247         /** @short  implements the default handling:
 248                     - intercept or forward to internal handler.
 249          */
 250         UCBHELPER_DLLPRIVATE void impl_handleDefault(const css::uno::Reference< css::task::XInteractionRequest >& xRequest);
 251
 252
 253         /** @short  implements the interception of requests.
 254
 255             @descr  The incoming request will be analyzed, if it match
 256                     any request of the m_lIntercepions list.
 257                     If an interception could be found, its continuation will be
 258                     searched and selected.
 259
 260                     The method return the state of that operation.
 261                     But it doesn't call the intercepted and here set
 262                     interaction handler. That has to be done in the outside method.
 263
 264             @param  xRequest
 265                     the interaction request, which should be intercepted.
 266
 267             @return A identifier, which indicates if the request was intercepted,
 268                     the continuation was found and selected... or not.
 269          */
 270         UCBHELPER_DLLPRIVATE EInterceptionState impl_interceptRequest(const css::uno::Reference< css::task::XInteractionRequest >& xRequest);
 271 };
 272
 273 } // namespace ucbhelper
 274
 275 #endif // INCLUDED_UCBHELPER_INTERCEPTEDINTERACTION_HXX
 276
 277 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */