EMoneyOperation.h

[詳解]

/// @file
/// @brief 電子マネーの各種操作を行うクラス EMoneyOperation のヘッダ。
///
/// Copyright(C)SEGA

#ifndef AMDAEMON_EMONEYOPERATION_H
#define AMDAEMON_EMONEYOPERATION_H

#include "amdaemon/env.h"
#include "amdaemon/EMoneyResult.h"
#include "amdaemon/EMoneyBrandId.h"

#include <utility>
#include <functional>
#include <cstdint>
#include <cstddef>

namespace amdaemon
{
/// @addtogroup g_emoney
/// @{

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

    /// @brief 電子マネーの各種操作を行うクラス。
    /// @see EMoney
    ///
    /// このクラスのインスタンスをアプリ側で直接生成することはできない。
    /// EMoney クラスのメンバ関数 EMoney#getOperation から取得すること。
    ///
    /// @par プラットフォーム情報
    /// - ALLSシリーズの電子マネー対応版SDKでのみ利用可能である。
    /// - 上記以外の場合、常に操作不可として扱われる。
    ///
    /// @par 支払操作未了時の挙動
    /// 通信不良等により支払操作が未了となった場合、
    /// ブランドによっては支払操作の再要求や残高照会要求が自動的に開始され、
    /// かざし待ち状態に移行する場合がある。
    /// @par
    /// その際、メンバ関数 #isBusy は true を返し続けるため、
    /// アプリ側からは支払操作が継続しているように見える。
    /// プレイヤー向けの情報は付属ディスプレイに随時表示されるため、
    /// 通常はアプリ側でこの状態をケアする必要はなく、
    /// 支払操作継続中であることを示す画面表示にしてしまって問題ない。
    /// @par
    /// 支払操作開始によるかざし待ちと操作未了時の自動処理によるかざし待ちを区別したい場合、
    /// メンバ関数 #isCancellable と #isHeldOver を組み合わせることで判別できる。
    /// メンバ関数 #isCancellable が true を返すならば何らかのかざし待ち状態であり、
    /// その際にメンバ関数 #isHeldOver が false を返すならば支払操作開始によるかざし待ち、
    /// true を返すならば操作未了時の自動処理によるかざし待ちとなる。
    /// (ただしPASELIは現状この方法で判別することはできず、他の判別方法も無い。)
    /// @par
    /// 支払操作が未了となり、その後の自動処理もすべて失敗もしくはキャンセルされた場合、
    /// 未了取引確認待ち状態に移行する。未了取引確認待ち状態については後述する。
    ///
    /// @par 未了取引確認待ち状態について
    /// 下記をすべて満たすと、未了取引確認待ち状態へ遷移する。
    /// @par
    /// - 通信不良等により、支払操作が未了となった。
    /// - 支払操作が未了となった際、
    ///   ブランドによっては支払操作の再要求や残高照会要求が自動的に開始される場合があるが、
    ///   それが正常に完了しなかった。またはキャンセルした。
    /// @par
    /// 未了取引確認待ち状態へ遷移すると、
    /// 付属ディスプレイには係員を呼び出して欲しい旨を伝えるメッセージが表示される。
    /// @par
    /// この状態はゲームテストモードを開始するまで解除されない。
    /// また、メンバ関数 #isDealAvailable が false を返すようになり、
    /// メンバ関数 #checkDisplay による付属ディスプレイ表示チェック以外の操作は開始できない。
    ///
    /// @par 操作実施中にゲームテストモードを開始した場合の挙動
    /// 各種操作を実施中に Sequence クラスのメンバ関数 Sequence#beginTest
    /// によってゲームテストモードを開始した場合、次のように動作する。
    /// @par
    /// - 操作がキャンセル可能な状態であれば、Daemonプロセスによって自動的にキャンセルされる。
    ///     - 自動キャンセルの挙動はメンバ関数 #cancel を呼び出した場合と同様である。
    /// - 操作がキャンセル不可な状態であれば、単にそのまま操作継続する。
    /// @par
    /// 操作継続となった場合、たとえゲームテストモード中であっても、
    /// EMoney クラスのメンバ関数 EMoney#setSoundHook で設定したフック関数は呼び出される。
    /// ゲームアプリはゲームテストモード中であってもサウンド再生/停止処理を実施すること。
    class EMoneyOperation
    {
    public:
        /// @brief コンストラクタ。
        /// @note アプリ側からは利用できない。
        explicit EMoneyOperation(InnerIndexHolder);

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

