configmgr/source/inc/interactionrequest.hxx

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: interactionrequest.hxx,v $
  10  * $Revision: 1.5 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30
  31 #ifndef CONFIGMGR_INTERACTIONREQUEST_HXX
  32 #define CONFIGMGR_INTERACTIONREQUEST_HXX
  33
  34 #include <com/sun/star/task/XInteractionRequest.hpp>
  35 #include <com/sun/star/task/XInteractionAbort.hpp>
  36 #include <com/sun/star/task/XInteractionRetry.hpp>
  37 #include <com/sun/star/task/XInteractionApprove.hpp>
  38 #include <com/sun/star/task/XInteractionDisapprove.hpp>
  39 #include <cppuhelper/implbase1.hxx>
  40
  41 namespace configmgr {
  42 namespace apihelper {
  43     namespace uno  = com::sun::star::uno;
  44     namespace task = com::sun::star::task;
  45 //============================================================================
  46
  47 /**
  48   * This class implements the interface XInteractionRequest. Instances can
  49   * be passed directly to XInteractionHandler::handle(...). Each interaction
  50   * request contains an exception describing the error and a number of
  51   * interaction continuations describing the possible "answers" for the request.
  52   * After the request was passed to XInteractionHandler::handle(...) the method
  53   * getSelection() returns the continuation choosen by the interaction handler.
  54   *
  55   * The typical usage of this class would be:
  56   *
  57   * 1) Create exception object that shall be handled by the interaction handler.
  58   * 2) Create InteractionRequest, supply exception as ctor parameter
  59   * 3) Create continuations needed and add them to a sequence
  60   * 4) Supply the continuations to the InteractionRequest by calling
  61   *    setContinuations(...)
  62   *
  63   * This class can also be used as base class for more specialized requests,
  64   * like authentication requests.
  65   */
  66 class InteractionRequest : public cppu::WeakImplHelper1<com::sun::star::task::XInteractionRequest>
  67 {
  68     struct Impl;
  69     Impl * m_pImpl;
  70
  71 protected:
  72     virtual ~InteractionRequest();
  73 public:
  74     /**
  75       * Constructor.
  76       *
  77       * @param rRequest is the exception describing the error.
  78       */
  79     InteractionRequest( const com::sun::star::uno::Any & rRequest );
  80
  81     /**
  82       * This method sets the continuations for the request.
  83       *
  84       * @param rContinuations contains the possible continuations.
  85       */
  86     void setContinuations(
  87         const uno::Sequence< uno::Reference< task::XInteractionContinuation > > &
  88                     rContinuations );
  89
  90     // XInteractionRequest
  91     virtual uno::Any SAL_CALL
  92         getRequest()
  93             throw( uno::RuntimeException );
  94
  95     virtual uno::Sequence< uno::Reference< task::XInteractionContinuation > > SAL_CALL
  96         getContinuations()
  97             throw( com::sun::star::uno::RuntimeException );
  98
  99     // Non-interface methods.
 100
 101     /**
 102       * After passing this request to XInteractionHandler::handle, this method
 103       * returns the continuation that was choosen by the interaction handler.
 104       *
 105       * @return the continuation choosen by an interaction handler or an empty
 106       *         reference, if the request was not (yet) handled.
 107       */
 108     uno::Reference< task::XInteractionContinuation > getSelection() const;
 109
 110     /**
 111       * This method sets a continuation for the request. It also can be used
 112       * to reset the continuation set by a previous XInteractionHandler::handle
 113       * call in order to use this request object more then once.
 114       *
 115       * @param rxSelection is the interaction continuation to activate for
 116       *        the request or an empty reference in order to reset the
 117       *        current selection.
 118       */
 119     void setSelection(
 120         const uno::Reference< task::XInteractionContinuation > & rxSelection );
 121 };
 122
 123 //============================================================================
 124
 125 /**
 126   * This template class  implements a simple standard interaction continuation
 127   * interface provided as template parameter. Classes instantiated from this
 128   * template work together with class InteractionRequest.
 129   * Instances of such a class can be passed along with an interaction request
 130   * to indicate the possiblity to continue the operation that caused the request
 131   * as indicated by the interface.
 132   */
 133 template <class XThisContinuation >
 134 class InteractionContinuation   : public cppu::WeakImplHelper1< XThisContinuation >
 135 {
 136     InteractionRequest * m_pRequest;
 137 public:
 138     InteractionContinuation( InteractionRequest * pRequest )
 139     : m_pRequest( pRequest ) {}
 140
 141     // XInteractionContinuation
 142     /**
 143       * This method marks this continuation as "selected" at the request it
 144       * belongs to.
 145       *
 146       * Derived classes must implement their XInteractionContinuation::select()
 147       * method the way that they call this method.
 148       */
 149     virtual void SAL_CALL select()
 150         throw( com::sun::star::uno::RuntimeException );
 151 };
 152 //============================================================================
 153
 154 template <class XThisContinuation >
 155 void SAL_CALL InteractionContinuation< XThisContinuation >::select()
 156     throw( com::sun::star::uno::RuntimeException )
 157 {
 158     m_pRequest->setSelection(this);
 159 }
 160 //============================================================================
 161
 162
 163 } // namespace apihelper
 164 } // namespace configmgr
 165
 166 #endif /* !CONFIGMGR_INTERACTIONREQUEST_HXX */