/*

* Copyright (c) 2004-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:  Declares main application class.

*

*/

#ifndef C_HIDDRIVER_H

#define C_HIDDRIVER_H

#include <ecom/ecom.h>

class CReportRoot;

class MDriverAccess;

class MTransportLayer;

class CHidDriver;

// ----------------------------------------------------------------------

// Return codes from the Generic HID to Transport layers

//

const TInt KErrHidBase = -8000;

const TInt KErrHidNoDriver = KErrHidBase;           /*!< No driver could be found to handle the request */

const TInt KErrHidSuspended = KErrHidBase - 1;      /*!< Command not handled - driver is suspended */

const TInt KErrHidUnrecognised = KErrHidBase - 2;   /*!< Driver could not understand the data */

const TInt KErrHidUnexpected = KErrHidBase - 3;     /*!< Unsolicited data from the device */

const TInt KErrHidBadChannel = KErrHidBase - 4;     /*!< Channel was not Int or Ctrl type */

const TInt KErrHidPartialSupported = KErrHidBase - 5;     /*!< Partil supported hid device */

// Errors returned by the report translator / generator:

//

const TInt KErrUsageNotFound = KErrHidBase - 10;    //!< Usage page/ID wasn't found in the field

const TInt KErrValueOutOfRange = KErrHidBase - 11;  //!< Value specified is outside the logical range

const TInt KErrNoSpaceInArray = KErrHidBase - 12;   //!< Array field already contains the maximum number of values

const TInt KErrBadControlIndex = KErrHidBase - 13;  //!< Control index exceeds the number of controls in the field

// ACK codes returned by Set/Get requests to the devices

//

const TInt KErrCommandAckBase = -8100;

const TInt KErrAckInvalidReportID = KErrCommandAckBase;         /*!< Invalid report ID */

const TInt KErrAckInvalidParameter = KErrCommandAckBase - 1;    /*!< Invalid or out of range param */

const TInt KErrAckUnknown = KErrCommandAckBase - 2;             /*!< Command failed, but the device can't determine why */

const TInt KErrAckFatal = KErrCommandAckBase - 3;               /*!< The device is in an unrecoverable state and must be restarted */

// Constant for plugin interface:

const TUid KHidDriverPluginInterfaceUid        = { 0x10201d26 };

class THidEvent

    {

    public:

    /**

     * Usage page

     */

    TInt iUsagePage;

    /**

     * Keycode

     */

    TInt iKeyCode;

    };

class CHidInputDataHandlingReg: public CBase

    {

public:

    /**

     * Two-phased constructor.     

     */

    static CHidInputDataHandlingReg* NewL();

    /**

     * Destructor

     */

     virtual ~CHidInputDataHandlingReg(); 

public:        

    /**

     * Check if key event is not allready processed

     *

     * @since S60 v5.0

     * @param aUsagePage a usage page to be checked

     * @param aUsage a usage code to be checked

     * @return true if event is not allready handled

     */

    IMPORT_C TBool  AllowedToHandleEvent(TInt aUsagePage, TInt aUsage);

    /**

     * Add handled event

     *

     * @since S60 v5.0

     * @param aUsagePage usage page to be handled

     * @param aUsage Usage to be handled

     * @return None.

     */ 

    IMPORT_C void  AddHandledEvent( TInt aUsagePage, TInt aUsage);

    /**

     * Reset Array 

     */

    void  Reset();

private:

    CHidInputDataHandlingReg();

    void ConstructL();

private: 

    /**

     * Event array

     * Own.

     */

    CArrayFixFlat<THidEvent>* iEventArray;

    };

/**

 *

 *  Transport layer interface class

 *  Interface allowing the generic HID layer to pass data to a Transport layer

 *  All commands are asynchronous.  The results are returned via the

 *

 *  @since S60 v5.0

 */

