SwitchOutput.h

[詳解]

/// @file
/// @brief OutputUnit クラスにスイッチ出力値を設定するラッパクラス SwitchOutput のヘッダ。
///
/// Copyright(C)SEGA

#ifndef AMDAEMON_SWITCHOUTPUT_H
#define AMDAEMON_SWITCHOUTPUT_H

#include "amdaemon/env.h"
#include "amdaemon/OutputId.h"

#include <cstddef>

namespace amdaemon
{
/// @addtogroup g_io
/// @{

    // OutputUnit クラスの前方宣言
    class OutputUnit;

    /// @brief OutputUnit クラスにスイッチ出力値を設定するラッパクラス。
    /// @see Output, OutputUnit
    ///
    /// 出力をビット単位で行いたい場合等に用いる。
    ///
    /// @code
    /// #include "amdaemon/Output.h"
    /// 
    /// namespace outputs
    /// {
    ///     // 定数宣言(実値は任意のソースファイルで定義する)
    ///     extern const amdaemon::OutputId Led1;
    ///     extern const amdaemon::OutputId Led2;
    /// }
    /// 
    /// void foo()
    /// {
    ///     amdaemon::Output output;
    /// 
    ///     // OutputUnit インスタンスから取得
    ///     auto led1 = output.getSystem().getSwitch(outputs::Led1);
    /// 
    ///     // LEDを先頭から2つ点灯
    ///     led1.set(true, 0);
    ///     led1.set(true, 1);
    /// 
    ///     // OutputUnit インスタンスから直接構築
    ///     amdaemon::SwitchOutput led2(output.getSystem(), outputs::Led2);
    /// 
    ///     // LEDを先頭から2つ消灯
    ///     led2.reset(0);
    ///     led2.reset(1);
    /// }
    /// @endcode
    class SwitchOutput
    {
    public:
        /// @brief コンストラクタ。
        /// @param[in] unit OutputUnit インスタンス参照。
        /// @param[in] id 出力識別ID。
        ///
        /// 引数 id に存在しない出力識別IDを指定した場合でも例外は発生しない。
        /// ただしメンバ関数 #exists は false を返す。
        SwitchOutput(OutputUnit& unit, const OutputId& id)
            :
            _unit(&unit),
            _id(id)
        {
        }

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

        /// @brief 出力が存在するか否かを取得する。
        /// @retval true  存在する場合。
        /// @retval false 存在しない場合。
        bool exists() const;

        /// @brief スイッチ出力のON/OFF状態を設定する。
        /// @param[in] bitIndex 対象ビットインデックス。
        /// @param[in] on ON状態にするならば true 。OFF状態にするならば false 。
        /// @param[in] forceUpdate
        ///     値が変化しない場合も更新要求するならば true 。既定値は false 。
        ///
        /// @exception Exception
        /// 引数 bitIndex に有効ビット範囲外の値を指定した場合。
        ///
        /// 出力が存在しない場合は何もしない。
        void set(std::size_t bitIndex, bool on, bool forceUpdate = false);

        /// @brief スイッチ出力をOFF状態に設定する。
        /// @param[in] bitIndex 対象ビットインデックス。
        /// @param[in] forceUpdate
        ///     値が変化しない場合も更新要求するならば true 。既定値は false 。
        ///
        /// @exception Exception
        /// 引数 bitIndex に有効ビット範囲外の値を指定した場合。
        ///
        /// 出力が存在しない場合は何もしない。
        inline void reset(std::size_t bitIndex, bool forceUpdate = false)
        {
            set(bitIndex, false, forceUpdate);
        }

        /// @brief 現在のスイッチ出力設定がON状態であるか否かを取得する。
        /// @param[in] bitIndex 対象ビットインデックス。
        /// @retval true  現在のスイッチ出力設定がON状態である場合。
        /// @retval false 現在のスイッチ出力設定がOFF状態であるか、出力が存在しない場合。
        ///
        /// 現在ライブラリ内で保持している値を返す。
        /// 起動直後などは、実デバイスにこの値が設定されているとは限らない。
        bool isCurrentOn(std::size_t bitIndex) const;

    private:
        OutputUnit* _unit;  ///< OutputUnit インスタンス参照。
        OutputId _id;       ///< 出力識別ID。
    };

/// @}
} // namespace amdaemon

#endif // AMDAEMON_SWITCHOUTPUT_H