/*!\file
 * \brief \todo Описание файла.
*/
/*
 * II2c.h
 *
 *  Created on: 3 июл. 2019 г.
 *      Author: titov
 */

#ifndef SOURCE_PERIPHERAL_II2C_H_
#define SOURCE_PERIPHERAL_II2C_H_

#include <cstddef>
#include <stdint.h>

namespace peripheral {

struct II2c {

    typedef uint32_t Frequency; //!<Частота тактов в Гц.
    typedef uint16_t FrameSize; //!<Размер фрейма в битах.

    //!Интерфейс формирования транзакции на шине I2c.
    struct ITransaction {

        typedef uint16_t Address;
        typedef uint16_t Quantity;

        //!Функция добавляет запрос на запись n фреймов данных.
        /*!Функция добавляет запрос на запись n фреймов данных.
         * Фрейм данных от 1 до 8 бит, выравнены по правому краю.
         * \param[in] address Адрес устройства на шине.
         * \param[in] data Массив данных по 8-1 бит данных в char.
         * \param[in] n Количество данных.
         * \return Признак валидости запроса записи.
         */
        virtual bool addWriteRequest( Address address, const void * data, Quantity n ) = 0;

        //!Функция добавляет запрос на чтение n фреймов данных.
        /*!Функция добавляет запрос на чтение n фреймов данных.
         * Фрейм данных от 1 до 8 бит, выравнены по правому краю.
         * \param[in] address Адрес устройства на шине.
         * \param[in] data Массив данных по 8-1 бит данных в char.
         * \param[in] n Количество данных.
         * \return Признак валидости запроса записи.
         */
        virtual bool addReadRequest( Address address, Quantity n ) = 0;

        //!Функция добавляет событие СТОП.
        virtual void addStopCondition() = 0;

        //!Функция добавляет автоматический повтор предыдущей операции в случае отсутсвия подтверждения.
        virtual bool addPollingAcknowledge() = 0;

        virtual ~ITransaction() = default;
    };

    struct IResult {
        //!Транзакция выполнена успешно.
        virtual bool isComplete() const noexcept = 0;
        //!Транзакция выполнена с ошибкой.
        virtual bool isError() const noexcept = 0;
        //!Получить данные транзакции.
        /*!Функция возвращает следующую порцию запрощенных данных.
         * Функция возвращает данные порциями того же размера, что и были запрошенны, последовательно в соотвествии с порядком запросов в транзакции.
         * \param[in] data Указатель на буфер для данных полученных в отвен на запрос.
         * \return Количество полученных данных или 0.
         */
        virtual ITransaction::Quantity getRequestedData( void * data ) = 0;

        virtual ~IResult() = default;
    };

    //!Запрос на выполнения транзакции.
    /*!Функция осуществляет запрос на выполнение транзакции.
     * Возвращаемый интерфейс необходимо вернуть модулю путем вызова функции perform, либо reset.
     * \param[in] freq Частота тактового сигнала для транзакции.
     * \param[in] frame_size Размер фрейма данных.
     * \return Интерфейс управления транзакцией, либо nullptr.
     */
    virtual ITransaction * request( Frequency freq, FrameSize frame_size ) = 0;
    //!Выполнение транзакции.
    /*!Подготовленная транзакция проходит валидацию на возможность выполнения и, в случае успеха, гарантированно будет обработана.
     * После вызова этой функции интерфейс транзакции считается не валидным.
     * Возвращаемый функцией интерфейс получения результата транзакции необходимо вернуть модулю путем вызова функции discard.
     * \param[in] transaction Интерфейс транзакции подлжешей выполнению.
     * \return Интерфейс управления результатом транзакции, в случае успешной валидации транзакции, либо nullptr.
     */
    virtual IResult * perform( ITransaction * & transaction ) = 0;
    //!Отброс результата.
    /*!Функция отбрасывает результат выполнения транзакции и освобождает выделенные ресурсы.
     * После вызова этой функции интерфейс получения результатов транзакции считается не валидным.
     * \param[in] result Интерфейс получения результата выполнения транзакции, подлежащий возврату.
     */
    virtual void discard( IResult * & result ) noexcept = 0;
    //!Отмена и сброс транзакции.
    /*!Функция возвращает интерфейс транзакции и освобождает выделенные ресурсы.
     * \param[in] transaction Интерфейс транзакции подлежащий возврату без выполнения.
     */
    virtual void reset( ITransaction * & transaction ) noexcept = 0;

    virtual void reset() noexcept = 0;

    virtual ~II2c() = default;

};

}


#endif /* SOURCE_PERIPHERAL_II2C_H_ */