class MTransportLayer

    {

public:

    /**

     * Request for the country code of the given device.

     *

     * @since S60 v5.0

     * @param aConnID The device identifier

     * @return country code.

     */

    virtual TUint CountryCodeL(TInt aConnID) = 0;

    /**

     * Request for the vendor identifier for the given device.

     *

     * @since S60 v5.0

     * @param aConnID The device identifier

     * @return vendor id.

     */

    virtual TUint VendorIdL(TInt aConnID) = 0;

    /**

     * Request for the product identifier for the given device.

     *

     * @since S60 v5.0

     * @param aConnID The device identifier

     * @return product id.

     */

    virtual TUint ProductIdL(TInt aConnID) = 0;

    /**

     * Request for the current device report protocol. The protocol will be

     * received as a control report via the CHidTransport::DataIn function

     *

     * @since S60 v5.0

     * @param aConnID The device identifier

     * @param aInterface The interface we want to get the protocol from

     * @return None.

     */

    virtual void GetProtocolL(TInt aConnID,  TUint16 aInterface) = 0;

    /**

     * Request to put the device in the specified protocol

     *

     * @since S60 v5.0

     * @param aConnID The device identifier

     * @param aValue The requested protocol for the device (boot or report)

     * @param aInterface The interface we want to set the protocol for

     * @return None.

     */

    virtual void SetProtocolL(TInt aConnID, TUint16 aValue,

        TUint16 aInterface) = 0;

    /**

     * Request for a device report. The data will be received as a control report

     * via the CHidTransport::DataIn function

     *

     * @since S60 v5.0

     * @param aConnID The device identifier

     * @param aReportType The type of report (input/output/feature) requested

     * @param aReportID The specific report required

     * @param aInterface The interface we want the report from

     * @param aLength The expected length of the report buffer

     * @return None.

     */

    virtual void GetReportL(TInt aConnID, TUint8 aReportType,TUint8 aReportID,

        TUint16 aInterface, TUint16 aLength) = 0;

    /**

     * Request to send a report to a device. The response will be reported via the

     * CHidTransport::CommandResult function

     *

     * @since S60 v5.0

     * @param aConnID The device identifier

     * @param aReportType The type of report (input/output/feature) requested

     * @param aReportID The specific report required to set

     * @param aInterface The interface we want to send the report to

     * @param aReport The report payload to be sent to the device

     * @return None.

     */

    virtual void SetReportL(TInt aConnID, TUint8 aReportType,TUint8 aReportID,

        TUint16 aInterface, const TDesC8& aReport) = 0;

    /**

     * Request to send data to a device. There are no responses to this report from device.

     *

     * @since S60 v5.0

     * @param aConnID The device identifier

     * @param aReportID The specific report required

     * @param aInterface The interface we want to send the report to

     * @param aReport The report payload to be sent to the device

     * @return None.

     */

    virtual void DataOutL(TInt aConnID, TUint8 aReportID,

        TUint16 aInterface, const TDesC8& aReport) = 0;

    /**

     * Request for the current idle rate of a report from the device. The response

     * will be recevied via the CHidTransport::DataIn function

     *

     * @since S60 v5.0

     * @param aConnID The device identifier

     * @param aReportID The specific report to be queried

     * @param aInterface The interface we want to query for idle rate

     * @return None.

     */

    virtual void GetIdleL(TInt aConnID, TUint8 aReportID,

        TUint16 aInterface) = 0;

    /**

     * Request to set the current idle rate for a report on the device.

     * The response will be received via the CHidTransport::CommandResult function

     *

     * @since S60 v5.0

     * @param aConnID The device identifier

     * @param aReportID The specific report to be queried

     * @param aDuration The time period between idle reports (4ms per bit. An

     *        interval of 0 disables idle reports so that Interrupt reports are only ever

     *        received when the reported data has changed

     * @param aReportID The specific report to be queried

     * @param aInterface The interface we want to query for idle rate

     * @return None.

     */

    virtual void SetIdleL(TInt aConnID,  TUint8 aDuration, TUint8 aReportID,

        TUint16 aInterface) = 0;

    };

/**

 *

 *  Driver access interface

 *  Interface allowing drivers to request data from and send data to devices via

 *  the Generic HID layer.

 *

 *  @since S60 v5.0

 */