        /// @brief 取引操作を利用可能な状態であるか否かを取得する。
        /// @retval true  利用可能な状態である場合。
        /// @retval false 操作が無効な状態である場合。
        /// @see #canOperateDeal, #requestBalance, #payToCoin
        ///
        /// 下記をすべて満たす状態であれば true を返す。
        ///
        /// - 第3世代以降のAimeリーダーユニット、および付属ディスプレイが接続されている。
        /// - 端末売上管理システム上で端末IDと基板が紐付けられており、 "利用可" の状態である。
        /// - EMoney クラスのメンバ関数 EMoney#isServiceAlive が true を返す。
        /// - EMoney クラスのメンバ関数 EMoney#isAuthCompleted が true を返す。
        /// - EMoney クラスのメンバ関数 EMoney#getAvailableBrandCount が 1 以上を返す。
        /// - Error クラスのメンバ関数 Error#isOccurred が false を返す。
        /// - 未了取引確認待ち状態ではない。
        ///   未了取引確認待ち状態については EMoneyOperation クラスの説明を参照すること。
        ///
        /// この関数が false を返す場合、メンバ関数 #requestBalance および #payToCoin
        /// による取引操作を行うことはできない。
        /// 付属ディスプレイには取引が行えない旨が表示される。
        ///
        /// この関数が true を返す場合であっても、
        /// 他の操作を実施中の場合や締め処理中である場合は取引操作を開始できない。
        /// 取引操作を開始可能か否か調べるにはメンバ関数 #canOperateDeal を用いること。
        ///
        /// メンバ関数 #checkDisplay, #authTerminal, #removeTerminal については、
        /// この関数の返す値に関わらず利用可能である。
        bool isDealAvailable() const;

        /// @brief 取引操作を開始可能な状態であるか否かを取得する。
        /// @retval true  開始可能な状態である場合。
        /// @retval false 開始可能な状態ではない場合。
        /// @see #requestBalance, #payToCoin
        ///
        /// 下記をすべて満たす状態であれば true を返す。
        ///
        /// - メンバ関数 #isDealAvailable が true を返す。
        /// - メンバ関数 #isBusy が false を返す。
        /// - EMoney クラスのメンバ関数 EMoney#isReporting が false を返す。
        ///
        /// この関数で開始可否を判断できるのは、
        /// メンバ関数 #requestBalance および #payToCoin のみである。
        /// メンバ関数 #checkDisplay, #authTerminal, #removeTerminal については、
        /// 各関数の説明を参照すること。
        bool canOperateDeal() const;

        /// @brief いずれかの操作、あるいはそのキャンセルを実施中であるか否かを取得する。
        /// @retval true  いずれかの操作、あるいはそのキャンセルを実施中である場合。
        /// @retval false いずれの操作も実施していない場合。
        ///
        /// この関数が true を返す場合、他の操作を開始することはできない。
        bool isBusy() const;

        /// @brief 実施中の操作をキャンセル可能な状態であるか否かを取得する。
        /// @retval true  キャンセル可能な状態である場合。
        /// @retval false キャンセルできない状態であるか、操作実施中ではない場合。
        /// @see #cancel
        ///
        /// 操作を実施中であっても常にキャンセル可能なわけではない。
        /// 具体的なキャンセル可能タイミングについては各操作関数の説明を参照すること。
        bool isCancellable() const;

        /// @brief 実施中の操作のキャンセルを開始する。
        /// @retval true  キャンセル開始に成功した場合。
        /// @retval false キャンセル開始に失敗したか、キャンセルできない状態である場合。
        /// @see #isCancellable
        ///
        /// メンバ関数 #isCancellable が false を返す状態の場合、
        /// この関数は何も行わずに false を返す。
        ///
        /// この関数を呼び出しても即座にキャンセル完了となるわけではない。
        /// この関数の成功後にメンバ関数 #isBusy が
        /// false を返すようになって初めてキャンセル完了となる。
        ///
        /// キャンセル完了時、メンバ関数 #getResult はキャンセル結果を返す。
        /// 通常は成功となる。
        ///
        /// 操作を実施中であっても常にキャンセル可能なわけではない。
        /// 具体的なキャンセル可能タイミングについては各操作関数の説明を参照すること。
        bool cancel();

        /// @brief 実施中の操作でカードリーダーへのかざし操作が1回以上行われたか否かを取得する。
        /// @retval true  かざし操作が1回以上行われた場合。
        /// @retval false かざし操作が行われていないか、操作中ではない場合。
        ///
        /// 端末認証、残高照会、支払の操作において、
        /// カードリーダーが認証用カードまたは電子マネーデバイスを一度でも認識すると、
        /// それ以降 true を返すようになる。
        /// 一旦 true を返すようになると、操作が完了してメンバ関数 #isBusy が
        /// false を返すようになるまで、この関数の戻り値は true のままとなる。
        ///
        /// 通常ではかざし操作は一度しか行わないが、通信不良等により支払操作が未了となると、
        /// ブランドによっては支払操作の再要求や残高照会要求が自動的に開始され、
        /// 再度かざし待ち状態となる場合がある。
        /// その場合であっても、この関数の返す値が false に戻ることはない。
        ///
        /// 対象外の操作(端末撤去等)が行われている場合、この関数の返す値は不定値となる。
        bool isHeldOver() const;

