AimeUnit.h

[詳解]

/// @file
/// @brief Aimeリーダー単体の処理を提供するクラス AimeUnit のヘッダ。
///
/// Copyright(C)SEGA

#ifndef AMDAEMON_AIMEUNIT_H
#define AMDAEMON_AIMEUNIT_H

#include "amdaemon/env.h"
#include "amdaemon/AimeResult.h"
#include "amdaemon/AimeErrorInfo.h"
#include "amdaemon/AimeCommand.h"
#include "amdaemon/AimeConfirm.h"
#include "amdaemon/AimeLedStatus.h"
#include "amdaemon/deprecated.h"

#include <cstddef>

namespace amdaemon
{
/// @addtogroup g_aime
/// @{

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

    /// @brief Aimeリーダー単体の処理を提供するクラス。
    /// @see Aime
    ///
    /// このクラスのインスタンスをアプリ側で直接生成することはできない。
    /// Aime クラスのメンバ関数 Aime#getUnit から取得すること。
    ///
    /// 一部の関数は処理完了まで呼び出し元スレッドをブロックする。
    ///
    /// @par UID値読み取り手順
    /// -# メンバ関数 #start を、引数に AimeCommand::Scan を渡して呼び出す。
    /// -# 下記のいずれかの状態になるまで待機する。
    ///     - メンバ関数 #hasConfirm が true を返す。
    ///     - メンバ関数 #isBusy が false を返す。
    /// -# メンバ関数 #hasConfirm が true を返す場合はプレイヤーへの要確認事項がある。
    ///     - メンバ関数 #getConfirm で内容を確認し、アプリ側で適切な確認表示を行う。
    ///     - プレイヤーが承諾した場合はメンバ関数 #acceptConfirm を呼び出し、再び待機する。
    ///     - プレイヤーが拒否した場合はメンバ関数 #cancel を呼び出し、処理を中断する。
    /// -# メンバ関数 #isBusy が false を返す場合は処理が完了している。
    /// -# メンバ関数 #hasError が true を返す場合はエラーが発生している。
    ///    メンバ関数 #getErrorInfo でエラー情報を取得し、アプリ側で適切に処理する。
    /// -# メンバ関数 #getResult で結果情報を得る。
    ///    処理に成功していれば getResult().getAimeId() によってUID値を取得できる。
    ///
    /// @par ポーリング処理途中の結果情報取得
    /// メンバ関数 #start 呼び出しによるポーリング処理途中であっても、
    /// 内部フェーズの進行により下記のように情報が取得可能になる。
    /// @par
    /// - hasResult() == true である場合(即ち getResult().valid() == true である場合)、
    ///   getResult().isReaderDetected() の値は有効である。
    /// - getResult().getOfflineId().valid() == true である場合、
    ///   getResult().getOfflineId(), getResult().isMobile() の値は有効である。
    /// - getResult().getAccessCode().valid() == true である場合、
    ///   getResult().getAccessCode() の値は有効である。
    /// - getResult().getAimeId().valid() == true である場合、
    ///   getResult().getAimeId(), getResult().isPortalRegistered(),
    ///   getResult().isSegaIdRegistered() の値は有効である。
    /// @par
    /// エラーが発生した場合も、エラー発生手前までの情報は取得可能である。
    ///
    /// @par Daemonプロセス初期化時のAimeリーダー接続チェック
    /// - Daemonプロセスの初期化時、Aimeリーダーの接続チェックが自動的に開始される。
    ///     - 初期化時とは、Daemonプロセス起動時と、ゲームテストモード終了時を指す。
    ///       ゲームテストモード状態の設定は Sequence クラスで行う。
    /// - 接続チェックが完了すると hasResult() == true となり、
    ///   getResult().isReaderDetected() によってチェック結果を取得できる。
    /// - 通常の初期化時は即座に接続チェックが開始されるが、
    ///   Aimeリーダーのファームウェア更新処理が必要な場合はそちらが優先され、
    ///   ファームウェア更新処理が完了してから接続チェックが行われる。
    ///     - ファームウェア更新処理中であるか否かは Aime クラスのメンバ関数
    ///       Aime#isFirmUpdating で判別できる。
    ///
    /// @par LED点灯処理
    /// - 通常シーケンスでの明示的なLED点灯処理にはメンバ関数 #setLedStatus を用いること。
    /// - ゲームテストモードでのLED点灯確認処理にはメンバ関数 #setLed を用いること。
    /// - Daemonプロセスは下記のLED点灯処理を自動で行う。
    ///     - ポーリング処理によってAimeリーダーの接続が確認できた時、
    ///       @ref #setLedStatus "setLedStatus"(AimeLedStatus::Scanning)
    ///       相当のLED白点灯処理を行う。
    ///     - ポーリング処理中にエラーが発生し、そのエラーカテゴリが
    ///       AimeErrorCategory::Warning である場合、
    ///       @ref #setLedStatus "setLedStatus"(AimeLedStatus::Error)
    ///       相当のLED赤点灯処理を行う。
    /// - 上記以外のLED自動点灯処理は一切行わない。
    ///     - たとえ読み取りに成功した場合であっても、ゲーム固有サーバとの通信成否等によって
    ///       点灯させるべきLED色が異なるため、自動化することができない。
    /// - 基本的にはAime作成基準に準拠し、例えば下記のように実装すること。
    ///     - 次の場合は @ref #setLedStatus "setLedStatus"(AimeLedStatus::Success) を呼び出す。
    ///         - 読み取り成功し、各種ネットワークサービスも正常に受けられる場合。
    ///     - 次の場合は @ref #setLedStatus "setLedStatus"(AimeLedStatus::Warning) を呼び出す。
    ///         - 読み取り成功したが、一部ネットワークサービスを受けられない状態の場合。
    ///         - 読み取り失敗したが、 AimeOfflineId を用いたオフラインプレイを行える場合。
    ///     - 次の場合は @ref #setLedStatus "setLedStatus"(AimeLedStatus::Error) を呼び出す。
    ///         - 読み取り失敗し、黄点灯および自動赤点灯の条件を満たさない場合。
    /// - 上記のLED点灯処理が完了してから続けてポーリング処理等を行いたい場合、
    ///   メンバ関数 #getLedStatus で現在のLED点灯ステータスを毎フレーム確認し、
    ///   ステータスが AimeLedStatus::None に戻るまで待機すること。
    class AimeUnit
    {
    public:
        /// @brief コンストラクタ。
        /// @note アプリ側からは利用できない。
        explicit AimeUnit(InnerIndexHolder);

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

