/*

  keyboard_chipset_api.h

  Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies). 

  All rights reserved.

  This program and the accompanying materials are made available 

  under the terms of the Eclipse Public License v1.0 which accompanies 

  this distribution, and is available at 

  http://www.eclipse.org/legal/epl-v10.html

  Initial Contributors:

  Nokia Corporation - initial contribution.

  Contributors:

*/

/** @file

@brief Keyboard Chipset API H

This is the header file for Keyboard Chipset API that is used to access 

the matrix keyboard and power key services provided by the third party chipset vendors.

@publishedDeviceAbstraction

*/

#ifndef __KEYBOARD_CHIPSET_API_H__

#define __KEYBOARD_CHIPSET_API_H__

// Include files

#include <kern_priv.h>

#include <e32event.h>

// Constants

// Macros

// Data types

/**

This defines the type of a callback function which is called to 

notify a new key event to the client. The callback function is 

executed in the context of the calling thread.

*/

typedef void (*TKeyboardEventCbFn)();

// Function prototypes

// Forward declarations

// Class declaration

/**

This class defines the Chipset API that is used to access 

the matrix keyboard service provided by the third party chipset vendors.

*/

class KeyboardMatrix

    {

    public:

        /**

        This function is used to do the necessary initialization with the given matrix size 

        so that the chipset is ready to provide the matrix keyboard service. It registers 

		a callback function which is called to notify a new key event.

        @param aSize The size of matrix keyboard that the client is using.

        @param aCallback The callback function which is called to notify a new key event.

        @return Symbian OS system wide error code, and the followings are required:

                KErrNone – the operation is successfully executed;

                KErrGeneral – error condition;

        @pre Pre-condition, it should be called before the other methods in the class are used.

        */

        IMPORT_C static TInt Init(TUint aSize, TKeyboardEventCbFn aCallback);

        /**

        This function is used to enable the matrix keyboard service.  

        @return Symbian OS system wide error code, and the followings are required:

                KErrNone – the operation is successfully executed;

                KErrGeneral – error condition;

        @pre Pre-condition, the matrix keyboard service has been initialized successfully.

        */

        IMPORT_C static TInt Enable();

        /**

        This function is used to disable the matrix keyboard service.

        @return Symbian OS system wide error code, and the followings are required:

                KErrNone – the operation is successfully executed;

                KErrGeneral – error condition;

        @pre Pre-condition, the matrix keyboard service has been enabled.

        */

        IMPORT_C static TInt Disable();

        /**

        This function is used to read the key state of the matrix keyboard.

        @param aKeys   Reference to the number of keys that are currently pressed. 

                       If the return value is 0 then it means all the previously pressed keys are released.

        @param aBuffer Pointer to the buffer where all the key presses shall be reported.

        @return Symbian OS system wide error code, and the followings are required:

				KErrNone – the operation is successfully executed;

                KErrGeneral – error condition;

        @pre Pre-condition, the matrix keyboard service has been enabled.

        */

        IMPORT_C static TInt Read(TInt& aKeys, TInt* aBuffer);

    };

/**

This class defines the Chipset API that is used to access 

the power key service provided by the third party chipset vendors.

*/

class KeyboardPowerKey

    {

    public:

        /**

        This function is used to do the necessary initialization so that 

        the chipset is ready to provide the power key service. It registers 

        a callback function which is called to notify a new power key event.

        @param aCallback The callback function which is called to notify a new power key event.

        @return Symbian OS system wide error code, and the followings are required:

                KErrNone – the operation is successfully executed;

                KErrGeneral – error condition;

        */

        IMPORT_C static TInt Init(TKeyboardEventCbFn aCallback);

        /**

        This function is used to read the key state of the power key.

        @param aState Reference to the variable that contains the power key state.

        @return Symbian OS system wide error code, and the followings are required:

                KErrNone – the operation is successfully executed;

                KErrGeneral – error condition;

        */

        IMPORT_C static TInt Read(TRawEvent::TType& aState);

    };

#endif // __KEYBOARD_CHIPSET_API_H__