/*
* ============================================================================
* Name : btnotifpairinghelper.h
* Part of : bluetoothengine / btnotif
* Description : Helper class for processing pairing requests and results, as extended functionality for CBTNotifConnection.
*
* Copyright © 2009 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
* Nokia Corporation
* ============================================================================
* Template version: 4.2
*/
#ifndef BTNOTIFPAIRINGHELPER_H
#define BTNOTIFPAIRINGHELPER_H
#include <e32base.h>
#include <btmanclient.h>
#include <bluetooth/pairing.h>
#include <btservices/btsimpleactive.h>
#include "bluetoothnotification.h"
#include "bluetoothtrace.h"
class CBTNotifConnection;
class CBTNotifConnectionTracker;
class CBTDevice;
/**
* Helper class for performing pairing-related operations.
*
* This class is constructed only when there is a pairing-related event,
* and destructed after completion. Pairing-related events are bonding
* (outgoing bonding request from an application), pairing notifiers
* (PIN input i.e. legacy pairing, numeric comparison and passkey display),
* and Just Works pairing completion.
*
* The structure of operations is as follows: each event is initiated through
* StartXxL() operation, and finished with CompleteXxL(), there is also a
* CancelXxL() operation where needed. In addition there are the base class virtual
* functions, a few helper functions and HandleAuthenticationCompleteL, which
* processes a baseband authentication result. The same structure applies to
* suboperations, such as StartTrustedQueryL and CompleteTrustedQueryL.
*
* For bonding, there is StartBondingL, CompleteBondingL() CancelBondingL();
* for pairing notifiers there is StartPairingNotifierL(),
* CancelPairingNotifierL(), CompletePairingNotifierL() and also
* UpdatePairingNotifierL(). For Just Works processing, there is
* StartJustWorksProcessingL(), CancelJustWorksProcessingL() and
* CompleteJustWorksProcessingL().
*
* The design of this class is focussed on structure and maintainability first.
* Duplicate (state) information is kept to a minimum. And memory usage comes
* before processing. Pairing is an infrequent operation, and this class is
* only instantiated when there is pairing-related processing, so extreme
* focus on memory or processing efficiency would have relatively little effect.
*
* @since Symbian^4
*/
NONSHARABLE_CLASS( CBTNotifPairingHelper ) : public CBase,
public MBTNotificationResult,
public MBtSimpleActiveObserver
{
public:
/** Enumeration identifying the stage of the pairing operation. */
enum TPairingOp
{
EIdle,
EAcceptPairing,
ELegacyPairing,
ESspPairing,
EJustWorksPairing,
EAutoPairing,
EPostPairingOperations, // Marks the queries and notes which follow
// the real pairing input from the user.
EDedicatedBonding,
EUnpairing,
EAwaitingPairingResult,
EShowPairingSuccess,
EShowPairingFailure,
EQueryTrust,
EBlocking,
EPairingCancelled
};
/**
* Two-phased constructor.
* @param aConnection Pointer to the parent.
* @param aDevice Pointer to information of the remote device.
* aParam aTracker Pointer to the connection tracker.
*/
static CBTNotifPairingHelper* NewL( CBTNotifConnection* aConnection,
CBTNotifConnectionTracker* aTracker );
/**
* Destructor.
*/
virtual ~CBTNotifPairingHelper();
/**
* Get the address of the remote device for this connection.
*
* @since Symbian^4
* @param aProfile The profile identifying the service.
*/
inline CBTNotifPairingHelper::TPairingOp CurrentOperation() const
{ return iOperation; }
/**
* The baseband authentication has completed, handle the result.
*
* @since Symbian^4
* @param aError The result of the authentication procedure.
*/
void HandleAuthenticationCompleteL( TInt aError );
/**
* Start a bonding operation with the remote device.
*
* @since Symbian^4
* @param aMessage The handle of the message from the client.
*/
void StartBondingL( TInt aHandle );
/**
* Cancel an ongoing bonding operation with the remote device.
*
* @since Symbian^4
*/
void CancelBondingL();
/**
* Handle a notifier request for pairing with the remote device
* of this connection.
*
* @since Symbian^4
* @param aUid The UID of the notifier for this pairing request.
* @param aParams The parameters for this request from the client.
*/
void StartPairingNotifierL( TInt aUid, const TDesC8& aParams );
/**
* Update an outstanding request for this connection.
*
* @since Symbian^4
* @param aUid The UID of the notifier for this update.
* @param aParams The updated parameters for this request from the client.
*/
void UpdatePairingNotifierL( TInt aUid, const TDesC8& aParams );
/**
* Cancel an outstanding request for this connection.
*
* @since Symbian^4
* @param aUid The UID of the notifier for this pairing request.
*/
void CancelPairingNotifierL( TInt aUid );
/**
* Start the processing of a completed Just Works pairing.
* This needs special attention, as this class is not notified
* other than by observing the registry, and the user is not
* notified otherwise either (which is the point of this association
* model). It needs to be verified that the pairing is related to
* a service access, as dedicated bonding should not be possible
* (for devices that do not have any IO capabilities).
*
* @since Symbian^4
* @param aMessage The handle of the message from the client.
*/
void StartJustWorksProcessingL();
/**
* Cancel the processing of a completed Just Works pairing.
*
* @since Symbian^4
*/
void CancelJustWorksProcessingL();
// from base class MBTNotificationResult
/**
* From MBTNotificationResult.
* Handle an intermediate result from a user query.
* This function is called if the user query passes information
* back before it has finished i.e. is dismissed. The final acceptance/
* denial of a query is passed back in MBRNotificationClosed.
*
* @since Symbian^4
* @param aData the returned data. The actual format
* is dependent on the actual notifier.
*/
virtual void MBRDataReceived( CHbSymbianVariantMap& aData );
/**
* From MBTNotificationResult.
* The notification is finished. The resulting data (e.g. user input or
* acceptance/denial of the query) is passed back here.
*
* @since Symbian^4
* @param aErr KErrNone or one of the system-wide error codes.
* @param aData the returned data. The actual format
* is dependent on the actual notifier.
*/
virtual void MBRNotificationClosed( TInt aError, const TDesC8& aData );
// from base class MBtSimpleActiveObserver
/**
* From MBtSimpleActiveObserver.
* Callback to notify that an outstanding request has completed.
*
* @since Symbian^4
* @param aActive The active object helper that completed this request.
* @param aStatus The status of the completed request.
*/
virtual void RequestCompletedL( CBtSimpleActive* aActive, TInt aStatus );
/**
* From MBtSimpleActiveObserver.
* Callback for handling cancelation of an outstanding request.
*
* @since Symbian^4
* @param aId The ID that identifies the outstanding request.
*/
virtual void CancelRequest( TInt aRequestId );
/**
* Callback to notify that an error has occurred in RunL.
*
* @param aActive Pointer to the active object that completed.
* @param aError The error occurred in RunL.
*/
virtual void HandleError( CBtSimpleActive* aActive, TInt aError );
private:
/**
* C++ default constructor.
*/
CBTNotifPairingHelper( CBTNotifConnection* aConnection,
CBTNotifConnectionTracker* aTracker );
/**
* Symbian 2nd-phase constructor.
*/
void ConstructL();
/**
* Process the user input and complete the outstanding pairing request.
*
* @since Symbian^4
* @param aError The result off the notification.
* @param aResult The user response; ETrue if the user accepted the query,
* otherwise EFalse.
* @param aData The data returned from the notification dialog.
*/
void CompletePairingNotifierL( TInt aError, TBool aResult, const TDesC8& aData );
/**
* Completes a bonding operation.
*
* @since Symbian^4
* @param aError The result of the bonding attempt.
*/
void CompleteBondingL( TInt aError );
/**
* Completes a bonding operation.
*
* @since Symbian^4
* @param aError The result of the bonding attempt.
*/
void CompleteJustWorksProcessingL( TInt aError );
/**
* Ask the user to allow incoming pairing.
*
* @since Symbian^4
*/
void StartAcceptPairingQueryL();
/**
* Process the user input and for accepting an incoming pairing and
* continue with the outstanding pairing request.
*
* @since Symbian^4
* @param aError The result of the notification.
* @param aResult The user response; ETrue if the user accepted the query,
* otherwise EFalse.
*/
void CompleteAcceptPairingQueryL( TInt aError, TBool aResult );
/**
* Ask the user to set the device as trusted.
*
* @since Symbian^4
* @param aData The data returned from the notification dialog.
*/
void StartTrustedQueryL();
/**
* Process the user input for setting the device as trusted.
*
* @since Symbian^4
* @param aError The result of the notification.
* @param aResult The user response; ETrue if the user accepted the query,
* otherwise EFalse.
*/
void CompleteTrustedQueryL( TInt aError, TBool aResult );
/**
* Parse the parameters of a request for pairing.
* This function also returns values to use for dialog config, and sets
* the operation state member variable (iOperation).
*
* @since Symbian^4
* @param aLocallyInitiated On return, will be set to ETrue if the pairing
* was initiated by us.
* @param aNumVal On return, this descriptor will contain a number to use in
* the pairing dialog. The meaning depends on the type of pairing.
* @param aDialogType On return, will contain the dialog type.
* @param aResourceId On return, will contain the resource id.
*/
void ParseNotifierReqParamsL( TBool& aLocallyInitiated, TDes& aNumVal,
TBluetoothDialogParams::TBTDialogType& aDialogType,
TBTDialogResourceId& aResourceId );
/**
* Parse the parameters of a request for pairing using pin query.
*
* @since Symbian^4
* @param aLocallyInitiated On return, will be set to ETrue if the pairing
* was initiated by us.
* @param aNumVal On return, this will contain the minimum passcode length.
*/
void ParsePinCodeReqParamsL( TBool& aLocallyInitiated, TUint& aNumVal );
/**
* Parse the parameters of a request for pairing using numeric comparison.
*
* @since Symbian^4
* @param aLocallyInitiated On return, will be set to ETrue if the pairing
* was initiated by us.
* @param aNumVal On return, this descriptor will contain the passkey to
* show to the user.
*/
void ParseNumericCompReqParamsL( TBool& aLocallyInitiated, TDes& aNumVal );
/**
* Parse the parameters of a request for pairing using passkey display.
*
* @since Symbian^4
* @param aLocallyInitiated On return, will be set to ETrue if the pairing
* was initiated by us.
* @param aNumVal On return, this descriptor will contain the passkey to
* show to the user.
*/
void ParsePasskeyDisplayReqParamsL( TBool& aLocallyInitiated, TDes& aNumVal );
/**
* Check if we can guess the PIN and complete the notifier without
* user interaction.
*
* @since Symbian^4
* @param aLocallyInitiated ETrue if we initiated the pairing, otherwise EFalse.
* @param aNumVal The minimum lenght of the passcode.
*/
void CheckAutoPairingL( TBool aLocallyInitiated, const TDesC& aNumVal );
/**
* Get a notification and configure it according to the current operation.
*
* @since Symbian^4
* @param aType The notification type.
* @param aResourceId Identifier for the resource to display.
*/
void PrepareNotificationL( TBluetoothDialogParams::TBTDialogType aType,
TBTDialogResourceId aResourceId );
/**
* Handle the result from a notification that is finished.
*
* @since Symbian^4
* @param aErr KErrNone or one of the system-wide error codes.
* @param aData The returned data. The actual format
* is dependent on the actual notifier.
*/
void NotificationClosedL( TInt aError, const TDesC8& aData );
private: // data
/**
* Identifier for the current operation.
*/
TPairingOp iOperation;
/**
* UID of the notifier pairing dialog request.
*/
TInt iNotifierUid;
/**
* Handle to the client message for dedicated bonding. Also serves as flag
* indicating that we are performing dedicated bonding.
*/
TInt iDedicatedBonding;
/**
* Subsession with pairing server for dedicated bonding.
*/
RBluetoothDedicatedBondingInitiator iBondingSession;
/**
* Handle for general bonding.
*/
RBTPhysicalLinkAdapter iBondingSocket;
/**
* Buffer containing the parameters of the client message.
* Own.
*/
HBufC8* iParams;
/**
* Active object helper for outgoing bonding.
* Own.
*/
CBtSimpleActive* iBondingActive;
/**
* Pointer to the data record of the remote device.
* Not own.
*/
CBTDevice* iDevice;
/**
* Pointer to an outstanding user interaction.
* Not own.
*/
CBluetoothNotification* iNotification;
/**
* Pointer to the class that we are helping.
* Not own.
*/
CBTNotifConnection* iConnection;
/**
* Pointer to our grandparent.
* Not own.
*/
CBTNotifConnectionTracker* iTracker;
BTUNITTESTHOOK
};
#endif // BTNOTIFPAIRINGHELPER_H