    public:
        // ポーリング

        /// @brief ポーリング処理を開始する。
        /// @param[in] command ポーリング処理コマンド。
        /// @retval true  正常にポーリング開始できた場合。
        /// @retval false ポーリング開始できなかった場合。
        ///
        /// @exception Exception
        /// 引数 command に不正な値を指定した場合。
        ///
        /// 下記のいずれかを満たす場合、この関数は即座に false を返す。
        ///
        /// - 既にポーリング処理中または中断処理中である場合。
        ///   即ちメンバ関数 #isBusy が true を返す場合。
        /// - ファームウェア更新処理中である場合。
        ///   即ち Aime クラスのメンバ関数 Aime#isFirmUpdating が true を返す場合。
        ///
        /// Daemonプロセスがポーリング開始するまで呼び出し元スレッドをブロックする。
        ///
        /// 正常にポーリング開始された場合、開始直後は下記のようになる。
        ///
        /// - メンバ関数 #isBusy は true を返す。
        /// - メンバ関数 #hasError は false を返す。
        /// - メンバ関数 #hasResult は false を返す。
        ///
        /// ポーリングが進むことでこれらのメンバ関数が返す値は変化する。
        /// 詳細は各メンバ関数の説明を参照すること。
        bool start(AimeCommand command);

        /// @brief ポーリング処理の中断を開始する。
        /// @retval true  正常に中断開始できた場合。
        /// @retval false 中断開始できなかった場合。
        ///
        /// この関数は中断開始するのみであり、呼び出しただけでは中断完了しない。
        /// メンバ関数 #isBusy が false を返すようになって初めて中断完了となる。
        ///
        /// 下記のいずれかを満たす場合、この関数は即座に false を返す。
        ///
        /// - ポーリング処理中ではない場合。
        ///   即ちメンバ関数 #isBusy が false を返す場合。
        /// - ファームウェア更新の実処理中である場合。
        ///   即ち Aime クラスのメンバ関数 Aime#isFirmUpdating が true を返す場合。
        ///
        /// 中断開始済みかつ中断未完了の状態でこの関数を呼び出した場合、
        /// この関数は true を返すが、内部的には何も行われない。
        ///
        /// Daemonプロセスが処理完了するまで呼び出し元スレッドをブロックする。
        bool cancel();

