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