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