localconnectivityservice/generichid/inc/hidtranslate.h
changeset 0 c3e98f10fcf4
equal deleted inserted replaced
-1:000000000000 0:c3e98f10fcf4
       
     1 /*
       
     2 * Copyright (c) 2005-2007 Nokia Corporation and/or its subsidiary(-ies).
       
     3 * All rights reserved.
       
     4 * This component and the accompanying materials are made available
       
     5 * under the terms of "Eclipse Public License v1.0"
       
     6 * which accompanies this distribution, and is available
       
     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".
       
     8 *
       
     9 * Initial Contributors:
       
    10 * Nokia Corporation - initial contribution.
       
    11 *
       
    12 * Contributors:
       
    13 *
       
    14 * Description:  Report translator
       
    15 *
       
    16 */
       
    17 
       
    18 #ifndef T_TRANSLATE_H
       
    19 #define T_TRANSLATE_H
       
    20 
       
    21 #include <e32std.h>
       
    22 
       
    23 class CField;
       
    24 
       
    25 /**
       
    26  * HID report base object
       
    27  *
       
    28  * Base class for report translator and report generator.
       
    29  * Contains only static functions.
       
    30  *
       
    31  * @lib  generichid.lib
       
    32  * @since S60 v5.0
       
    33  */
       
    34 class TReportUtils
       
    35     {
       
    36 public:
       
    37     /**
       
    38      *  Find the index within the usages for a field of a given usage ID.
       
    39      *
       
    40      *  @since S60 v5.0
       
    41      *  @param aField Pointer to the field.
       
    42      *  @param aUsageId Usage ID to find.
       
    43      *  @param aUsageIndex Reference to variable to receive the index.
       
    44      *  @return True if the usage ID is found.
       
    45      */
       
    46     static TBool GetIndexOfUsage(const CField* aField,
       
    47         TInt aUsageId, TInt& aUsageIndex);
       
    48     /**
       
    49      *  Find the usage ID at a given index within the usages for a field.
       
    50      *
       
    51      *  @since S60 v5.0
       
    52      *  @param aField Pointer to the field.
       
    53      *  @param aUsageIndex The index.
       
    54      *  @return The usage ID at the given index.
       
    55      */
       
    56     static TInt UsageAtIndex(const CField* aField, TInt aUsageIndex);
       
    57 
       
    58     /**
       
    59      *  Write a value to a field at a given index.
       
    60      *
       
    61      *  @since S60 v5.0
       
    62      *  @param aData Buffer containing the HID report.
       
    63      *  @param aField The field in which to write.
       
    64      *  @param aIndex Position in the field to write.
       
    65      *  @param aValue Value to write to the field.
       
    66      *  @return Error code indicating success or reason for failure.
       
    67      */
       
    68     static TInt WriteData(HBufC8& aData, const CField* aField,
       
    69         TInt aIndex, TInt aValue);
       
    70 
       
    71     /**
       
    72      *  Read a value from a field at a given index.
       
    73      *
       
    74      *  @since S60 v5.0
       
    75      *  @param aData Buffer containing the HID report.
       
    76      *  @param aField The field from which to read.
       
    77      *  @param aIndex Position in the field to read.
       
    78      *  @param aValue Reference to variable to receive the value read
       
    79      *                from the field.
       
    80      *  @return Error code indicating success or reason for failure.
       
    81      */
       
    82     static TInt ReadData(const TDesC8& aData, const CField* aField,
       
    83         TInt aIndex, TInt& aValue);
       
    84     };
       
    85 
       
    86 /**
       
    87  * HID report translator
       
    88  *
       
    89  * Allows a device driver to extract data items from a device report, based on
       
    90  * the results of the report descriptor parser stage (at device connection)
       
    91  *
       
    92  * @lib  generichid.lib
       
    93  * @since S60 v5.0
       
    94  */
       
    95 class TReportTranslator
       
    96     {
       
    97 public:
       
    98 
       
    99     /**
       
   100      * Constructor.
       
   101      *
       
   102      * @since S60 v5.0
       
   103      * @param aData Data to be extracted
       
   104      * @param aField  HID field
       
   105      * @return return TReportTranslator
       
   106      */
       
   107     IMPORT_C TReportTranslator(const TDesC8& aData, const CField* aField);
       
   108 
       
   109     /**
       
   110      * For variable fields, reads the logical value of the control with the
       
   111      * given usage ID.  For arrays, searches for the usage ID and gives the
       
   112      * value as ETrue if found and EFalse if not.
       
   113      *
       
   114      * @since S60 v5.0
       
   115      * @param aValue Reference to variable to receive the value read
       
   116      *  from the field.
       
   117      * @param aUsageId Usage ID of the control to read.
       
   118      * @param aControlOffset Which control to read when more than one
       
   119      *                       have the same usage ID.
       
   120      * @return Error code indicating success or reason for failure.
       
   121      */
       
   122     IMPORT_C TInt GetValue(TInt& aValue, TInt aUsageId,
       
   123         TInt aControlOffset = 0) const;
       
   124 
       
   125     /**
       
   126      * Alternate version of the above method for convenience.  Returns the
       
   127      * value read directly and leaves if an error occurs.
       
   128      *
       
   129      * @since S60 v5.0
       
   130      * @param aUsageId Usage ID of the control to read.
       
   131      * @param aControlOffset Which control to read when more than one
       
   132      *                       have the same usage ID.
       
   133      * @return The logical value of a variable, or true/false for an array.
       
   134      */
       
   135     IMPORT_C TInt ValueL(TInt aUsageId, TInt aControlOffset = 0) const;
       
   136 
       
   137     /**
       
   138      * Gets the usage ID at a given index in an array field.  For variable
       
   139      * fields, if the logical value of the control at the given index is non-
       
   140      * zero, returns the usage ID of the control, otherwise returns zero.
       
   141      *
       
   142      * @since S60 v5.0
       
   143      * @param aUsageId Reference to variable to receive the usage ID.
       
   144      * @param aIndex Index in the array to read.
       
   145      * @return Error code indicating success or reason for failure.
       
   146      */
       
   147     IMPORT_C TInt GetUsageId(TInt& aUsageId, TInt aIndex) const;
       
   148 
       
   149     /**
       
   150      * Alternate version of the above method for convenience.  Returns the
       
   151      * usage ID directly and leaves if an error occurs.
       
   152      *
       
   153      * @since S60 v5.0
       
   154      * @param aIndex Index in the array to read.
       
   155      * @return The usage ID.
       
   156      */
       
   157     IMPORT_C TInt UsageIdL(TInt aIndex) const;
       
   158 
       
   159     /**
       
   160      * Gets the logical value at a given index in a field.  Leaves if an
       
   161      * error occurs.
       
   162      *
       
   163      * @since S60 v5.0
       
   164      * @param aIndex Index in the field to read.
       
   165      * @return The logical value.
       
   166      */
       
   167     IMPORT_C TInt RawValueL(TInt aIndex) const;
       
   168 
       
   169     /**
       
   170      * Gets the number of controls in the field.
       
   171      *
       
   172      * @since S60 v5.0
       
   173      * @return The number of controls.
       
   174      */
       
   175     IMPORT_C TInt Count() const;
       
   176 
       
   177 private:
       
   178 
       
   179     /**
       
   180      * Data to be extracted
       
   181      */
       
   182     const TDesC8& iData;
       
   183 
       
   184     /**
       
   185      * HID field
       
   186      * Not own.
       
   187      */
       
   188     const CField* iField;
       
   189     };
       
   190 
       
   191 #endif