CreditSpecialDevice.h

[詳解]

/// @file
/// @brief
///     ビデオゲームのクレジット処理に統合された特殊デバイスを操作するクラス
///     CreditSpecialDevice のヘッダ。
///
/// Copyright(C)SEGA

#ifndef AMDAEMON_CREDITSPECIALDEVICE_H
#define AMDAEMON_CREDITSPECIALDEVICE_H

#include "amdaemon/env.h"

namespace amdaemon
{
/// @addtogroup g_credit
/// @{

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

    /// @brief ビデオゲームのクレジット処理に統合された特殊デバイスを操作するクラス。
    ///
    /// このクラスのインスタンスをアプリ側で直接生成することはできない。
    /// Credit クラスのメンバ関数 Credit#getSpecialDevice から取得すること。
    ///
    /// 一部の関数は処理完了まで呼び出し元スレッドをブロックする。
    ///
    /// 現実装では、電子コインセレクター AS-6DB-S1 の操作のみをサポートする。
    ///
    /// @par 電子コインセレクター AS-6DB-S1 利用時の注意事項
    /// - Daemonプロセスの初期化完了時点ではロックアウトが有効になっている。
    ///     - 適宜メンバ関数 #lockout でロックアウト設定を行うこと。
    /// - デバイスエラー発生中、自動的にロックアウトが有効になる。
    ///     - デバイスエラーの中には進行停止エラーとはならないものも含まれる。
    ///       現在のロックアウト状態はメンバ関数 #isLockoutOn で確認すること。
    /// - デバイスエラー発生中はメンバ関数 #lockout でのロックアウト設定が必ず失敗する。
    ///     - デバイスエラーが内部でリセットされ、ロックアウト設定が成功するまで、
    ///       毎フレーム試行することが望ましい。
    class CreditSpecialDevice
    {
    public:
        /// @brief コンストラクタ。
        /// @note アプリ側からは利用できない。
        explicit CreditSpecialDevice(InnerIndexHolder);

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

        /// @brief 特殊デバイス機能を利用可能であるか否かを取得する。
        /// @retval true  利用可能である場合。
        /// @retval false 機能が無効である場合。
        ///
        /// 現実装では、電子コインセレクター AS-6DB-S1 の操作をサポートするか否かを返す。
        bool isAvailable() const;

        /// @brief 現在ロックアウトが有効であるか否かを取得する。
        /// @retval true  ロックアウトが有効である場合。
        /// @retval false ロックアウトが無効であるか、機能が無効である場合。
        ///
        /// デバイスの仕様により自動的にロックアウトが有効になる場合がある。
        /// 進行停止エラーとはならない場合もあるため、
        /// アプリからは突然ロックアウトされたように見える。
        ///
        /// この関数の戻り値を毎フレーム確認し、アプリの想定するロックアウト状態と
        /// 異なっている場合はメンバ関数 #lockout を用いてロックアウト設定を行うこと。
        /// その際、内部状態次第ではロックアウト設定に失敗する場合があるため、
        /// 成功するまで毎フレーム試行し続けること。
        bool isLockoutOn() const;

        /// @brief ロックアウト設定を行う。
        /// @param[in] on ロックアウトを有効にするならば true 。無効にするならば false 。
        /// @retval true  処理に成功した場合。
        /// @retval false 処理に失敗したか、機能が無効である場合。
        ///
        /// 毎フレーム呼び出されることを想定した設計になっている。
        ///
        /// 一度呼び出すと数フレームの間はロックアウト設定処理中となり、
        /// 処理中に再度呼び出した場合は何もせずに false を返す。
        ///
        /// ロックアウト設定処理中以外でも、
        /// 内部状態次第でロックアウト設定に失敗する場合があるため、
        /// 必ずこの関数の戻り値やメンバ関数 #isLockoutOn の戻り値を確認すること。
        bool lockout(bool on);

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

/// @}
} // namespace amdaemon

#endif // AMDAEMON_CREDITSPECIALDEVICE_H