        /// @brief ポーリング処理中または中断処理中であるか否かを取得する。
        /// @retval true  ポーリング処理中または中断処理中である場合。
        /// @retval false ポーリング処理中でも中断処理中でもない場合。
        ///
        /// ポーリング処理中であっても各メンバ関数が返す値は変化する場合がある。
        /// 詳細は各メンバ関数の説明を参照すること。
        bool isBusy() const;

        /// @brief ポーリング処理中または中断処理中の処理コマンドを取得する。
        /// @return ポーリング処理中または中断処理中の処理コマンド。
        /// @see isBusy
        ///
        /// ポーリング処理中または中断処理中ではない場合、この関数は不定値を返す。
        AimeCommand getBusyCommand() const;

        /// @brief Aime登録に関する要確認事項が存在するか否かを取得する。
        /// @retval true  要確認事項が存在する場合。
        /// @retval false 要確認事項が存在しない場合。
        ///
        /// 条件式 (getConfirm() != AimeConfirm::None) の結果を返す。
        ///
        /// メンバ関数 #start を AimeCommand::Scan を引数として呼び出した後、
        /// そのポーリング処理中にこの関数が true を返す場合がある。
        ///
        /// リーダーにかざされたAimeがFeliCaDBやAimeDBに未登録である場合、
        /// それらのDBへ登録して構わないかプレイヤーに確認を取る必要がある。
        /// そういった要確認事項が発生した場合にこの関数が true を返す。
        ///
        /// 具体的な確認事項はメンバ関数 #getConfirm で取得できる。
        bool hasConfirm() const
        {
            return (getConfirm() != AimeConfirm::None);
        }

        /// @brief Aime登録に関する要確認事項を取得する。
        /// @return Aime登録に関する要確認事項。存在しない場合は AimeConfirm::None 。
        ///
        /// メンバ関数 #hasConfirm が true を返す場合、この関数によって具体的な
        /// 確認事項を取得し、アプリ側で適切な確認画面表示を行う。
        ///
        /// その結果、確認事項が承諾された場合はメンバ関数 #acceptConfirm を呼び出して
        /// ポーリング処理を継続すること。
        /// 拒否された場合はメンバ関数 #cancel を呼び出してポーリング処理を中断すること。
        AimeConfirm getConfirm() const;

        /// @brief Aime登録に関する要確認事項が承諾されたことを通知する。
        /// @retval true  正常に通知できた場合。
        /// @retval false 通知できなかった場合。
        ///
        /// メンバ関数 #getConfirm によって取得できる要確認事項に対し、
        /// プレイヤーがその内容を承諾した場合にこの関数を呼び出すこと。
        /// この関数を呼び出すことでポーリング処理が継続される。
        ///
        /// 要確認事項が存在しない場合は即座に false を返す。
        ///
        /// Daemonプロセスが通知を受理するまで呼び出し元スレッドをブロックする。
        bool acceptConfirm();

        /// @brief ポーリング処理の結果が存在するか否かを取得する。
        /// @retval true  ポーリング処理の結果が存在する場合。
        /// @retval false ポーリング処理の結果が存在しない場合。
        ///
        /// getResult().valid() を返す。
        ///
        /// ポーリング処理中であっても、途中経過として結果が設定される場合がある。
        /// そのため、この関数の戻り値でポーリング処理の完了判定を行ってはならない。
        /// ポーリング処理の完了判定はメンバ関数 #isBusy で行うこと。
        bool hasResult() const
        {
            return getResult().valid();
        }