class MDriverAccess

    {

public:

    /**

     * The type of report requested from the device

     * Note: The enumeration values map directly to the HID equivalent values

     * (Passed as TUint16 values to the transport layer)

     */

    enum TReportType

        {

        EInput=1,     /*!< Input report */

        EOutput,      /*!< Output report */

        EFeature      /*!< Feature report */

        };

    /** Return codes from the Generic HID to the device drivers

     * Note: The enumeration values map directly to the HID equivalent values

     *(Passed as TUint8 values to the transport layer)

     */

    enum TProtocols

        {

        EBoot=0,        /*!< Boot Protocol */

        EReport=1       /*!< Report Protocol */

        };

public:

    /**

     * Retrieves the country code for the HID device

     *

     * @since S60 v5.0

     * @param aConnID The device identifier

     * @return contry code

     */

    virtual TUint CountryCodeL(TInt aConnID) = 0;

    /**

     * Retrieves the  for the HID device

     *

     * @since S60 v5.0

     * @param aConnID The device identifier

     * @return vendor id

     */

    virtual TUint VendorIdL(TInt aConnID) = 0;

    /**

     * Retrieves the product identifier for the HID device

     *

     * @since S60 v5.0

     * @param aConnID The device identifier

     * @return produrct id

     */

    virtual TUint ProductIdL(TInt aConnID) = 0;

    /**

     * Requests the current protocol for the device (boot or report)

     * Leaves whit KErrInUse The request was not successful because the transport 

     * layer is busy with previous request and KErrNotReady The request failed 

     * because the device is currently unavaila

     *

     * @since S60 v5.0

     * @param aConnectionID The connection id

     * @param aInterface The current interface being used by the driver

     * @return None.

     */

    virtual void GetProtocolL(TInt aConnectionID,

        TUint16 aInterface) = 0;

    /**

     * Requests a report from the device

     * Leaves whit KErrInUse The request was not successful because the transport 

     * layer is busy with previous request and KErrNotReady The request failed 

     * because the device is currently unavailable

     *

     * @since S60 v5.0

     * @param aConnectionId The connection id

     * @param aReportId The report required from the device

     * @param aInterface The current interface being used by the driver

     * @param aLength ** NOT USED **

     * @return None

     */

    virtual void GetReportL(TInt aConnectionId, TUint8 aReportId,

        TUint16 aInterface, TUint16 aLength) = 0;

    /**

     * Requests the current Idle setting for the device

     * Leaves whit KErrInUse The request was not successful because the transport 

     * layer is busy with previous request and KErrNotReady The request failed 

     * because the device is currently unavailable

     *

     * @since S60 v5.0

     * @param aConnectionId The device ID

     * @param aReportId The report required from the device

     * @param aInterface The current interface being used by the driver

     * @return None.

     */

    virtual void GetIdleL(TInt aConnectionId, TUint8 aReportId,

        TUint16 aInterface ) = 0;

    /**

     * Sets the protocol to be used for reports

     * Leaves whit KErrInUse The request was not successful because the transport 

     * layer is busy with previous request and KErrNotReady The request failed 

     * because the device is currently unavailable

     *

     * @since S60 v5.0

     * @param aConnectionId The device ID

     * @param aInterface The current interface being used by the driver

     * @param aProtocol The required protocol (boot or report)

     * @parem aDriver Calling driver

     * @return None.

     */

    virtual void SetProtocolL(TInt aConnectionId,

        TUint16 aInterface, TProtocols aProtocol, CHidDriver* aDriver) = 0;

    /**

     * Sets the idle interval for interrupt data.

     * Leaves whit KErrInUse The request was not successful because the transport 

     * layer is busy with previous request and KErrNotReady The request failed 

     * because the device is currently unavailable

     *

     * @since S60 v5.0

     * @param aConnectionId The device ID

     * @param aDuration The idle interval, in steps of 0.04ms intervals (where

     *                  1 = 0.04ms, 2=0.08ms). 0 will disable idle so reports

     *                   are only sent when the state of the device changes

     * @param aInterface The current interface being used by the driver

     * @param aReportId The report whose idle rate is being set

     * @param aInterface The current interface being used by the driver

     * @parem aDriver Calling driver

     * @return None.

     */

    virtual void SetIdleL(TInt aConnectionId, TUint8 aDuration,

        TUint8 aReportId, TUint16 aInterface, CHidDriver* aDriver) = 0;

    /**

     * Sends a report to the device

     *

     * @since S60 v5.0

     * @param aConnectionId The device ID

     * @param aReportId The report to receive the setup report

     * @param aReportType The type of report being sent to the device (input, output

     *                     or Feature)

     * @param aPayload The report being sent to the device

     * @parem aDriver Calling driver

     * @param aInterface The current interface being used by the driver

     * @return KErrNone The request was successful and the result of the command is

     *         expected at a later time (as a CmdAck message), KErrInUse The request

     *         was not successful because the transport layer is busy with a previous

     *         request, KErrNotReady The request failed because the device is currently

     *         unavailable and KErrNoMemory The request failed because not enough memory

     *         available

     */

    virtual void SetReportL(TInt aConnectionId, TUint8 aReportId,

        TReportType aReportType, const TDesC8& aPayload,

        TUint16 aInterface, CHidDriver* aDriver) = 0;

    /**

     * Sends a report to the device (from host) using Interrupt Channel as DATA

     *

     * @since S60 v5.0

     * @param aConnectionId The device ID

     * @param aReportId The report to receive the setup report

     * @param aPayload The report being sent to the device

     * @param aInterface The current interface being used by the driver

     * @return KErrNone The request was successful and the result of the

     *         command is expected at a later time (as a CmdAck message),

     *         KErrInUse The request was not successful because the transport layer is

     *         busy with a previous request, KErrNotReady The request failed because the

     *         device is currently unavailable and KErrNoMemory The request failed because

     *         not enough memory available

     */

    virtual void DataOutL(TInt aConnectionId, TUint8 aReportId,

        /*TReportType aReportType,*/ const TDesC8& aPayload,

        TUint16 aInterface) = 0;

    /**

     * A request for the parsed descriptor container object so the driver can

     * retrieve the report format(s)

     *

     * @since S60 v5.0

     * @param aConnectionId The device ID

     * @return A pointer to the parsed report descriptor container and

     *        NULL if no parsed report descriptor container exists

     */

    virtual CReportRoot* ReportDescriptor(TInt aConnectionId) = 0;

    };

