CanAck.h

[詳解]

/// @file
/// @brief CANボードから送信されたアクノリッジパケット情報を提供するクラス CanAck のヘッダ。
///
/// Copyright(C)SEGA

#ifndef AMDAEMON_CANACK_H
#define AMDAEMON_CANACK_H

#include "amdaemon/env.h"
#include "amdaemon/CanErrorReport.h"
#include "amdaemon/Exception.h"
#include "amdaemon/util/traits.h"

#include <type_traits>
#include <cstdint>
#include <cstddef>

namespace amdaemon
{
/// @addtogroup g_can
/// @{

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

    /// @brief CANボードから送信されたアクノリッジパケット情報を提供するクラス。
    /// @see CanTarget
    ///
    /// このクラスのインスタンスをアプリ側で直接生成することはできない。
    /// CanTarget クラスのメンバ関数 CanTarget#getAck から取得すること。
    ///
    /// CanTarget クラスから同じ命令コードのリクエストパケットを送信したり、
    /// Core クラスのメンバ関数 Core#execute 呼び出しによって新しいアクノリッジパケットを
    /// 受け取った時点で、インスタンスの各メンバ関数が返す情報は更新される。
    /// ある時点における情報を保持したい場合、各メンバ関数の戻り値をコピーしておくこと。
    ///
    /// メンバ関数 #isError が true を返す場合、
    /// そのインスタンスは当該コマンドのアクノリッジパケット情報ではなく、
    /// エラーレポート取得コマンド(命令コード値は CanErrorReportCommand)の
    /// アクノリッジパケット情報を返す。
    class CanAck
    {
    public:
        /// @brief コンストラクタ。
        /// @note アプリ側からは利用できない。
        CanAck(InnerIndexHolder, InnerIndexHolder, std::uint8_t);

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

        /// @brief パケットが存在するか否かを取得する。
        /// @retval true  存在する場合。
        /// @retval false 存在しない場合。
        ///
        /// この関数が false を返す場合、他のメンバ関数の返す値を利用してはならない。
        bool exists() const
        {
            return (this->getData() != nullptr);
        }

        /// @brief 命令コードを取得する。
        /// @return 命令コード。
        std::uint8_t getCommand() const
        {
            return _command;
        }

        /// @brief
        ///     このインスタンスがコマンド処理結果ではなく
        ///     エラーレポート情報を保持しているか否かを取得する。
        /// @retval true  エラーレポート情報を保持している場合。
        /// @retval false コマンド処理結果を保持している場合。(正常時)
        bool isError() const
        {
            return (this->getErrorReport() != CanErrorReport::None);
        }

        /// @brief エラーレポート種別を取得する。
        /// @return エラーレポート種別。エラーが発生していない場合は CanErrorReport::None 。
        CanErrorReport getErrorReport() const;

        /// @brief パケットデータを取得する。
        /// @return パケットデータ。パケットが存在しない場合は nullptr 。
        ///
        /// - メンバ関数 #isError が false を返す場合、
        ///   この関数は当該コマンドのパケットデータを返す。
        /// - メンバ関数 #isError が true を返す場合、
        ///   この関数はエラーレポート取得コマンド(命令コード値は CanErrorReportCommand)の
        ///   アクノリッジパケットデータを返す。
        ///     - 特に加工せずパケットデータをそのまま返すため、
        ///       1バイト目はメンバ関数 #getCommand の戻り値と等しくなり、
        ///       2バイト目はメンバ関数 #getErrorReport の戻り値と等しくなる。
        const void* getData() const;

        /// @brief パケットデータを指定した型の参照として取得する。
        /// @tparam Data パケットデータ型。後述の要件を満たす型でなければならない。
        /// @return パケットデータ。
        /// @see #getData
        ///
        /// @exception Exception
        /// パケットが存在しない場合。
        ///
        /// メンバ関数 #getData の戻り値を単純にキャストし、 const Data& 型として返す。
        /// 型 Data の const 修飾および volatile 修飾は取り除かれる。
        ///
        /// 型 Data は下記の要件をすべて満たす必要がある。
        ///
        /// - オブジェクト型(スカラ型、配列、クラス＆構造体、共用体のいずれか)である。
        /// - トリビアルコピー可能な型である。
        /// - ポインタ型ではない。
        /// - std::nullptr_t 型ではない。
        ///
        /// 要するに、安全に std::memcpy によるコピーが可能な型である必要がある。
        /// 1つでも満たしていない場合はコンパイルエラーとなる。
        template<class Data>
        auto getDataAs() const
            ->
            typename std::enable_if<
                ::amdaemon::util::IsBinaryCopyable<Data>::value,
                const typename std::remove_cv<Data>::type&>::type
        {
            const void* data = this->getData();
            if (data == nullptr)
            {
                AMDAEMON_RAISE_EXCEPTION_MSG(Operation, L"Packet is not exists.");
            }
            return *static_cast<const typename std::remove_cv<Data>::type*>(data);
        }

        /// @brief パケットデータサイズを取得する。
        /// @return パケットデータサイズ。コマンドによっては 0 の場合もある。
        std::size_t getDataSize() const;

    private:
        std::size_t _portIndex;     ///< ポート定義インデックス。
        std::size_t _targetIndex;   ///< ターゲット定義インデックス。
        std::uint8_t _command;      ///< 命令コード。

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

/// @}
} // namespace amdaemon

#endif // AMDAEMON_CANACK_H