LCOV - code coverage report
Current view: top level - include/ucbhelper - interceptedinteraction.hxx (source / functions) Hit Total Coverage
Test: commit 10e77ab3ff6f4314137acd6e2702a6e5c1ce1fae Lines: 7 7 100.0 %
Date: 2014-11-03 Functions: 4 6 66.7 %
Legend: Lines: hit not hit

          Line data    Source code
       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       10553 : class UCBHELPER_DLLPUBLIC InterceptedInteraction : public ::cppu::WeakImplHelper1< ::com::sun::star::task::XInteractionHandler >
      44             : {
      45             : 
      46             :     // types
      47             :     public:
      48             : 
      49      116083 :         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       10553 :             InterceptedRequest()
     100       10553 :             {
     101       10553 :                 MatchExact = false;
     102       10553 :                 Handle     = INVALID_HANDLE;
     103       10553 :             }
     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 isnt 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: */

Generated by: LCOV version 1.10