/**

 *

 *  Hid transport interface

 *  Interface allowing the transport layer to pass data to the Generic HID

 *

 *  @since S60 v5.0

 */

class CHidTransport : public CBase

    {

public:

    /**

     * Defines the channel type for the DataIn function

     */

    enum THidChannelType

        {

        EHidChannelInt,     /*!< Interrupt channel */

        EHidChannelCtrl     /*!< Control channel */

        };

    /**

     *Driver state (active or suspended)

     */

    enum TDriverState

        {

        EActive,            /*!< Driver will handle interrupt data */

        ESuspend            /*!< the driver will not handle interrupt data */

        };

public:

    /**

     * Called when a device has connected

     *

     * @since S60 v5.0

     * @param aConnectionId The transport-layer enumeration for the connection

     * @param aDescriptor The report descriptor for the device

     * @return KErrNone The connection will be handled by one or more drivers,

     *         KErrHidNoDriver No driver was found to handle the connected device

     */

    virtual TInt ConnectedL(TInt aConnectionId, const TDesC8& aDescriptor) = 0;

    /**

     * Called when a device has been disconnected

     *

     * @since S60 v5.0

     * @param aConnectionId The transport-layer enumeration for the connection

     * @param aDescriptor The report descriptor for the device

     * @return KErrNone The device was recognised and its drivers were unloaded and

     *         KErrHidNoDriver No driver was found to handle the connected device

     */

    virtual TInt Disconnected(TInt aConnectionId) = 0;

    /**

     * Called when a device has been disconnected

     *

     * @since S60 v5.0

     * @param aConnectionId Transport layer connection enumeration

     * @param aChannel Channel ID (Interrupt or Control)

     * @param aPayload The complete report payload