/*========================== begin_copyright_notice ============================
Copyright (C) 2021-2022 Intel Corporation

SPDX-License-Identifier: MIT
============================= end_copyright_notice ===========================*/


/*!
 * @file GTPin configuration argument (KNOB)
 */

#ifndef IGT_KNOB_ARG_H_
#define IGT_KNOB_ARG_H_

#include <stdint.h>

#include "gt_knob_defs.h"

namespace gtpin
{
#pragma pack(push, 8)

/* ===================================================================================================== */
// Class IGtKnobArg
/* ===================================================================================================== */
/*! @ingroup GTPIN_KNOB
 * @brief Abstract class that represents GTPin configuration argument (KNOB)
 */
class IGtKnobArg
{
public:

    /*!
     * Assign a new value element to this argument.
     * If this is a vector-value %Knob (KNOB_FLAG_VECTOR), append the new value to the vector.
     * Otherwise, if this is a scalar-value %Knob, replace the old value with the new one.
     * @param[in]   value    New value of the %Knob. Its type must match the type of the %Knob,
     *                       as specified at %Knob creation.
     * @return  Success/failure status
     */
    virtual bool AddValue(const KnobValue& value) = 0;

    /*!
     * Get a value element specified by its position in the vector of argument's values
     * @note Vector-value %Knob (KNOB_FLAG_VECTOR) may have multiple value elements;
     *       scalar-value %Knob has a single value element and its position is zero.
     * @note For a %Knob of type KNOB_TYPE_STRING, the returned C-string could be invalidated when
     *       the %Knob is modified by a subsequent AddValue() call.
     *
     * @param[out]  value    Structure that receives the requested value and its type
     * @param[in]   index    Index of the requested element in the vector of values.
     *                       The index is any integer in the [0, NumValues()) range.
     * @return  Success/failure status
     */
    virtual bool GetValue(KnobValue& value, uint32_t index) const = 0;

    /*!
     * @return Number of value elements associated with this argument
     * @note Vector-value %Knob (KNOB_FLAG_VECTOR) may have multiple value elements;
     *       scalar-value %Knob has a single value element.
     */
    virtual uint32_t NumValues() const = 0;

    /*!
     * Copy descriptor of this argument into 'dsc' structure
     */
    virtual void GetDescriptor(KnobDescriptor& dsc) const = 0;

    /*!
     * Reset value of the specified %Knob.
     * If 'knob' is associated with a vector of values, clear the vector. Otherwise, for scalar %Knob, do nothing.
     */
    virtual void Reset() = 0;

protected:
    /// @internal Protected destructor
    virtual ~IGtKnobArg() = default;
};

#pragma pack(pop)
}
#endif
