EMoney.h

[詳解]

/// @file
/// @brief 電子マネー処理を提供するMonostateクラス EMoney のヘッダ。
///
/// Copyright(C)SEGA

#ifndef AMDAEMON_EMONEY_H
#define AMDAEMON_EMONEY_H

#include "amdaemon/env.h"
#include "amdaemon/EMoneyBrand.h"
#include "amdaemon/EMoneySound.h"
#include "amdaemon/EMoneyOperation.h"
#include "amdaemon/EMoneyResult.h"
#include "amdaemon/EMoneyReport.h"
#include "amdaemon/EMoneyDef.h"
#include "amdaemon/util/container.h"

#include <functional>
#include <vector>
#include <cstdint>
#include <cstddef>

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

    /// @brief 電子マネー処理を提供するMonostateクラス。
    ///
    /// Core クラスのメンバ関数 Core#execute 呼び出しによって内容が更新される。
    ///
    /// @par プラットフォーム情報
    /// - ALLSシリーズの電子マネー対応版SDKでのみ利用可能である。
    /// - 上記以外の場合、常にサービスサーバ非生存かつ各種項目数 0 として扱われる。
    ///
    /// @ingroup g_common
    class EMoney
    {
    public:
        // 下記は暗黙の定義を用いる。
        //EMoney() = default;
        //‾EMoney() = default;
        //EMoney(const EMoney&) = default;
        //EMoney& operator=(const EMoney&) = default;

        /// @brief 電子マネー機能を利用可能であるか否かを取得する。
        /// @retval true  利用可能である場合。
        /// @retval false 機能が無効である場合。
        bool isAvailable() const;

        /// @brief サウンドフック関数を設定する。
        /// @param[in] hook フック関数。
        /// @see EMoneySound
        ///
        /// この関数でフック関数(コールバック)を設定すると、
        /// 電子マネー用のサウンドを処理すべきタイミングでこのフック関数が呼び出される。
        ///
        /// 電子マネー用のサウンドは必ず処理しなければならないため、
        /// 必ずこの関数にフック関数を登録し、サウンド再生/停止処理を実施すること。
        ///
        /// フック関数の第1引数にはサウンド情報が渡される。
        ///
        /// - メンバ関数 EMoneySound#isStopRequired が false を返す場合、
        ///   メンバ関数 EMoneySound#getId や EMoneySound#getFilePath を基に、
        ///   対応するサウンドの再生処理を開始すること。
        /// - メンバ関数 EMoneySound#isStopRequired が true を返す場合、
        ///   電子マネー関連サウンドを再生中であればそれを即座に停止すること。
        ///
        /// EMoneySound クラスはコピー可能であるため、必要に応じてコピーしてもよい。
        ///
        /// フック関数未設定である場合、設定されるまでフック処理が保留される。
        ///
        /// サウンド再生に関しては、 EMoneySound クラスの説明も参照すること。
        void setSoundHook(std::function<void (const EMoneySound&)> hook);

        /// @brief サウンドフック関数を解除し、未設定状態に戻す。
        /// @see #setSoundHook
        ///
        /// フック関数未設定である場合、設定されるまでフック関数呼び出しが保留される。
        void resetSoundHook();

        /// @brief サービスサーバが生存しているか否かを取得する。
        /// @retval true  生存している場合。
        /// @retval false 生存が確認できないか、電子マネー機能が無効である場合。
        ///
        /// メンバ関数 #isAuthCompleted が false を返す場合、疎通確認を行えないため、
        /// 実際のサービスサーバ生存状態に関わらずこの関数は false を返す。
        bool isServiceAlive() const;

        /// @brief 端末認証を実施済みであるか否かを取得する。
        /// @return true  実施済みである場合。
        /// @return false 未実施であるか、電子マネー機能が無効である場合。
        /// @see EMoneyOperation#authTerminal
        bool isAuthCompleted() const;

        /// @brief 端末ID値を取得する。
        /// @return 端末ID値。端末認証未実施の場合は nullptr 。
        ///
        /// 最大文字数は amdaemon::MaxEMoneyTerminalIdLength 。終端文字を含まない。
        const wchar_t* getTerminalId() const;

        /// @brief 端末シリアル値を取得する。
        /// @return 端末シリアル値。端末認証未実施の場合は nullptr 。
        ///
        /// 最大文字数は amdaemon::MaxEMoneyTerminalSerialLength 。終端文字を含まない。
        const wchar_t* getTerminalSerial() const;

        /// @brief ブランドが有効であるか否かを取得する。
        /// @param[in] brandId ブランドID。
        /// @retval true  有効である場合。
        /// @retval false 無効である場合。
        ///
        /// 無効なブランドに対して残高照会や支払といった操作を行うことはできない。
        bool isBrandAvailable(EMoneyBrandId brandId) const;

        /// @brief 有効ブランド数を取得する。
        /// @return
        ///     有効ブランド数。
        ///     サービスサーバーの生存が確認できない場合や、端末認証未実施の場合は 0 。
        std::size_t getAvailableBrandCount() const;

        /// @brief 有効ブランド情報を取得する。
        /// @param[in] index 有効ブランドのインデックス。
        /// @return 有効ブランド情報。
        ///
        /// @exception Exception
        /// - 電子マネー機能が無効である場合。
        /// - 引数 index に有効ブランド数以上の値を指定した場合。
        ///   有効ブランド数はメンバ関数 #getAvailableBrandCount で取得できる。
        ///
        /// この関数で取得できるブランド情報は、表示優先順に並んでいる。
        /// アプリでブランド選択画面を表示する際は、
        /// この関数のインデックス順に従ってアイコン画像を並べること。
        const EMoneyBrand& getAvailableBrand(std::size_t index) const;

        /// @brief 有効ブランド情報配列を取得する。
        /// @return 有効ブランド情報配列。
        ///
        /// 範囲for文や各種アルゴリズム関数に渡すことを想定している。
        ///
        /// - 有効ブランド数を知りたいだけならばメンバ関数
        ///   #getAvailableBrandCount を用いること。
        /// - 特定の有効ブランド情報を取得したいだけならばメンバ関数
        ///   #getAvailableBrand を用いること。
        std::vector<std::reference_wrapper<const EMoneyBrand>> getAvailableBrands() const
        {
            return
                ::amdaemon::util::toContainer<decltype(this->getAvailableBrands())>(
                    this->getAvailableBrandCount(),
                    [this](std::size_t i) -> const EMoneyBrand&
                    {
                        return this->getAvailableBrand(i);
                    });
        }

        /// @brief 通信操作インスタンスを取得する。
        /// @return 通信操作インスタンス。
        EMoneyOperation& getOperation();

        /// @copydoc getOperation()
        const EMoneyOperation& getOperation() const;

        /// @brief 取引結果履歴の有効項目数を取得する。
        /// @return
        ///     取引結果履歴の有効項目数。最大値は amdaemon::MaxEMoneyDealResultCount 。
        ///     電子マネー機能が無効である場合は 0 。
        std::size_t getDealResultCount() const;

        /// @brief 取引結果履歴の項目を取得する。
        /// @param[in] index 取引結果履歴インデックス。
        /// @return 取引結果履歴項目。
        ///
        /// @exception Exception
        /// - 電子マネー機能が無効である場合。
        /// - 引数 index に有効項目数以上の値を指定した場合。
        ///   有効項目数はメンバ関数 #getDealResultCount で取得できる。
        ///
        /// インデックスの小さい要素ほど取引日時が新しい。
        const EMoneyResult& getDealResult(std::size_t index) const;

        /// @brief 取引結果履歴配列を取得する。
        /// @return 取引結果履歴配列。
        ///
        /// 範囲for文や各種アルゴリズム関数に渡すことを想定している。
        ///
        /// - 履歴の有効項目数を知りたいだけならばメンバ関数
        ///   #getDealResultCount を用いること。
        /// - 特定の履歴項目を取得したいだけならばメンバ関数 #getDealResult を用いること。
        std::vector<std::reference_wrapper<const EMoneyResult>> getDealResults() const
        {
            return
                ::amdaemon::util::toContainer<decltype(this->getDealResults())>(
                    this->getDealResultCount(),
                    [this](std::size_t i) -> const EMoneyResult&
                    {
                        return this->getDealResult(i);
                    });
        }

        /// @brief 締め処理中であるか否かを取得する。
        /// @retval true  締め処理中である場合。
        /// @retval false 締め処理中ではないか、電子マネー機能が無効である場合。
        ///
        /// 締め処理中である場合、 EMoneyOperation クラスの各種操作を開始することはできない。
        /// ただしメンバ関数 EMoneyOperation#checkDisplay だけは開始可能である。
        bool isReporting() const;

        /// @brief 締め処理結果履歴の有効項目数を取得する。
        /// @return
        ///     締め処理結果履歴の有効項目数。最大値は amdaemon::MaxEMoneyReportCount 。
        ///     電子マネー機能が無効である場合は 0 。
        std::size_t getReportCount() const;

        /// @brief 締め処理結果履歴の項目を取得する。
        /// @param[in] index 締め処理結果履歴インデックス。
        /// @return 締め処理結果履歴項目。
        ///
        /// @exception Exception
        /// - 電子マネー機能が無効である場合。
        /// - 引数 index に有効項目数以上の値を指定した場合。
        ///   有効項目数はメンバ関数 #getReportCount で取得できる。
        ///
        /// インデックスの小さい要素ほど処理日時が新しい。
        ///
        /// 現状、締め処理対象ブランドは楽天Edyのみとなっている。
        /// 集計期間中に対象ブランドでの支払いが一度も行われていない場合、支払件数や支払総額が
        /// 0 となるが、正常な動作である。
        const EMoneyReport& getReport(std::size_t index) const;

        /// @brief 締め処理結果履歴配列を取得する。
        /// @return 締め処理結果履歴配列。
        ///
        /// 範囲for文や各種アルゴリズム関数に渡すことを想定している。
        ///
        /// - 履歴の有効項目数を知りたいだけならばメンバ関数 #getReportCount を用いること。
        /// - 特定の履歴項目を取得したいだけならばメンバ関数 #getReport を用いること。
        std::vector<std::reference_wrapper<const EMoneyReport>> getReports() const
        {
            return
                ::amdaemon::util::toContainer<decltype(this->getReports())>(
                    this->getReportCount(),
                    [this](std::size_t i) -> const EMoneyReport&
                    {
                        return this->getReport(i);
                    });
        }
    };

/// @}
} // namespace amdaemon

#endif // AMDAEMON_EMONEY_H