/*
* Copyright (c) 2007 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:
*
* Description:  Key pattern matching component.
 *
*/


#ifndef __LOCKAPPKEYPATTERN__
#define __LOCKAPPKEYPATTERN__

// INCLUDES
#include <w32std.h>
#include <e32base.h>

enum TPatternState
    {
    EPatternNotInitialized = 1,
    EPatternNotEnabled,
    EPatternNoMatch,
    EPatternPrimaryMatch,
    EPatternSecondaryMatch,
    };

/**
 *  CLockAppKeyPattern class implements a 2-key pattern matcher. 
 *  Can be used for both iCodes and iScancodes, as it matches integer numbers. 
 *  The caller's responsability is to make sense what is beeing matched. 
 *  Multiple patterns can be defined.
 *
 *  @lib    lockapp
 *  @since  5.0
 *  @author Tamas Koteles
 */
class CLockAppKeyPattern : public CBase
    {
    public:

        /**
         * Two phased constructor.
         */
        static CLockAppKeyPattern* NewL( );

        /**
         * Destructor.
         */
        ~CLockAppKeyPattern( );

        /**
         * If no patterns have been defined it cannot be used.
         * @return ETrue if has succesfully loaded policy
         */
        TBool HasPatterns( );

        /**
         * Gets the enabled state.
         *
         * @return true if the patterns are enabled, false othewise
         */
        TBool IsEnabled( );

        /**
         * Sets the enabled state.
         */
        void SetEnabled( TBool aEnabled );

        /**
         * Gets the primary key timeout.
         *
         * @return the timeout in miliseconds
         */
        TUint GetKeyTimeOut( );

        /**
         * Sets the primary key timeout.
         *
         */
        void SetKeyTimeOut( TUint aTimeOut );

        /**
         * Adds a key combination.
         *
         * @param aPrimaryKey code for primary key
         * @param aSecondaryKey code for secondary key
         * @return standard Symbian error code
         */
        TInt AddPattern( TUint32 aPrimaryKey, TUint32 aSecondaryKey );

        /**
         * Gets a key combination.
         *
         * @param aIndex index of the key combination
         * @param aPrimaryKey primary key code if found
         * @param aSecondaryKey secondary key code if found
         * @return standard Symbian error code
         */
        TInt GetPattern( TInt aIndex, TUint32& aPrimaryKey, TUint32& aSecondaryKey );

        /**
         * Clears all the defined key combinations.
         *
         * @return standard Symbian error code
         */
        TInt ClearPatterns( );

        /**
         * Handles Key events. Result of the event is returned in the pattern state.
         *
         * @param aKey the actual key event (code or scancode)
         * @return TPatternState caused by the event.
         */
        TPatternState HandleKeyEvent( TUint32 aKey );

    protected:

        /**
         * C++ default constructor (private so cannot be derived).
         */
        CLockAppKeyPattern( );

        /**
         * Second constructor initializes the policy
         */
        void ConstructL( );

    private:

        /**
         * A primary key has been received, set primary-match state.
         */
        void HandlePrimaryKeyEvent( TUint32 aKey );

        /**
         * A secondary key has been received, set secondary-match state.
         */
        void HandleSecondaryKeyEvent( );

        /**
         * Any other key has been received, set no-match state.
         */
        void HandleOtherKeyEvent( );

        /**
         * A call back to the keylock timer
         * param TAny aSelf a pointer to the parent class
         */
        static TInt HandleKeyTimerTimeout( TAny* aSelf );

    private:

        // defined configurations
        RArray<TUint> iPrimaryKeys;
        RArray<TUint> iSecondaryKeys;
        RArray<TUint> iWaitingKeys;

        // defined timeout
        TUint iKeyTimeOut;

        // first key pressed
        TPatternState iState;

        // if the keypatterns are enabled
        TBool iEnabled;

        // if the keylock policy exists
        TBool iHasPatterns;

        // timer used between primary and secondary keys
        CPeriodic* iKeyTimer;

    };

#endif // __LOCKAPPKEYPATTERN__