/*

* 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:  BTHid item

*

*/

#ifndef T_ITEM_H

#define T_ITEM_H

#include <e32std.h>

/**

 * HID item class

 * A HID report descriptor is comprised of a sequence of "items"

 * that provide information about the device.  Items consist of a

 * header and zero or more bytes of data.  The header contains the item

 * type (main/global/local), an item "tag" (subtype) and the item size.

 * Items can be "short" (containing a maximum of 4 bytes of data) or

 * "long" (a maximum of 255 bytes of data).

 * A TItem represents a single HID report descriptor item. It is

 * constructed from an eight bit non-modifiable (Symbian-) descriptor,

 * which is assumed to contain report (HID-) descriptor data.

 *

 * @lib generichid.lib

 * @since S60 v5.0

 */

class TItem

    {

public:

    /**

     * The possible item types: main, global or local.  Item type is

     * a two-bit field -- the 11b value is reserved for "long items", which

     * are only used for vendor-specific commands.

     */

    enum TItemType

        {

        EMain = 0,    //!< Input, output, feature and begin or end collection

        EGlobal = 1,  //!< Global item items affect all subsequent fields

        ELocal = 2,   //!< Local items only persist until the next main item

        EReserved = 3 //!< No defined use in the current HID standard (v1.11)

        };

public:

    /**

     * The constructor takes a an eight bit non-modifiable (Symbian-)

     * descriptor containing report (HID-) descriptor data.

     * The item tag, type, data size and offset are calculated here.

     *

     * @since S60 v5.0

     * @param aRawData The raw item data, represented as a Symbian

     * descriptor. The item data is assumed to be at the beginning of the

     * descriptor. The size of the TDesC8 may be greater than the size

     * of the item, as the item size will be calculated from the raw HID

     * descriptor data.  Of course, the TDesC8 should be at least as

     * long as the raw item data.

     */

    TItem(const TDesC8& aRawData);

    /**

     * DataSize() returns the size of the item data in bytes. This

     * is the total item size minus the size of any header information.

     * (A short item header is a single byte, a long item header is

     * three bytes long.)

     *

     * @since S60 v5.0

     * @return The size, in bytes, of the item data. Range 0-255.

     */

    TInt DataSize() const;

    /**

     * Tag() returns the tag (subtype) value for this item.

     *

     * @since S60 v5.0

     * @return The item tag.

     */

    TInt Tag() const;

    /**

     * Data() returns the data associated with the item, represented as a

     * 32-bit unsigned integer.  This is only meaningful if the data length

     * is less than 4 bytes.

     *

     * @since S60 v5.0

     * @return The item data as a 32-bit unsigned integer.

     */

    TUint32 Data() const;

    /**

     * SignedData() returns the data associated with the item,

     * represented as a 32-bit signed integer.  This is only

     * meaningful if the data length is less than 4 bytes.

     *

     * @since S60 v5.0

     * @return The item data as a 32-bit signed integer.

     */

    TInt32 SignedData() const;

    /**

     * Returns the byte at the given offset within the item data block.     

     *

     * @since S60 v5.0

     * @param aIndex The index within the data block for the current tag.

     * @return The data at the specified index.

     */

    TUint8 operator[](TInt aIndex) const;

    /**

     * Type() returns the item type (e.g. "global").

     *

     * @since S60 v5.0     

     * @return The item type.

     */

    TItemType Type() const;

    /**

     * Check if item is main

     *

     * @since S60 v5.0

     * @return ETrue if item type is "main"

     */

    TBool IsMain() const;

    /**

     * Check if item is local

     *

     * @since S60 v5.0

     * @return ETrue if item type is "local"

     */

    TBool IsLocal() const;

    /**

     * Check if item is global

     *

     * @since S60 v5.0

     * @return ETrue if item type is "global"

     */

    TBool IsGlobal() const;

    /**

     * Check if item is global

     *

     * @since S60 v5.0

     * @return ETrue if this is a long item

     */

    TBool IsLong() const;

    /**

     * ItemSize() returns the total size of this item, including the

     * header data.

     *

     * @since S60 v5.0

     * @return The total size of this item, in bytes.

     */

    TInt ItemSize() const;

private:

    /**

     * Pointer to the raw report descriptor data

     */

    TPtrC8 iRawData;

    /**

     * Item data size

     */

    TInt iSize;

    /**

     * Item tag value

     */

    TInt iTag;

    /**

     * Offset in bytes of the data block

     */

    TInt iDataOffset;

    /**

     * Item type

     */

    TItemType iType;

    };

#endif