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