        /// @brief 直近の操作を実施中にエラーが発生したか否かを取得する。
        /// @retval true  エラーが発生した場合。
        /// @retval false エラーが発生していない場合。
        ///
        /// いずれかの操作を開始すると、過去のエラー情報を破棄して false を返すようになる。
        /// 操作内容は問わない。(操作結果を返さないものを含む)
        ///
        /// 操作の実施中にエラーが発生すると true を返すようになる。
        bool isErrorOccurred() const;

        /// @brief 直近の操作、あるいはそのキャンセルの結果が存在するか否かを取得する。
        /// @retval true  直近の操作、あるいはそのキャンセルの結果が存在する場合。
        /// @retval false 結果が存在しない場合。
        ///
        /// getResult().valid() を返す。
        bool hasResult() const
        {
            return this->getResult().valid();
        }

        /// @brief 直近の操作、あるいはそのキャンセルの結果を取得する。
        /// @return
        ///     直近の操作、あるいはそのキャンセルの結果。
        ///     まだ一度も操作開始していない場合は無効値。
        ///
        /// いずれかの操作を開始すると、過去の操作結果を破棄して無効値を返すようになる。
        /// 操作内容は問わない。(操作結果を返さないものを含む)
        ///
        /// 操作が完了するか、もしくはキャンセルされると、その結果を返すようになる。
        /// ただし、操作内容が残高照会でも支払でもない場合は操作結果を返さない。
        ///
        /// 操作が成功した場合とエラーが発生した場合とでは設定内容が異なる。
        /// EMoneyResult クラスの説明を参照すること。
        const EMoneyResult& getResult() const
        {
            return _result;
        }

        /// @brief 付属ディスプレイの表示チェックを開始する。
        /// @retval true  操作開始に成功した場合。
        /// @retval false 操作開始に失敗した場合。
        ///
        /// メンバ関数 #isBusy が true を返す状態である場合、
        /// この関数は何も行わずに false を返す。
        ///
        /// この操作がエラー情報を返すことはない。
        /// 実際に問題があるか否かは付属ディスプレイの表示状態による。
        ///
        /// @par キャンセル可能タイミング
        /// 常にキャンセル可能である。
        bool checkDisplay();

        /// @brief 端末認証操作を開始する。
        /// @retval true  操作開始に成功した場合。
        /// @retval false 操作開始に失敗した場合。
        ///
        /// 下記のいずれかの状態である場合、この関数は何も行わずに false を返す。
        ///
        /// - メンバ関数 #isBusy が true を返す。
        /// - EMoney クラスのメンバ関数 EMoney#isReporting が true を返す。
        ///
        /// 操作開始に成功した場合であっても、
        /// サービスサーバが生存していない等の理由で操作に失敗する可能性があるため、
        /// 操作完了後は必ずメンバ関数 #isErrorOccurred によってエラーの有無を確認すること。
        ///
        /// アプリでは、ゲームテストモードに端末認証用の画面を用意し、
        /// オペレータの画面操作によってこの操作を開始すること。
        /// なお、操作を完了させるためには認証用カードをカードリーダーにかざす必要がある。
        ///
        /// 認証済みの端末であっても、
        /// 利用可能な電子マネーを追加する際には再度この操作を実施する必要があるため、
        /// 認証済みか否かに関わらず上記画面に遷移できるようにすること。
        ///
        /// @par キャンセル可能タイミング
        /// - 操作開始から認証用カードをかざすまでの間はキャンセル可能である。
        /// - カードリーダーが認証用カードを認識すると、それ以降はキャンセル不可となる。
        /// @par
        /// 現在キャンセル可能であるか否かはメンバ関数 #isCancellable によって判別すること。
        bool authTerminal();

        /// @brief 端末撤去操作を開始する。
        /// @retval true  操作開始に成功した場合。
        /// @retval false 操作開始に失敗した場合。
        ///
        /// 下記のいずれかの状態である場合、この関数は何も行わずに false を返す。
        ///
        /// - メンバ関数 #isBusy が true を返す。
        /// - EMoney クラスのメンバ関数 EMoney#isReporting が true を返す。
        ///
        /// 操作開始に成功した場合であっても、
        /// サービスサーバが生存していない等の理由で操作に失敗する可能性があるため、
        /// 操作完了後は必ずメンバ関数 #isErrorOccurred によってエラーの有無を確認すること。
        ///
        /// アプリでは、ゲームテストモードに端末撤去用の画面を用意し、
        /// オペレータの画面操作によってこの操作を開始すること。
        ///
        /// @par キャンセル可能タイミング
        /// 常にキャンセル不可である。
        bool removeTerminal();

