1 /*

     2 * ============================================================================

     3 *  Name        : btnotifpairinghelper.h

     4 *  Part of     : bluetoothengine / btnotif

     5 *  Description : Helper class for processing pairing requests and results, as extended functionality for CBTNotifConnection.

     6 *

     7 *  Copyright © 2009 Nokia Corporation and/or its subsidiary(-ies).

     8 *  All rights reserved.

     9 *  This component and the accompanying materials are made available

    10 *  under the terms of "Eclipse Public License v1.0"

    11 *  which accompanies this distribution, and is available

    12 *  at the URL "http://www.eclipse.org/legal/epl-v10.html".

    13 *

    14 *  Initial Contributors:

    15 *  Nokia Corporation - initial contribution.

    16 *

    17 *  Contributors:

    18 *  Nokia Corporation

    19 * ============================================================================

    20 * Template version: 4.2

    21 */

    22 

    23 #ifndef BTNOTIFPAIRINGHELPER_H

    24 #define BTNOTIFPAIRINGHELPER_H

    25 

    26 #include <e32base.h>

    27 #include <btmanclient.h>

    28 #include <bluetooth/pairing.h>

    29 #include <btservices/btsimpleactive.h>

    30 

    31 #include "bluetoothnotification.h"

    32 #include "bluetoothtrace.h"

    33 

    34 class CBTNotifConnection;

    35 class CBTNotifConnectionTracker;

    36 class CBTDevice;

    37 

    38 

    39 /**

    40  *  Helper class for performing pairing-related operations.

    41  *  

    42  *  This class is constructed only when there is a pairing-related event,

    43  *  and destructed after completion. Pairing-related events are bonding

    44  *  (outgoing bonding request from an application), pairing notifiers

    45  *  (PIN input i.e. legacy pairing, numeric comparison and passkey display),

    46  *  and Just Works pairing completion.

    47  *  

    48  *  The structure of operations is as follows: each event is initiated through

    49  *  StartXxL() operation, and finished with CompleteXxL(), there is also a

    50  *  CancelXxL() operation where needed. In addition there are the base class virtual

    51  *  functions, a few helper functions and HandleAuthenticationCompleteL, which

    52  *  processes a baseband authentication result. The same structure applies to

    53  *  suboperations, such as StartTrustedQueryL and CompleteTrustedQueryL.

    54  *  

    55  *  For bonding, there is StartBondingL, CompleteBondingL() CancelBondingL();

    56  *  for pairing notifiers there is StartPairingNotifierL(),

    57  *  CancelPairingNotifierL(), CompletePairingNotifierL() and also

    58  *  UpdatePairingNotifierL(). For Just Works processing, there is

    59  *  StartJustWorksProcessingL(), CancelJustWorksProcessingL() and

    60  *  CompleteJustWorksProcessingL().

    61  *  

    62  *  The design of this class is focussed on structure and maintainability first.

    63  *  Duplicate (state) information is kept to a minimum. And memory usage comes

    64  *  before processing. Pairing is an infrequent operation, and this class is

    65  *  only instantiated when there is pairing-related processing, so extreme

    66  *  focus on memory or processing efficiency would have relatively little effect.

    67  *  

    68  *  @since Symbian^4

    69  */

    70 NONSHARABLE_CLASS( CBTNotifPairingHelper ) : public CBase,

    71                                              public MBTNotificationResult,

    72                                              public MBtSimpleActiveObserver

    73     {

    74 

    75 public:

    76 

    77     /**  Enumeration identifying the stage of the pairing operation. */

    78     enum TPairingOp

    79         {

    80         EIdle,

    81         EAcceptPairing,

    82         ELegacyPairing,

    83         ESspPairing,

    84         EJustWorksPairing,

    85         EAutoPairing,

    86         EPostPairingOperations, // Marks the queries and notes which follow

    87                                 // the real pairing input from the user.

    88         EDedicatedBonding,

    89         EUnpairing,

    90         EAwaitingPairingResult,

    91         EShowPairingSuccess,

    92         EShowPairingFailure,

    93         EQueryTrust,

    94         EBlocking,

    95         EPairingCancelled

    96         };

    97 

    98     /**

    99      * Two-phased constructor.

   100      * @param aConnection Pointer to the parent.

   101      * @param aDevice Pointer to information of the remote device.

   102      * aParam aTracker Pointer to the connection tracker.

   103      */

   104     static CBTNotifPairingHelper* NewL( CBTNotifConnection* aConnection, 

   105                 CBTNotifConnectionTracker* aTracker );

   106 

   107     /**

   108     * Destructor.

   109     */

   110     virtual ~CBTNotifPairingHelper();

   111 

   112     /**

   113      * Get the address of the remote device for this connection.

   114      *

   115      * @since Symbian^4

   116      * @param aProfile The profile identifying the service.

   117      */

   118     inline CBTNotifPairingHelper::TPairingOp CurrentOperation() const

   119         { return iOperation; }

   120 

   121     /**

   122      * The baseband authentication has completed, handle the result.

   123      *

   124      * @since Symbian^4

   125      * @param aError The result of the authentication procedure.

   126      */    

   127     void HandleAuthenticationCompleteL( TInt aError );

   128 

   129     /**

   130      * Start a bonding operation with the remote device.

   131      *

   132      * @since Symbian^4

   133      * @param aMessage The handle of the message from the client.

   134      */

   135     void StartBondingL( TInt aHandle );

   136 

   137     /**

   138      * Cancel an ongoing bonding operation with the remote device.

   139      *

   140      * @since Symbian^4

   141      */

   142     void CancelBondingL();

   143 

   144     /**

   145      * Handle a notifier request for pairing with the remote device

   146      * of this connection.

   147      *

   148      * @since Symbian^4

   149      * @param aUid The UID of the notifier for this pairing request.

   150      * @param aParams The parameters for this request from the client.

   151      */    

   152     void StartPairingNotifierL( TInt aUid, const TDesC8& aParams );

   153 

   154     /**

   155      * Update an outstanding request for this connection.

   156      *  

   157      * @since Symbian^4

   158      * @param aUid The UID of the notifier for this update.

   159      * @param aParams The updated parameters for this request from the client.

   160      */

   161     void UpdatePairingNotifierL( TInt aUid, const TDesC8& aParams );

   162 

   163     /**

   164      * Cancel an outstanding request for this connection.

   165      *  

   166      * @since Symbian^4

   167      * @param aUid The UID of the notifier for this pairing request.

   168      */

   169     void CancelPairingNotifierL( TInt aUid );

   170 

   171     /**

   172      * Start the processing of a completed Just Works pairing.

   173      * This needs special attention, as this class is not notified

   174      * other than by observing the registry, and the user is not

   175      * notified otherwise either (which is the point of this association

   176      * model). It needs to be verified that the pairing is related to

   177      * a service access, as dedicated bonding should not be possible

   178      * (for devices that do not have any IO capabilities).

   179      *

   180      * @since Symbian^4

   181      * @param aMessage The handle of the message from the client.

   182      */

   183     void StartJustWorksProcessingL();

   184 

   185     /**

   186      * Cancel the processing of a completed Just Works pairing.

   187      *

   188      * @since Symbian^4

   189      */

   190     void CancelJustWorksProcessingL();

   191 

   192 // from base class MBTNotificationResult

   193 

   194     /**

   195      * From MBTNotificationResult.

   196      * Handle an intermediate result from a user query.

   197      * This function is called if the user query passes information

   198      * back before it has finished i.e. is dismissed. The final acceptance/

   199      * denial of a query is passed back in MBRNotificationClosed.

   200      *

   201      * @since Symbian^4

   202      * @param aData the returned data. The actual format 

   203      *              is dependent on the actual notifier.

   204      */

   205     virtual void MBRDataReceived( CHbSymbianVariantMap& aData );

   206 

   207     /**

   208      * From MBTNotificationResult.

   209      * The notification is finished. The resulting data (e.g. user input or

   210      * acceptance/denial of the query) is passed back here.

   211      *

   212      * @since Symbian^4

   213      * @param aErr KErrNone or one of the system-wide error codes.

   214      * @param aData the returned data. The actual format 

   215      *              is dependent on the actual notifier.

   216      */

   217     virtual void MBRNotificationClosed( TInt aError, const TDesC8& aData );

   218 

   219 // from base class MBtSimpleActiveObserver

   220 

   221     /**

   222      * From MBtSimpleActiveObserver.

   223      * Callback to notify that an outstanding request has completed.

   224      *

   225      * @since Symbian^4

   226      * @param aActive The active object helper that completed this request.

   227      * @param aStatus The status of the completed request.

   228      */

   229     virtual void RequestCompletedL( CBtSimpleActive* aActive, TInt aStatus );

   230 

   231     /**

   232      * From MBtSimpleActiveObserver.

   233      * Callback for handling cancelation of an outstanding request.

   234      *

   235      * @since Symbian^4

   236      * @param aId The ID that identifies the outstanding request.

   237      */

   238     virtual void CancelRequest( TInt aRequestId );

   239 

   240     /**

   241      * Callback to notify that an error has occurred in RunL.

   242      *

   243      * @param aActive Pointer to the active object that completed.

   244      * @param aError The error occurred in RunL.

   245      */

   246     virtual void HandleError( CBtSimpleActive* aActive, TInt aError );

   247     

   248 private:

   249 

   250     /**

   251      * C++ default constructor.

   252      */

   253     CBTNotifPairingHelper( CBTNotifConnection* aConnection,

   254                 CBTNotifConnectionTracker* aTracker );

   255 

   256     /**

   257      * Symbian 2nd-phase constructor.

   258      */

   259     void ConstructL();

   260 

   261     /**

   262      * Process the user input and complete the outstanding pairing request.

   263      *

   264      * @since Symbian^4

   265      * @param aError The result off the notification.

   266      * @param aResult The user response; ETrue if the user accepted the query,

   267      *                otherwise EFalse.

   268      * @param aData The data returned from the notification dialog.

   269      */

   270     void CompletePairingNotifierL( TInt aError, TBool aResult, const TDesC8& aData );

   271 

   272     /**

   273      * Completes a bonding operation.

   274      *

   275      * @since Symbian^4

   276      * @param aError The result of the bonding attempt.

   277      */

   278     void CompleteBondingL( TInt aError );

   279 

   280     /**

   281      * Completes a bonding operation.

   282      *

   283      * @since Symbian^4

   284      * @param aError The result of the bonding attempt.

   285      */

   286     void CompleteJustWorksProcessingL( TInt aError );

   287 

   288     /**

   289      * Ask the user to allow incoming pairing.

   290      *

   291      * @since Symbian^4

   292      */

   293     void StartAcceptPairingQueryL();

   294 

   295     /**

   296      * Process the user input and for accepting an incoming pairing and

   297      * continue with the outstanding pairing request.

   298      *

   299      * @since Symbian^4

   300      * @param aError The result of the notification.

   301      * @param aResult The user response; ETrue if the user accepted the query,

   302      *                otherwise EFalse.

   303      */

   304     void CompleteAcceptPairingQueryL( TInt aError, TBool aResult );

   305 

   306     /**

   307      * Ask the user to set the device as trusted.

   308      *

   309      * @since Symbian^4

   310      * @param aData The data returned from the notification dialog.

   311      */

   312     void StartTrustedQueryL();

   313 

   314     /**

   315      * Process the user input for setting the device as trusted.

   316      *

   317      * @since Symbian^4

   318      * @param aError The result of the notification.

   319      * @param aResult The user response; ETrue if the user accepted the query,

   320      *                otherwise EFalse.

   321      */

   322     void CompleteTrustedQueryL( TInt aError, TBool aResult );

   323 

   324     /**

   325      * Parse the parameters of a request for pairing.

   326      * This function also returns values to use for dialog config, and sets

   327      * the operation state member variable (iOperation).

   328      *

   329      * @since Symbian^4

   330      * @param aLocallyInitiated On return, will be set to ETrue if the pairing 

   331      *                          was initiated by us.

   332      * @param aNumVal On return, this descriptor will contain a number to use in

   333      *                the pairing dialog. The meaning depends on the type of pairing.

   334      * @param aDialogType On return, will contain the dialog type.

   335      * @param aResourceId On return, will contain the resource id.

   336      */

   337     void ParseNotifierReqParamsL( TBool& aLocallyInitiated, TDes& aNumVal,

   338                 TBluetoothDialogParams::TBTDialogType& aDialogType,

   339                 TBTDialogResourceId& aResourceId );

   340 

   341     /**

   342      * Parse the parameters of a request for pairing using pin query.

   343      *

   344      * @since Symbian^4

   345      * @param aLocallyInitiated On return, will be set to ETrue if the pairing 

   346      *                          was initiated by us.

   347      * @param aNumVal On return, this will contain the minimum passcode length.

   348      */

   349     void ParsePinCodeReqParamsL( TBool& aLocallyInitiated, TUint& aNumVal );

   350 

   351     /**

   352      * Parse the parameters of a request for pairing using numeric comparison.

   353      *

   354      * @since Symbian^4

   355      * @param aLocallyInitiated On return, will be set to ETrue if the pairing 

   356      *                          was initiated by us.

   357      * @param aNumVal On return, this descriptor will contain the passkey to 

   358      *                show to the user.

   359      */

   360     void ParseNumericCompReqParamsL( TBool& aLocallyInitiated, TDes& aNumVal );

   361 

   362     /**

   363      * Parse the parameters of a request for pairing using passkey display.

   364      *

   365      * @since Symbian^4

   366      * @param aLocallyInitiated On return, will be set to ETrue if the pairing 

   367      *                          was initiated by us.

   368      * @param aNumVal On return, this descriptor will contain the passkey to 

   369      *                show to the user.

   370      */

   371     void ParsePasskeyDisplayReqParamsL( TBool& aLocallyInitiated, TDes& aNumVal );

   372 

   373     /**

   374      * Check if we can guess the PIN and complete the notifier without 

   375      * user interaction.

   376      *

   377      * @since Symbian^4

   378      * @param aLocallyInitiated ETrue if we initiated the pairing, otherwise EFalse.

   379      * @param aNumVal The minimum lenght of the passcode.

   380      */

   381     void CheckAutoPairingL( TBool aLocallyInitiated, const TDesC& aNumVal );

   382 

   383     /**

   384      * Get a notification and configure it according to the current operation.

   385      *

   386      * @since Symbian^4

   387      * @param aType The notification type.

   388      * @param aResourceId Identifier for the resource to display.

   389      */

   390     void PrepareNotificationL( TBluetoothDialogParams::TBTDialogType aType,

   391                 TBTDialogResourceId aResourceId );

   392 

   393     /**

   394      * Handle the result from a notification that is finished.

   395      *

   396      * @since Symbian^4

   397      * @param aErr KErrNone or one of the system-wide error codes.

   398      * @param aData The returned data. The actual format 

   399      *              is dependent on the actual notifier.

   400      */

   401     void NotificationClosedL( TInt aError, const TDesC8& aData );

   402 

   403 private: // data

   404 

   405     /**

   406      * Identifier for the current operation.

   407      */

   408     TPairingOp iOperation;

   409 

   410     /**

   411      * UID of the notifier pairing dialog request.

   412      */

   413     TInt iNotifierUid;

   414 

   415     /**

   416      * Handle to the client message for dedicated bonding. Also serves as flag 

   417      * indicating that we are performing dedicated bonding.

   418      */

   419     TInt iDedicatedBonding;

   420 

   421     /**

   422      * Subsession with pairing server for dedicated bonding.

   423      */

   424     RBluetoothDedicatedBondingInitiator iBondingSession;

   425 

   426     /**

   427      * Handle for general bonding.

   428      */

   429     RBTPhysicalLinkAdapter iBondingSocket;

   430 

   431     /**

   432      * Buffer containing the parameters of the client message.

   433      * Own.

   434      */

   435     HBufC8* iParams;

   436 

   437     /**

   438      * Active object helper for outgoing bonding.

   439      * Own.

   440      */

   441     CBtSimpleActive* iBondingActive;

   442 

   443     /**

   444      * Pointer to the data record of the remote device.

   445      * Not own.

   446      */

   447     CBTDevice* iDevice;

   448 

   449     /**

   450      * Pointer to an outstanding user interaction.

   451      * Not own.

   452      */

   453     CBluetoothNotification* iNotification;

   454 

   455     /**

   456      * Pointer to the class that we are helping.

   457      * Not own.

   458      */

   459     CBTNotifConnection* iConnection;

   460 

   461     /**

   462      * Pointer to our grandparent.

   463      * Not own.

   464      */

   465     CBTNotifConnectionTracker* iTracker;

   466 

   467     BTUNITTESTHOOK

   468 

   469     };

   470 

   471 #endif // BTNOTIFPAIRINGHELPER_H