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