diff -r 453dfc402455 -r 0aa8cc770c8a remoteconn_plat/generic_hid_api/inc/hidinterfaces.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/remoteconn_plat/generic_hid_api/inc/hidinterfaces.h Tue Aug 31 16:03:15 2010 +0300 @@ -0,0 +1,704 @@ +/* +* 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 + + +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* 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 + * @return KErrNone The payload was handled by one or more drivers, + * KErrHidNoDriver No driver is handling reports from the device + * and KErrHidSuspended The report was not handled because all the drivers + * handling the device are suspended + */ + virtual TInt DataIn(TInt aConnectionId, + THidChannelType aChannel, const TDesC8& aPayload) = 0; + + /** + * Suspends or Resumes the driver(s) handling the connection + * + * @since S60 v5.0 + * @param aConnectionId Transport layer connection enumeration + * @param aActive The requested state of the driver (active or suspended) + * @return KErrNone The driver was successfully put into the requested state, + * and KErrHidAlreadyInState All the drivers were already in the + * requested state + */ + virtual TInt DriverActive(TInt aConnectionId, + CHidTransport::TDriverState aActive) = 0; + + /** + * Called by the transport layers to inform the generic HID of the + * success of the last Set... command. + * + * @since S60 v5.0 + * @param aConnectionId Transport layer connection enumeration + * @param aCmdAck Status of the last Set... command + * @return None. + */ + virtual void CommandResult(TInt aConnectionId, TInt aCmdAck) = 0; + }; + +/** + * + * Driver plugin interface + * Interface allowing drivers to request data from and send data to devices via + * the Generic HID layer. + * + * @lib generichid.lib + * @since S60 v5.0 + */ +class CHidDriver : public CBase + { +public: + + + /** + * Two-phased constructor. + * @param aImplementationUid Implementation UID of the plugin to be + * created. + * @param aHid Driver acces interface + */ + IMPORT_C static CHidDriver* NewL( + const TUid aImplementationUid, + MDriverAccess* aHid ); + + /** + * Destructor + */ + IMPORT_C virtual ~CHidDriver(); + + /** + * Called by the Generic HID to see if the factory can use reports described by + * the parsed report descriptor + * NOTE: The current implementation supports just one driver and that driver + * that will either handle all the reports from the device or none at all. + * Report ID is not currently being taken into account. + * + * @since S60 v5.0 + * @param aReportDescriptor Parsed HID report descriptor + * @return KErrNone The driver will handle reports from the report descriptor and + * KErrHidUnrecognised The driver cannot handle reports from the device + */ + virtual TInt CanHandleReportL(CReportRoot* aReportDescriptor) = 0; + + /** + * Called by the Generic HID layer when a device has sent a report on the + * interrupt or control channel + * + * @since S60 v5.0 + * @param aChannel Channel ID (Interrupt or Control) + * @param aPayload The complete report payload + * @return Error if data can't be handled. + */ + virtual TInt DataIn(CHidTransport::THidChannelType aChannel, + const TDesC8& aPayload) = 0; + + /** + * Called by the Generic HID layer when the handled device has been disconnected + * interrupt or control channel + * + * @since S60 v5.0 + * @param aReason Disconnection code + * @return None. + */ + virtual void Disconnected(TInt aReason) = 0; + + /** + * Called after a driver is sucessfully created by the Generic HID, + * when a device is connected. + * + * @since S60 v5.0 + * @param aConnectionId An number used to identify the device in + * subsequent calls from the driver to the generic HID, for example + * when sending data to the device. + * @return None. + */ + virtual void InitialiseL(TInt aConnectionId) = 0; + + /** + * Enables the driver so that it will configure the device and + * start handling interrupt reports from the device + * + * @since S60 v5.0 + * @param aConnectionId A number used to identify the device in + * subsequent calls from the driver to the Generic HID, for example + * when sending data to the device. + * @return None. + */ + virtual void StartL(TInt aConnectionId) = 0; + + /** + * Disables the driver so that it will stop handling device + * interrupt reports + * + * @since S60 v5.0 + * @return None. + */ + virtual void Stop() = 0; + + /** + * Called by the transport layers to inform the generic HID of + * the success of the last Set... command. + * + * @since S60 v5.0 + * @param aCmdAck Status of the last Set... command + * @return None. + */ + virtual void CommandResult(TInt aCmdAck) = 0; + + /** + * Return count of supported fields + * + * @since S60 v5.0 + * @return Number of supported fields. + */ + virtual TInt SupportedFieldCount()= 0; + + + /** + * Set input handling registy + * + * @since S60 v5.0 + * @param aHandlingReg a Input handling registry + * @return Number of supported fields. + */ + virtual void SetInputHandlingReg(CHidInputDataHandlingReg* aHandlingReg) = 0; + + protected: + /** + * C++ constructor. + */ + IMPORT_C CHidDriver(); + + private: // Data + + /** + * ECOM plugin instance UID. + */ + TUid iDtor_ID_Key; + }; + +#endif + +