/*! \file
 * \brief Handles requests to the PlatformDevice.
 *
 * Handles requests to the PlatformDevice.
 * PlatformDevice contains system-level requests, like getting the MCU Unique Identifier, etc.
 *
 * \copyright
 * COPYRIGHT NOTICE: (c) 2017-2022 Neonode Technologies AB. All rights reserved.
 */

#ifndef DEVICE_PLATFORMDEVICE_PLATFORMDEVICE_H
#define DEVICE_PLATFORMDEVICE_PLATFORMDEVICE_H 1

#ifndef ZFORCECOMMON_H
    #error Please include "zForceCommon.h" before this file.
#endif // ZFORCECOMMON_H

/*!
 * \brief Struct representing a PlatformDevice.
 *
 * The PlatformDevice struct contains system-level requests, like getting the MCU Unique Identifier, etc.
 */
struct PlatformDevice
{
    zForce     * zForce;                   //!< Pointer to zForce.
    Connection * Connection;               //!< The Connection this Device is part of.
    DeviceType   DeviceType;               //!< Which type of Device this is.
    uint32_t     DeviceIndex;              //!< Which Device Index this device has.
    Device    ** StorageDevices;           //!< Future: List of Storage Devices. Will change type during implementation.
    uint32_t     NumberOfStorageDevices;   //!< Number of Storage Devices.
    void       * PrivateProtocolData;      //!< Private Protocol Data.
    /*!
     * \brief Destructor.
     *
     * Destructs the Device and all base structs.
     * \n\n
     * Inherited from Device base class.
     *
     * \param self Pointer to the struct itself.
     *
     * \return No return value.
     */
    void         ( * Destructor)(Device * self);
    /*!
     * \brief Get the finger frequency.
     *
     * Gets the finger frequency.
     * \n\n
     * On failure, errno is set.
     * - ::EALREADYINPROGRESS - Another request is currently in progress.
     * - ::ENOTSUPPORTED - This request is not supported by this Protocol and/or Device.
     *
     * \param self Pointer to the struct itself.
     * \return True for success, false for failure. See errno.
     */
    bool         ( * GetFingerFrequency)(PlatformDevice * self);

    /*!
     * \brief Set the finger frequency.
     *
     * Sets the finger frequency.
     * \n\n
     * On failure, errno is set.
     * - ::EALREADYINPROGRESS - Another request is currently in progress.
     * - ::ENOTSUPPORTED - This request is not supported by this Protocol and/or Device.
     *
     * \param self Pointer to the struct itself.
     * \param frequency The frequency to set.
     *
     * \return True for success, false for failure. See errno.
     */
    bool         ( * SetFingerFrequency)(PlatformDevice * self, uint32_t frequency);

    /*!
     * \brief Get the idle frequency.
     *
     * Gets the idle frequency.
     * \n\n
     * On failure, errno is set.
     * - ::EALREADYINPROGRESS - Another request is currently in progress.
     * - ::ENOTSUPPORTED - This request is not supported by this Protocol and/or Device.
     *
     * \param self Pointer to the struct itself.
     *
     * \return True for success, false for failure. See errno.
     */
    bool         ( * GetIdleFrequency)(PlatformDevice * self);

    /*!
     * \brief Set the idle frequency.
     *
     * Sets the idle frequency.
     * \n\n
     * On failure, errno is set.
     * - ::EALREADYINPROGRESS - Another request is currently in progress.
     * - ::ENOTSUPPORTED - This request is not supported by this Protocol and/or Device.
     *
     * \param self Pointer to the struct itself.
     * \param frequency The frequency to set.
     *
     * \return True for success, false for failure. See errno.
     */
    bool         ( * SetIdleFrequency)(PlatformDevice * self, uint32_t frequency);

    /*!
     * \brief Get the Mcu Unique Identifier.
     *
     * Gets the Mcu Unique Identifier.
     * \n\n
     * On failure, errno is set.
     * - ::EALREADYINPROGRESS - Another request is currently in progress.
     * - ::ENOTSUPPORTED - This request is not supported by this Protocol and/or Device.
     *
     * \param self Pointer to the struct itself.
     *
     * \return True for success, false for failure. See errno.
     */
    bool         ( * GetMcuUniqueIdentifier)(PlatformDevice * self);

    /*!
     * \brief Set the Mcu Unique Identifier.
     *
     * Sets the Mcu Unique Identifier.
     * \n\n
     * On failure, errno is set.
     * - ::EALREADYINPROGRESS - Another request is currently in progress.
     * - ::ENOTSUPPORTED - This request is not supported by this Protocol and/or Device.
     *
     * \param self Pointer to the struct itself.
     * \param identifier Pointer to the Identifier array to set.
     * \param length Buffer size.
     *
     * \return True for success, false for failure. See errno.
     */
    bool         ( * SetMcuUniqueIdentifier)(PlatformDevice * self, uint8_t * identifier, uint32_t bufferSize);
};

#ifdef __cplusplus
extern "C"
{
#endif // __cplusplus

/*!
 * \brief Internal call used to create a new PlatformDevice.
 *
 * Internal call used to create a new PlatformDevice.
 * \n\n
 * On failure, errno is set.
 * - ::EINVALIDSIZE - Invalid size
 *
 * \param connection The Connection the Device is associated with.
 * \param deviceType Which DeviceType to create.
 * \param deviceIndex Which Device Index to set.
 * \param size If this is used as a base class for another class, set size to non-zero.
 *
 * \return A pointer to the new Device.
 */
DLLINTERNAL PlatformDevice * PlatformDevice_New (Connection * connection, DeviceType deviceType, uint32_t deviceIndex,
                                                 size_t size);

#ifdef __cplusplus
}
#endif // _cplusplus

#endif // DEVICE_PLATFORMDEVICE_PLATFORMDEVICE_H