        /// @brief 残高照会操作を開始する。
        /// @param[in] brandId ブランドID。
        /// @retval true  操作開始に成功した場合。
        /// @retval false 操作開始に失敗した場合。
        ///
        /// @exception Exception
        /// 引数 brandId に不正な値を指定した場合。
        ///
        /// メンバ関数 #canOperateDeal が false を返す場合や、
        /// 引数 brandId に指定したブランドが有効ではない場合、
        /// この関数は何も行わずに false を返す。
        ///
        /// @par キャンセル可能タイミング
        /// - 操作開始から電子マネーデバイスをかざすまでの間はキャンセル可能である。
        /// - カードリーダーが電子マネーデバイスを認識すると、それ以降はキャンセル不可となる。
        /// @par
        /// 現在キャンセル可能であるか否かはメンバ関数 #isCancellable によって判別すること。
        bool requestBalance(EMoneyBrandId brandId);

        /// @brief コイン購入支払操作を開始する。
        /// @param[in] playerIndex プレイヤーインデックス。
        /// @param[in] brandId ブランドID。
        /// @param[in] coin 購入するコイン数。
        /// @retval true  操作開始に成功した場合。
        /// @retval false 操作開始に失敗した場合。
        ///
        /// @exception Exception
        /// - 引数 playerIndex に有効プレイヤー数以上の値を指定した場合。
        ///   有効プレイヤー数は Core クラスのメンバ関数 Core#getPlayerCount で取得できる。
        /// - 引数 brandId に不正な値を指定した場合。
        /// - 引数 coin に 0 もしくは 99 より大きい値を指定した場合。
        ///
        /// 電子マネーを支払い、コインを購入する。
        /// 購入したコイン数などの情報はブックキーピングに記録される。
        ///
        /// 1コインあたりの金額はクレジット設定により決定される。
        /// Credit クラスのメンバ関数 Credit#getConfig から取得したクレジット設定の
        /// CreditConfig#coinAmount メンバを参照する事。
        ///
        /// 下記の場合、この関数は何も行わずに false を返す。
        ///
        /// - メンバ関数 #canOperateDeal が false を返す場合。
        /// - 引数 brandId に指定したブランドが有効ではない場合。
        /// - 現在ゲームテストモード中である場合。
        ///   ゲームテストモード状態の管理は Sequence クラスで行える。
        ///
        /// また、下記の場合はプロセス側で操作開始に失敗して false を返す。
        ///
        /// - クレジット機能が無効である場合。
        /// - コインを購入することで MAX CREDIT 値を超える場合。
        ///
        /// MAX CREDIT 値を超えずに購入可能なコイン数は、
        /// CreditUnit クラスのメンバ関数 CreditUnit#getAddableCoin によって取得できる。
        ///
        /// @code
        /// // 購入可能なコイン数を事前チェックしてから payToCoin を呼び出すサンプル。
        /// bool buyCoin(std::size_t playerIndex, EMoneyBrandId brandId, std::uint32_t coin)
        /// {
        ///     amdaemon::Credit credit;
        ///     amdaemon::EMoney eMoney;
        /// 
        ///     // (追加可能なコイン数 < 購入予定コイン数) なら購入不可
        ///     if (credit.getPlayer(playerIndex).getAddableCoin() < coin)
        ///     {
        ///         return false;
        ///     }
        /// 
        ///     return eMoney.getOperation().payToCoin(playerIndex, brandId, coin);
        /// }
        /// @endcode
        ///
        /// @par キャンセル可能タイミング
        /// - 操作開始から電子マネーデバイスをかざすまでの間はキャンセル可能である。
        /// - カードリーダーが電子マネーデバイスを認識すると、それ以降はキャンセル不可となる。
        /// - 支払操作が未了となった場合は再びキャンセル可能となる場合がある。
        ///   詳細は EMoneyOperation クラスの説明を参照すること。
        /// @par
        /// 現在キャンセル可能であるか否かはメンバ関数 #isCancellable によって判別すること。
        bool payToCoin(std::size_t playerIndex, EMoneyBrandId brandId, std::uint32_t coin);

    private:
        EMoneyResult _result;   ///< 操作結果。

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

/// @}
} // namespace amdaemon

#endif // AMDAEMON_EMONEYOPERATION_H