UsbIOUniqueOutput.h

[詳解]

/// @file
/// @brief USB I/O のユニーク出力処理を行うクラス UsbIOUniqueOutput のヘッダ。
///
/// Copyright(C)SEGA

#ifndef AMDAEMON_USBIOUNIQUEOUTPUT_H
#define AMDAEMON_USBIOUNIQUEOUTPUT_H

#include "amdaemon/env.h"
#include "amdaemon/RequestState.h"
#include "amdaemon/util/traits.h"

#include <algorithm>
#include <type_traits>
#include <vector>
#include <cstdint>
#include <cstddef>

namespace amdaemon
{
/// @addtogroup g_usbio
/// @{

    // 内部クラスの前方宣言
    class InnerIndexHolder;

    /// @brief USB I/O のユニーク出力処理を行うクラス。
    /// @see UsbIO, UsbIONode
    ///
    /// このクラスのインスタンスをアプリ側で直接生成することはできない。
    /// UsbIONode クラスのメンバ関数 UsbIONode#getUniqueOutput から取得すること。
    ///
    /// ユニークコマンドによる USB I/O のインタラプト出力を行う。
    /// Daemonプロセスの設定ファイルで指定した命令コードのみがサポートされる。
    class UsbIOUniqueOutput
    {
    public:
        /// 最大データサイズ。
        static const std::size_t MaxDataSize = 62;

    public:
        /// @brief コンストラクタ。
        /// @note アプリ側からは利用できない。
        explicit UsbIOUniqueOutput(InnerIndexHolder);

        // 下記は暗黙の定義を用いる。
        //‾UsbIOUniqueOutput();

        /// @brief 指定した命令コードがサポートされているか否かを取得する。
        /// @param[in] command 命令コード。
        /// @retval true  サポートされている場合。
        /// @retval false サポートされていない場合。
        ///
        /// Daemonプロセスの設定ファイルで指定した命令コードであれば true を返す。
        bool isSupported(std::uint8_t command) const;

        /// @brief ユニークコマンドの出力値を設定する。
        /// @param[in] command 命令コード。
        /// @param[in] data 出力データ。不要ならば nullptr を指定可能。
        /// @param[in] dataSize 出力データサイズ。 #MaxDataSize 以下。データが不要ならば 0 。
        /// @return 要求状態値。
        ///
        /// @exception Exception
        /// - 引数 command にサポートされていない命令コードを指定した場合。
        /// - 引数 data に nullptr を指定した上で引数 dataSize に 0 以外の値を指定した場合。
        /// - 引数 dataSize に #MaxDataSize より大きい値を指定した場合。
        ///
        /// この関数を呼び出しても即座に出力されるわけではない。
        /// 反映状況は戻り値の要求状態値で確認できる。
        ///
        /// この関数を同一フレーム内で複数回呼びだした場合、
        /// 最後の呼び出し時に指定した値のみが実際の更新要求に使われる。
        RequestState set(std::uint8_t command, const void* data, std::size_t dataSize);

        /// @brief ユニークコマンドの出力値を設定する。
        /// @param[in] command 命令コード。
        /// @param[in] data 出力データ。
        /// @param[in] dataSize
        ///     出力データサイズ。既定値は SIZE_MAX (std::size_t 型の最大値)。
        ///     この値と data.size() のうち小さい方の値が実際のサイズとして利用される。
        /// @return 要求状態値。
        ///
        /// @exception Exception
        /// - 引数 command にサポートされていない命令コードを指定した場合。
        /// - 引数 dataSize に #MaxDataSize より大きい値を指定し、
        ///   かつ引数 data の要素数も #MaxDataSize より大きい場合。
        ///
        /// 出力データを可変長配列型で指定するオーバロード。
        /// 挙動は
        /// set(std::uint8_t, const void*, std::size_t)
        /// オーバロードに準ずる。
        RequestState set(
            std::uint8_t command,
            const std::vector<std::uint8_t>& data,
            std::size_t dataSize = SIZE_MAX)
        {
            return this->set(command, data.data(), std::min(dataSize, data.size()));
        }

        /// @brief ユニークコマンドの出力値を設定する。
        /// @tparam Data 出力データ型。後述の要件を満たす型でなければならない。
        /// @param[in] command 命令コード。
        /// @param[in] data 出力データ。
        /// @param[in] dataSize
        ///     出力データサイズ。既定値は sizeof(Data) 。
        ///     この値と sizeof(data) のうち小さい方の値が実際のサイズとして利用される。
        /// @return 要求状態値。
        ///
        /// @exception Exception
        /// - 引数 command にサポートされていない命令コードを指定した場合。
        /// - 引数 dataSize に #MaxDataSize より大きい値を指定し、
        ///   かつ sizeof(data) も #MaxDataSize より大きい場合。
        ///
        /// 出力データを任意のデータ型(固定長配列等)で指定するオーバロード。
        /// 挙動は
        /// set(std::uint8_t, const void*, std::size_t)
        /// オーバロードに準ずる。
        ///
        /// 型 Data から参照性を取り除いた型(例えば型 Data が int& ならば int)は
        /// 下記の要件をすべて満たす必要がある。
        ///
        /// - オブジェクト型(スカラ型、配列、クラス＆構造体、共用体のいずれか)である。
        /// - トリビアルコピー可能な型である。
        /// - ポインタ型ではない。
        /// - std::nullptr_t 型ではない。
        ///
        /// 要するに、安全に std::memcpy によるコピーが可能な型である必要がある。
        /// 1つでも満たしていない場合はコンパイルエラーとなる。
        template<class Data>
        auto set(
            std::uint8_t command,
            Data&& data,
            std::size_t dataSize = sizeof(Data))
            ->
            typename std::enable_if<
                ::amdaemon::util::IsBinaryCopyable<
                    typename std::remove_reference<Data>::type>::value,
                RequestState>::type
        {
            return this->set(command, &data, std::min(dataSize, sizeof(Data)));
        }

        /// @brief ユニークコマンドの出力値を設定する。
        /// @param[in] command 命令コード。
        /// @return 要求状態値。
        ///
        /// @exception Exception
        /// 引数 command にサポートされていない命令コードを指定した場合。
        ///
        /// 出力データを持たないユニークコマンド用のオーバロード。
        /// 挙動は
        /// set(std::uint8_t, const void*, std::size_t)
        /// オーバロードに準ずる。
        RequestState set(std::uint8_t command)
        {
            return this->set(command, nullptr, 0);
        }

        /// @brief 現在設定されている出力データを取得する。
        /// @param[in] command 命令コード。
        /// @return 現在設定されている出力データ。データサイズは #MaxDataSize 。
        ///
        /// @exception Exception
        /// 引数 command にサポートされていない命令コードを指定した場合。
        ///
        /// 現在ライブラリ内で保持している出力データを返す。
        /// 起動直後などは、実デバイスにこの値が設定されているとは限らない。
        const void* getCurrent(std::uint8_t command) const;

    private:
        std::size_t _nodeIndex; ///< ノードインデックス。

    private:
        // コピー禁止
        UsbIOUniqueOutput(const UsbIOUniqueOutput&);              // 宣言のみ
        UsbIOUniqueOutput& operator=(const UsbIOUniqueOutput&);   // 宣言のみ
    };

/// @}
} // namespace amdaemon

#endif // AMDAEMON_USBIOUNIQUEOUTPUT_H