        /// @brief ポーリング処理の結果を取得する。
        /// @return ポーリング処理の結果。
        ///
        /// メンバ関数 #start 呼び出しによるポーリング処理中であっても、
        /// 内部的なフェーズ完了ごとに情報が更新される。
        /// 例えば AimeCommand::Scan を引数としてメンバ関数 #start を呼び出した場合、
        /// 下記のタイミングで情報が更新される。
        ///
        /// - Aimeリーダーの接続確認が完了した時。
        /// - オフラインID情報(アクセスコードまたはFeliCaID)の取得が完了した時。
        ///
        /// メンバ関数 #isBusy が false を返す場合、この関数も最終的な結果を返す。
        ///
        /// また、ポーリング処理中にエラーが発生した場合や中断された場合であっても、
        /// 成功済みの内部フェーズ分の情報は取得可能である。
        const AimeResult& getResult() const
        {
            return _result;
        }

        /// @brief ポーリング処理中にエラーが発生したか否かを取得する。
        /// @retval true  エラーが発生した場合。
        /// @retval false エラーが発生していない場合。
        ///
        /// getErrorInfo().isOccurred() を返す。
        bool hasError() const
        {
            return getErrorInfo().isOccurred();
        }

        /// @brief ポーリング処理中に発生したエラー情報を取得する。
        /// @return エラー情報。
        const AimeErrorInfo& getErrorInfo() const
        {
            return _errorInfo;
        }

    public:
        // LED制御

        /// @brief 現在のLED点灯ステータスを取得する。
        /// @return 現在のLED点灯ステータス。
        ///
        /// メンバ関数 #setLedStatus で設定したか、
        /// もしくはDaemonプロセスが自動で設定したLED点灯ステータスを取得できる。
        ///
        /// AimeLedStatus::Scanning 以外の点灯ステータスは、一定時間点灯後に自動で消灯して
        /// AimeLedStatus::None を返すようになる。
        /// そのため、LEDが自動消灯するまで待機するためにこの関数を利用することもできる。
        AimeLedStatus getLedStatus() const;

        /// @brief LED点灯ステータスを設定する。
        /// @param[in] status 要求するLED点灯ステータス。
        /// @retval true  正常に処理要求できた場合。
        /// @retval false 処理要求に失敗した場合。
        ///
        /// @exception Exception
        /// 引数 status に不正な値を指定した場合。
        ///
        /// LED点灯処理の詳細は、当クラスの説明およびAime作成基準を参照すること。
        ///
        /// 引数 status に AimeLedStatus::Scanning 以外の点灯ステータスを渡した場合、
        /// 一定時間点灯後にDaemonプロセスが自動で消灯処理を行い、点灯ステータスを
        /// AimeLedStatus::None に移行させる。
        /// そのため明示的に消灯処理を行う必要はない。
        ///
        /// ファームウェア更新処理中である場合、この関数は即座に false を返す。
        /// 更新処理中であるか否かは Aime クラスのメンバ関数
        /// Aime#isFirmUpdating で取得できる。
        ///
        /// Daemonプロセスが処理完了するまで呼び出し元スレッドをブロックする。
        bool setLedStatus(AimeLedStatus status);

        /// @brief LEDの点灯状態をRGB別に設定する。
        /// @param[in] onR 赤成分を点灯させるならば true 。
        /// @param[in] onG 緑成分を点灯させるならば true 。
        /// @param[in] onB 青成分を点灯させるならば true 。
        /// @retval true  正常に点灯させることができた場合。
        /// @retval false 処理に失敗した場合。
        /// @note ゲームテストモード用。
        ///
        /// この関数はゲームテストモードでのLED点灯確認処理のために用意されている。
        /// 通常シーケンスではこちらではなくメンバ関数 #setLedStatus を用いること。
        ///
        /// この関数が成功すると、LED点灯ステータスは AimeLedStatus::None となる。
        ///
        /// ファームウェア更新処理中である場合、この関数は即座に false を返す。
        /// 更新処理中であるか否かは Aime クラスのメンバ関数
        /// Aime#isFirmUpdating で取得できる。
        ///
        /// Daemonプロセスが処理完了するまで呼び出し元スレッドをブロックする。
        bool setLed(bool onR, bool onG, bool onB);

    private:
        std::size_t _unitIndex;     ///< ユニットインデックス。
        AimeResult _result;         ///< ポーリング結果。
        AimeErrorInfo _errorInfo;   ///< ポーリングエラー情報。

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

/// @}
} // namespace amdaemon

#endif // AMDAEMON_AIMEUNIT_H