include/ucbhelper/interactionrequest.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_INTERACTIONREQUEST_HXX
  21 #define INCLUDED_UCBHELPER_INTERACTIONREQUEST_HXX
  22
  23 #include <com/sun/star/lang/XTypeProvider.hpp>
  24 #include <com/sun/star/task/XInteractionRequest.hpp>
  25 #include <com/sun/star/task/XInteractionAbort.hpp>
  26 #include <com/sun/star/task/XInteractionRetry.hpp>
  27 #include <com/sun/star/task/XInteractionApprove.hpp>
  28 #include <com/sun/star/task/XInteractionDisapprove.hpp>
  29 #include <com/sun/star/ucb/XInteractionAuthFallback.hpp>
  30 #include <com/sun/star/ucb/XInteractionReplaceExistingData.hpp>
  31 #include <com/sun/star/ucb/XInteractionSupplyAuthentication2.hpp>
  32 #include <cppuhelper/weak.hxx>
  33 #include <ucbhelper/ucbhelperdllapi.h>
  34 #include <memory>
  35
  36 namespace rtl { template <class reference_type> class Reference; }
  37
  38 namespace ucbhelper {
  39
  40 class InteractionContinuation;
  41
  42
  43 struct InteractionRequest_Impl;
  44
  45 /**
  46   * This class implements the interface XInteractionRequest. Instances can
  47   * be passed directly to XInteractionHandler::handle(...). Each interaction
  48   * request contains an exception describing the error and a number of
  49   * interaction continuations describing the possible "answers" for the request.
  50   * After the request was passed to XInteractionHandler::handle(...) the method
  51   * getSelection() returns the continuation chosen by the interaction handler.
  52   *
  53   * The typical usage of this class would be:
  54   *
  55   * 1) Create exception object that shall be handled by the interaction handler.
  56   * 2) Create InteractionRequest, supply exception as ctor parameter
  57   * 3) Create continuations needed and add them to a sequence
  58   * 4) Supply the continuations to the InteractionRequest by calling
  59   *    setContinuations(...)
  60   *
  61   * This class can also be used as base class for more specialized requests,
  62   * like authentication requests.
  63   */
  64 class UCBHELPER_DLLPUBLIC InteractionRequest : public cppu::OWeakObject,
  65                            public css::lang::XTypeProvider,
  66                            public css::task::XInteractionRequest
  67 {
  68     std::unique_ptr<InteractionRequest_Impl> m_pImpl;
  69
  70 protected:
  71     void setRequest( const css::uno::Any & rRequest );
  72
  73     InteractionRequest();
  74     virtual ~InteractionRequest() override;
  75
  76 public:
  77     /**
  78       * Constructor.
  79       *
  80       * @param rRequest is the exception describing the error.
  81       */
  82     InteractionRequest( const css::uno::Any & rRequest );
  83
  84     /**
  85       * This method sets the continuations for the request.
  86       *
  87       * @param rContinuations contains the possible continuations.
  88       */
  89     void setContinuations(
  90         const css::uno::Sequence< css::uno::Reference< css::task::XInteractionContinuation > > & rContinuations );
  91
  92     // XInterface
  93     virtual css::uno::Any SAL_CALL
  94     queryInterface( const css::uno::Type & rType ) override;
  95     virtual void SAL_CALL acquire()
  96         throw() override;
  97     virtual void SAL_CALL release()
  98         throw() override;
  99
 100     // XTypeProvider
 101     virtual css::uno::Sequence< css::uno::Type > SAL_CALL
 102     getTypes() override;
 103     virtual css::uno::Sequence< sal_Int8 > SAL_CALL
 104     getImplementationId() override;
 105
 106     // XInteractionRequest
 107     virtual css::uno::Any SAL_CALL
 108     getRequest() override;
 109     virtual css::uno::Sequence< css::uno::Reference< css::task::XInteractionContinuation > > SAL_CALL
 110     getContinuations() override;
 111
 112     // Non-interface methods.
 113
 114     /**
 115       * After passing this request to XInteractionHandler::handle, this method
 116       * returns the continuation that was chosen by the interaction handler.
 117       *
 118       * @return the continuation chosen by an interaction handler or an empty
 119       *         reference, if the request was not (yet) handled.
 120       */
 121     rtl::Reference< InteractionContinuation > const & getSelection() const;
 122
 123     /**
 124       * This method sets a continuation for the request. It also can be used
 125       * to reset the continuation set by a previous XInteractionHandler::handle
 126       * call in order to use this request object more than once.
 127       *
 128       * @param rxSelection is the interaction continuation to activate for
 129       *        the request or an empty reference in order to reset the
 130       *        current selection.
 131       */
 132     void
 133     setSelection(
 134         const rtl::Reference< InteractionContinuation > & rxSelection );
 135 };
 136
 137
 138 /**
 139   * This class is the base for implementations of the interface
 140   * XInteractionContinuation. Classes derived from this bas class work together
 141   * with class InteractionRequest.
 142   *
 143   * Derived classes must implement their XInteractionContinuation::select()
 144   * method the way that they simply call recordSelection() which is provided by
 145   * this class.
 146   */
 147 class UCBHELPER_DLLPUBLIC InteractionContinuation : public cppu::OWeakObject
 148 {
 149     InteractionRequest* m_pRequest;
 150
 151 protected:
 152     /**
 153       * This method marks this continuation as "selected" at the request it
 154       * belongs to.
 155       *
 156       * Derived classes must implement their XInteractionContinuation::select()
 157       * method the way that they call this method.
 158       */
 159     void recordSelection();
 160     virtual ~InteractionContinuation() override;
 161
 162 public:
 163     InteractionContinuation( InteractionRequest * pRequest );
 164 };
 165
 166
 167 /**
 168   * This class implements a standard interaction continuation, namely the
 169   * interface XInteractionAbort. Instances of this class can be passed
 170   * along with an interaction request to indicate the possibility to abort
 171   * the operation that caused the request.
 172   */
 173 class UCBHELPER_DLLPUBLIC InteractionAbort : public InteractionContinuation,
 174                          public css::lang::XTypeProvider,
 175                          public css::task::XInteractionAbort
 176 {
 177 public:
 178     InteractionAbort( InteractionRequest * pRequest )
 179     : InteractionContinuation( pRequest ) {}
 180
 181     // XInterface
 182     virtual css::uno::Any SAL_CALL
 183     queryInterface( const css::uno::Type & rType ) override;
 184     virtual void SAL_CALL acquire()
 185         throw() override;
 186     virtual void SAL_CALL release()
 187         throw() override;
 188
 189     // XTypeProvider
 190     virtual css::uno::Sequence< css::uno::Type > SAL_CALL
 191     getTypes() override;
 192     virtual css::uno::Sequence< sal_Int8 > SAL_CALL
 193     getImplementationId() override;
 194
 195     // XInteractionContinuation
 196     virtual void SAL_CALL select() override;
 197 };
 198
 199
 200 /**
 201   * This class implements a standard interaction continuation, namely the
 202   * interface XInteractionRetry. Instances of this class can be passed
 203   * along with an interaction request to indicate the possibility to retry
 204   * the operation that caused the request.
 205   */
 206 class UCBHELPER_DLLPUBLIC InteractionRetry : public InteractionContinuation,
 207                          public css::lang::XTypeProvider,
 208                          public css::task::XInteractionRetry
 209 {
 210 public:
 211     InteractionRetry( InteractionRequest * pRequest )
 212     : InteractionContinuation( pRequest ) {}
 213
 214     // XInterface
 215     virtual css::uno::Any SAL_CALL
 216     queryInterface( const css::uno::Type & rType ) override;
 217     virtual void SAL_CALL acquire()
 218         throw() override;
 219     virtual void SAL_CALL release()
 220         throw() override;
 221
 222     // XTypeProvider
 223     virtual css::uno::Sequence< css::uno::Type > SAL_CALL
 224     getTypes() override;
 225     virtual css::uno::Sequence< sal_Int8 > SAL_CALL
 226     getImplementationId() override;
 227
 228     // XInteractionContinuation
 229     virtual void SAL_CALL select() override;
 230 };
 231
 232
 233 /**
 234   * This class implements a standard interaction continuation, namely the
 235   * interface XInteractionApprove. Instances of this class can be passed
 236   * along with an interaction request to indicate the possibility to approve
 237   * the request.
 238   */
 239 class UCBHELPER_DLLPUBLIC InteractionApprove : public InteractionContinuation,
 240                            public css::lang::XTypeProvider,
 241                            public css::task::XInteractionApprove
 242 {
 243 public:
 244     InteractionApprove( InteractionRequest * pRequest )
 245     : InteractionContinuation( pRequest ) {}
 246
 247     // XInterface
 248     virtual css::uno::Any SAL_CALL
 249     queryInterface( const css::uno::Type & rType ) override;
 250     virtual void SAL_CALL acquire()
 251         throw() override;
 252     virtual void SAL_CALL release()
 253         throw() override;
 254
 255     // XTypeProvider
 256     virtual css::uno::Sequence< css::uno::Type > SAL_CALL
 257     getTypes() override;
 258     virtual css::uno::Sequence< sal_Int8 > SAL_CALL
 259     getImplementationId() override;
 260
 261     // XInteractionContinuation
 262     virtual void SAL_CALL select() override;
 263 };
 264
 265
 266 /**
 267   * This class implements a standard interaction continuation, namely the
 268   * interface XInteractionDisapprove. Instances of this class can be passed
 269   * along with an interaction request to indicate the possibility to disapprove
 270   * the request.
 271   */
 272 class UCBHELPER_DLLPUBLIC InteractionDisapprove : public InteractionContinuation,
 273                               public css::lang::XTypeProvider,
 274                               public css::task::XInteractionDisapprove
 275 {
 276 public:
 277     InteractionDisapprove( InteractionRequest * pRequest )
 278     : InteractionContinuation( pRequest ) {}
 279
 280     // XInterface
 281     virtual css::uno::Any SAL_CALL
 282     queryInterface( const css::uno::Type & rType ) override;
 283     virtual void SAL_CALL acquire()
 284         throw() override;
 285     virtual void SAL_CALL release()
 286         throw() override;
 287
 288     // XTypeProvider
 289     virtual css::uno::Sequence< css::uno::Type > SAL_CALL
 290     getTypes() override;
 291     virtual css::uno::Sequence< sal_Int8 > SAL_CALL
 292     getImplementationId() override;
 293
 294     // XInteractionContinuation
 295     virtual void SAL_CALL select() override;
 296 };
 297
 298
 299 /**
 300   * This class implements a standard interaction continuation, namely the
 301   * interface XInteractionSupplyAuthentication. Instances of this class can be
 302   * passed along with an authentication interaction request to enable the
 303   * interaction handler to supply the missing authentication data.
 304   */
 305 class UCBHELPER_DLLPUBLIC InteractionSupplyAuthentication :
 306                   public InteractionContinuation,
 307                   public css::lang::XTypeProvider,
 308                   public css::ucb::XInteractionSupplyAuthentication2
 309 {
 310     css::uno::Sequence< css::ucb::RememberAuthentication > const
 311                   m_aRememberPasswordModes;
 312     css::uno::Sequence< css::ucb::RememberAuthentication > const
 313                   m_aRememberAccountModes;
 314     OUString m_aRealm;
 315     OUString m_aUserName;
 316     OUString m_aPassword;
 317     css::ucb::RememberAuthentication m_eRememberPasswordMode;
 318     css::ucb::RememberAuthentication const m_eDefaultRememberPasswordMode;
 319     css::ucb::RememberAuthentication const m_eDefaultRememberAccountMode;
 320     bool const m_bCanSetRealm    : 1;
 321     bool const m_bCanSetUserName : 1;
 322     bool const m_bCanSetPassword : 1;
 323     bool const m_bCanSetAccount  : 1;
 324     bool const m_bCanUseSystemCredentials     : 1;
 325     bool m_bUseSystemCredentials        : 1;
 326
 327 public:
 328     /**
 329       * Constructor.
 330       *
 331       * Note: The remember-authentication stuff is interesting only for
 332       *       clients implementing own password storage functionality.
 333       *
 334       * @param rxRequest is the interaction request that owns this continuation.
 335       * @param bCanSetRealm indicates, whether the realm given with the
 336       *        authentication request is read-only.
 337       * @param bCanSetUserName indicates, whether the username given with the
 338       *        authentication request is read-only.
 339       * @param bCanSetPassword indicates, whether the password given with the
 340       *        authentication request is read-only.
 341       * @param bCanSetAccount indicates, whether the account given with the
 342       *        authentication request is read-only.
 343       * @param rRememberPasswordModes specifies the authentication-remember-
 344       *        modes for passwords supported by the requesting client.
 345       * @param eDefaultRememberPasswordMode specifies the default
 346       *        authentication-remember-mode for passwords preferred by the
 347       *        requesting client.
 348       * @param rRememberAccountModes specifies the authentication-remember-
 349       *        modes for accounts supported by the requesting client.
 350       * @param eDefaultRememberAccountMode specifies the default
 351       *        authentication-remember-mode for accounts preferred by the
 352       *        requesting client.
 353       * @param bCanUseSystemCredentials indicates whether issuer of the
 354       *        authentication request can obtain and use system credentials
 355       *        for authentication.
 356       *
 357       * @see css::ucb::AuthenticationRequest
 358       * @see css::ucb::RememberAuthentication
 359       */
 360     inline InteractionSupplyAuthentication(
 361                     InteractionRequest * pRequest,
 362                     bool bCanSetRealm,
 363                     bool bCanSetUserName,
 364                     bool bCanSetPassword,
 365                     bool bCanSetAccount,
 366                     const css::uno::Sequence< css::ucb::RememberAuthentication > & rRememberPasswordModes,
 367                     const css::ucb::RememberAuthentication eDefaultRememberPasswordMode,
 368                     const css::uno::Sequence< css::ucb::RememberAuthentication > & rRememberAccountModes,
 369                     const css::ucb::RememberAuthentication  eDefaultRememberAccountMode,
 370                     bool bCanUseSystemCredentials );
 371
 372     // XInterface
 373     virtual css::uno::Any SAL_CALL
 374     queryInterface( const css::uno::Type & rType ) override;
 375     virtual void SAL_CALL acquire()
 376         throw() override;
 377     virtual void SAL_CALL release()
 378         throw() override;
 379
 380     // XTypeProvider
 381     virtual css::uno::Sequence< css::uno::Type > SAL_CALL
 382     getTypes() override;
 383     virtual css::uno::Sequence< sal_Int8 > SAL_CALL
 384     getImplementationId() override;
 385
 386     // XInteractionContinuation
 387     virtual void SAL_CALL select() override;
 388
 389     // XInteractionSupplyAuthentication
 390     virtual sal_Bool SAL_CALL
 391     canSetRealm() override;
 392     virtual void SAL_CALL
 393     setRealm( const OUString& Realm ) override;
 394
 395     virtual sal_Bool SAL_CALL
 396     canSetUserName() override;
 397     virtual void SAL_CALL
 398     setUserName( const OUString& UserName ) override;
 399
 400     virtual sal_Bool SAL_CALL
 401     canSetPassword() override;
 402     virtual void SAL_CALL
 403     setPassword( const OUString& Password ) override;
 404
 405     virtual css::uno::Sequence<
 406                 css::ucb::RememberAuthentication > SAL_CALL
 407     getRememberPasswordModes(
 408             css::ucb::RememberAuthentication& Default ) override;
 409     virtual void SAL_CALL
 410     setRememberPassword( css::ucb::RememberAuthentication Remember ) override;
 411
 412     virtual sal_Bool SAL_CALL
 413     canSetAccount() override;
 414     virtual void SAL_CALL
 415     setAccount( const OUString& Account ) override;
 416
 417     virtual css::uno::Sequence< css::ucb::RememberAuthentication > SAL_CALL
 418     getRememberAccountModes(
 419             css::ucb::RememberAuthentication& Default ) override;
 420     virtual void SAL_CALL
 421     setRememberAccount( css::ucb::RememberAuthentication Remember ) override;
 422
 423     // XInteractionSupplyAuthentication2
 424     virtual sal_Bool SAL_CALL canUseSystemCredentials( sal_Bool& Default ) override;
 425     virtual void SAL_CALL setUseSystemCredentials( sal_Bool UseSystemCredentials ) override;
 426
 427     // Non-interface methods.
 428
 429     /**
 430       * This method returns the realm that was supplied by the interaction
 431       * handler.
 432       *
 433       * @return the realm.
 434       */
 435     const OUString & getRealm()    const { return m_aRealm; }
 436
 437     /**
 438       * This method returns the username that was supplied by the interaction
 439       * handler.
 440       *
 441       * @return the username.
 442       */
 443     const OUString & getUserName() const { return m_aUserName; }
 444
 445     /**
 446       * This method returns the password that was supplied by the interaction
 447       * handler.
 448       *
 449       * @return the password.
 450       */
 451     const OUString & getPassword() const { return m_aPassword; }
 452
 453     /**
 454       * This method returns the authentication remember-mode for the password
 455       * that was supplied by the interaction handler.
 456       *
 457       * @return the remember-mode for the password.
 458       */
 459     const css::ucb::RememberAuthentication &
 460     getRememberPasswordMode() const { return m_eRememberPasswordMode; }
 461
 462     bool getUseSystemCredentials() const { return m_bUseSystemCredentials; }
 463 };
 464
 465
 466
 467 inline InteractionSupplyAuthentication::InteractionSupplyAuthentication(
 468     InteractionRequest * pRequest,
 469     bool bCanSetRealm,
 470     bool bCanSetUserName,
 471     bool bCanSetPassword,
 472     bool bCanSetAccount,
 473     const css::uno::Sequence< css::ucb::RememberAuthentication > & rRememberPasswordModes,
 474     const css::ucb::RememberAuthentication eDefaultRememberPasswordMode,
 475     const css::uno::Sequence< css::ucb::RememberAuthentication > & rRememberAccountModes,
 476     const css::ucb::RememberAuthentication eDefaultRememberAccountMode,
 477     bool bCanUseSystemCredentials )
 478 : InteractionContinuation( pRequest ),
 479   m_aRememberPasswordModes( rRememberPasswordModes ),
 480   m_aRememberAccountModes( rRememberAccountModes ),
 481   m_eRememberPasswordMode( eDefaultRememberPasswordMode ),
 482   m_eDefaultRememberPasswordMode( eDefaultRememberPasswordMode ),
 483   m_eDefaultRememberAccountMode( eDefaultRememberAccountMode ),
 484   m_bCanSetRealm( bCanSetRealm ),
 485   m_bCanSetUserName( bCanSetUserName ),
 486   m_bCanSetPassword( bCanSetPassword ),
 487   m_bCanSetAccount( bCanSetAccount ),
 488   m_bCanUseSystemCredentials( bCanUseSystemCredentials ),
 489   m_bUseSystemCredentials( false )
 490 {
 491 }
 492
 493
 494 /**
 495   * This class implements a standard interaction continuation, namely the
 496   * interface XInteractionReplaceExistingData. Instances of this class can be
 497   * passed along with an interaction request to indicate the possibility to
 498   * replace existing data.
 499   */
 500 class InteractionReplaceExistingData :
 501                   public InteractionContinuation,
 502                   public css::lang::XTypeProvider,
 503                   public css::ucb::XInteractionReplaceExistingData
 504 {
 505 public:
 506     InteractionReplaceExistingData( InteractionRequest * pRequest )
 507     : InteractionContinuation( pRequest ) {}
 508
 509     // XInterface
 510     virtual css::uno::Any SAL_CALL
 511     queryInterface( const css::uno::Type & rType ) override;
 512     virtual void SAL_CALL acquire()
 513         throw() override;
 514     virtual void SAL_CALL release()
 515         throw() override;
 516
 517     // XTypeProvider
 518     virtual css::uno::Sequence< css::uno::Type > SAL_CALL
 519     getTypes() override;
 520     virtual css::uno::Sequence< sal_Int8 > SAL_CALL
 521     getImplementationId() override;
 522
 523     // XInteractionContinuation
 524     virtual void SAL_CALL select() override;
 525 };
 526
 527 class UCBHELPER_DLLPUBLIC InteractionAuthFallback:
 528                   public InteractionContinuation,
 529                   public css::ucb::XInteractionAuthFallback
 530 {
 531     OUString m_aCode;
 532
 533 public:
 534     InteractionAuthFallback( InteractionRequest * pRequest )
 535     : InteractionContinuation( pRequest ) {}
 536
 537     // XInterface
 538     virtual css::uno::Any SAL_CALL
 539     queryInterface( const css::uno::Type & rType ) override;
 540     virtual void SAL_CALL acquire()
 541         throw() override;
 542     virtual void SAL_CALL release()
 543         throw() override;
 544
 545     // XInteractionContinuation
 546     virtual void SAL_CALL select() override;
 547
 548     // XAuthFallback
 549     virtual void SAL_CALL setCode( const OUString& code ) override;
 550     /// @throws css::uno::RuntimeException
 551     const OUString& getCode() const;
 552
 553
 554 };
 555
 556
 557 } // namespace ucbhelper
 558
 559 #endif /* ! INCLUDED_UCBHELPER_INTERACTIONREQUEST_HXX */
 560
 561 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */