/*
* 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