zircon/system/ulib/hid-parser/include/hid-parser/item.h

// Copyright 2017 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#pragma once

#include <stdint.h>
#include <stdlib.h>

namespace hid {

// Value class that represents a USB HID report descriptor "Item" as defined
// by the Device Class Definition for Human Interface Devices Firmware
// specification 1.11 for "short items" (see usb.org).

class Item {
public:
    enum class Type : uint8_t {
        kMain,
        kGlobal,
        kLocal,
        kReserved,
        // Note: long items are not fully parsed.
        kLongItem,
    };

    enum class Tag: uint8_t {
        // Main tags.
        kInput,
        kOutput,
        kFeature,
        kCollection,
        kEndCollection,

        // Global tags.
        kUsagePage,
        kLogicalMinimum,
        kLogicalMaximum,
        kPhysicalMinimum,
        kPhysicalMaximum,
        kUnitExponent,
        kUnit,
        kReportSize,
        kReportId,
        kReportCount,
        kPush,
        kPop,

        // Local tags.
        kUsage,
        kUsageMinimum,
        kUsageMaximum,
        kDesignatorIndex,
        kDesignatorMinimum,
        kDesignatorMaximum,
        kStringIndex,
        kStringMinimum,
        kStringMaximum,
        kDelimiter,

        // Reserved tag (for any type).
        kReserved,
    };

    // Construct an Item from a HID report descriptor bytestream.
    // |data| should contain a hid report descriptor with |len| > 0
    // and the returned object is one parsed hid report item.
    //
    // Upon return |*actual| contains how many bytes to advance to the
    // next Item. Caller must check that:
    //  |*actual| is not zero
    //     If so, parsing is not supported for this stream.
    //  |*actual| is not greater than |len|.
    //    If so, more data is needed and returned item's data()
    //    is set to zero.
    //
    // Most bit patterns are valid items so if garbage data is given
    // to this method a set of valid-looking items can be returned so
    // the next layer must validate that the sequence of items is
    // reasonable and structurally correct.
    static Item ReadNext(const uint8_t* data, size_t len, size_t* actual);

    // Construct an Item from explicit values.
    // No validation is performed.
    constexpr Item(Type type, Tag tag, uint8_t size, uint32_t data)
        : type_(type), tag_(tag), size_(size), data_(data) {
    }

    Type type() const { return type_; }
    Tag tag() const { return tag_; }
    uint32_t data() const { return data_; }
    int32_t signed_data() const;

private:
    const Type type_;
    const Tag tag_;
    const uint8_t size_;
    const uint32_t data_;
};

}  // namespace hid