localconnectivityservice/generichid/inc/hidtranslate.h
changeset 0 c3e98f10fcf4
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/localconnectivityservice/generichid/inc/hidtranslate.h	Mon Jan 18 21:03:15 2010 +0200
@@ -0,0 +1,191 @@
+/*
+* Copyright (c) 2005-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:  Report translator
+*
+*/
+
+#ifndef T_TRANSLATE_H
+#define T_TRANSLATE_H
+
+#include <e32std.h>
+
+class CField;
+
+/**
+ * HID report base object
+ *
+ * Base class for report translator and report generator.
+ * Contains only static functions.
+ *
+ * @lib  generichid.lib
+ * @since S60 v5.0
+ */
+class TReportUtils
+    {
+public:
+    /**
+     *  Find the index within the usages for a field of a given usage ID.
+     *
+     *  @since S60 v5.0
+     *  @param aField Pointer to the field.
+     *  @param aUsageId Usage ID to find.
+     *  @param aUsageIndex Reference to variable to receive the index.
+     *  @return True if the usage ID is found.
+     */
+    static TBool GetIndexOfUsage(const CField* aField,
+        TInt aUsageId, TInt& aUsageIndex);
+    /**
+     *  Find the usage ID at a given index within the usages for a field.
+     *
+     *  @since S60 v5.0
+     *  @param aField Pointer to the field.
+     *  @param aUsageIndex The index.
+     *  @return The usage ID at the given index.
+     */
+    static TInt UsageAtIndex(const CField* aField, TInt aUsageIndex);
+
+    /**
+     *  Write a value to a field at a given index.
+     *
+     *  @since S60 v5.0
+     *  @param aData Buffer containing the HID report.
+     *  @param aField The field in which to write.
+     *  @param aIndex Position in the field to write.
+     *  @param aValue Value to write to the field.
+     *  @return Error code indicating success or reason for failure.
+     */
+    static TInt WriteData(HBufC8& aData, const CField* aField,
+        TInt aIndex, TInt aValue);
+
+    /**
+     *  Read a value from a field at a given index.
+     *
+     *  @since S60 v5.0
+     *  @param aData Buffer containing the HID report.
+     *  @param aField The field from which to read.
+     *  @param aIndex Position in the field to read.
+     *  @param aValue Reference to variable to receive the value read
+     *                from the field.
+     *  @return Error code indicating success or reason for failure.
+     */
+    static TInt ReadData(const TDesC8& aData, const CField* aField,
+        TInt aIndex, TInt& aValue);
+    };
+
+/**
+ * HID report translator
+ *
+ * Allows a device driver to extract data items from a device report, based on
+ * the results of the report descriptor parser stage (at device connection)
+ *
+ * @lib  generichid.lib
+ * @since S60 v5.0
+ */
+class TReportTranslator
+    {
+public:
+
+    /**
+     * Constructor.
+     *
+     * @since S60 v5.0
+     * @param aData Data to be extracted
+     * @param aField  HID field
+     * @return return TReportTranslator
+     */
+    IMPORT_C TReportTranslator(const TDesC8& aData, const CField* aField);
+
+    /**
+     * For variable fields, reads the logical value of the control with the
+     * given usage ID.  For arrays, searches for the usage ID and gives the
+     * value as ETrue if found and EFalse if not.
+     *
+     * @since S60 v5.0
+     * @param aValue Reference to variable to receive the value read
+     *  from the field.
+     * @param aUsageId Usage ID of the control to read.
+     * @param aControlOffset Which control to read when more than one
+     *                       have the same usage ID.
+     * @return Error code indicating success or reason for failure.
+     */
+    IMPORT_C TInt GetValue(TInt& aValue, TInt aUsageId,
+        TInt aControlOffset = 0) const;
+
+    /**
+     * Alternate version of the above method for convenience.  Returns the
+     * value read directly and leaves if an error occurs.
+     *
+     * @since S60 v5.0
+     * @param aUsageId Usage ID of the control to read.
+     * @param aControlOffset Which control to read when more than one
+     *                       have the same usage ID.
+     * @return The logical value of a variable, or true/false for an array.
+     */
+    IMPORT_C TInt ValueL(TInt aUsageId, TInt aControlOffset = 0) const;
+
+    /**
+     * Gets the usage ID at a given index in an array field.  For variable
+     * fields, if the logical value of the control at the given index is non-
+     * zero, returns the usage ID of the control, otherwise returns zero.
+     *
+     * @since S60 v5.0
+     * @param aUsageId Reference to variable to receive the usage ID.
+     * @param aIndex Index in the array to read.
+     * @return Error code indicating success or reason for failure.
+     */
+    IMPORT_C TInt GetUsageId(TInt& aUsageId, TInt aIndex) const;
+
+    /**
+     * Alternate version of the above method for convenience.  Returns the
+     * usage ID directly and leaves if an error occurs.
+     *
+     * @since S60 v5.0
+     * @param aIndex Index in the array to read.
+     * @return The usage ID.
+     */
+    IMPORT_C TInt UsageIdL(TInt aIndex) const;
+
+    /**
+     * Gets the logical value at a given index in a field.  Leaves if an
+     * error occurs.
+     *
+     * @since S60 v5.0
+     * @param aIndex Index in the field to read.
+     * @return The logical value.
+     */
+    IMPORT_C TInt RawValueL(TInt aIndex) const;
+
+    /**
+     * Gets the number of controls in the field.
+     *
+     * @since S60 v5.0
+     * @return The number of controls.
+     */
+    IMPORT_C TInt Count() const;
+
+private:
+
+    /**
+     * Data to be extracted
+     */
+    const TDesC8& iData;
+
+    /**
+     * HID field
+     * Not own.
+     */
+    const CField* iField;
+    };
+
+#endif