Aime.h

[詳解]

/// @file
/// @brief Aime関連処理を提供するMonostateクラス Aime のヘッダ。
///
/// Copyright(C)SEGA

#ifndef AMDAEMON_AIME_H
#define AMDAEMON_AIME_H

#include "amdaemon/env.h"
#include "amdaemon/AimeUnit.h"
#include "amdaemon/AimeLogStatus.h"
#include "amdaemon/AimeId.h"
#include "amdaemon/AimeCampaignInfo.h"
#include "amdaemon/AimeCampaignProgress.h"
#include "amdaemon/AimeDef.h"
#include "amdaemon/RequestState.h"
#include "amdaemon/util/container.h"

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

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

    /// @brief Aime関連処理を提供するMonostateクラス。
    ///
    /// Core クラスのメンバ関数 Core#execute 呼び出しによって内容が更新される。
    ///
    /// @par ライブラリ利用アプリで実装すべきこと(Aime利用タイトルのみ)
    /// - メンバ関数 #isFirmUpdating の戻り値が true の間はポーリング処理等を行えない。
    ///   必要に応じてファームウェア更新処理中であることを示す画面表示を行うこと。
    ///     - メンバ関数 #getFirmUpdateProgress で更新処理の進捗率を取得できる。
    ///     - 戻り値が false になった後は、稼働中に再度 true になることはない。
    ///
    /// @par UID値読み取り手順
    /// AimeUnit クラスの説明を参照すること。
    ///
    /// @ingroup g_common
    class Aime
    {
    public:
        // 下記は暗黙の定義を用いる。
        //Aime() = default;
        //Aime(const Aime&) = default;
        //‾Aime() = default;
        //Aime& operator=(const Aime&) = default;

        /// @brief Aime機能を利用可能であるか否かを取得する。
        /// @retval true  利用可能である場合。
        /// @retval false 機能が無効である場合。
        ///
        /// 条件式 (getUnitCount() > 0) の結果を返す。
        bool isAvailable() const;

        /// @brief ファームウェア更新の実処理中であるか否かを取得する。
        /// @retval true  ファームウェア更新の実処理中である場合。
        /// @retval false ファームウェア更新の実処理中ではない場合。
        ///
        /// Daemonプロセスによるファームウェア更新処理中であれば true を返す。
        bool isFirmUpdating() const;

        /// @brief ファームウェア更新の進捗率を取得する。
        /// @return ファームウェア更新の進捗率を表すパーセント値。
        /// @see isFirmUpdating
        ///
        /// ファームウェア更新処理中ではない場合、この関数は不定値を返す。
        /// Aimeリーダーユニットが複数接続されている場合、全体での進捗率を返す。
        float getFirmUpdateProgress() const;

        /// @brief AimeDBサーバが生存しているか否かを取得する。
        /// @retval true  生存している場合。
        /// @retval false 生存が確認できない場合。
        bool isDBAlive() const;

        /// @brief Aimeリーダーユニット数を取得する。
        /// @return Aimeリーダーユニット数。
        std::size_t getUnitCount() const;

        /// @brief Aimeリーダーユニットインスタンスを取得する。
        /// @param[in] unitIndex ユニットインデックス。
        /// @return Aimeリーダーユニットインスタンス。
        ///
        /// @exception Exception
        /// 引数 unitIndex にユニット数以上の値を指定した場合。
        /// ユニット数はメンバ関数 #getUnitCount で取得できる。
        AimeUnit& getUnit(std::size_t unitIndex);

        /// @copydoc getUnit
        const AimeUnit& getUnit(std::size_t unitIndex) const;

        /// @brief Aimeリーダーユニットインスタンス配列を取得する。
        /// @return Aimeリーダーユニットインスタンス配列。
        ///
        /// 範囲for文や各種アルゴリズム関数に渡すことを想定している。
        ///
        /// - ユニット数を知りたいだけならばメンバ関数 #getUnitCount を用いること。
        /// - 特定ユニットを取得したいだけならばメンバ関数 #getUnit を用いること。
        std::vector<std::reference_wrapper<AimeUnit>> getUnits()
        {
            return
                ::amdaemon::util::toContainer<decltype(this->getUnits())>(
                    this->getUnitCount(),
                    [this](std::size_t i) -> AimeUnit& { return this->getUnit(i); });
        }

        /// @copydoc getUnits
        std::vector<std::reference_wrapper<const AimeUnit>> getUnits() const
        {
            return
                ::amdaemon::util::toContainer<decltype(this->getUnits())>(
                    this->getUnitCount(),
                    [this](std::size_t i) -> const AimeUnit& { return this->getUnit(i); });
        }

        /// @brief ログ送信開始を要求する。
        /// @param[in] aimeId ログ送信対象のUID値。
        /// @param[in] status ログステータス。
        /// @return 要求状態値。
        /// @see Sequence#beginPlay
        ///
        /// @exception Exception
        /// - 引数 aimeId に無効なUID値を指定した場合。
        /// - 引数 status に不正な値を指定した場合。
        ///
        /// プレイ開始、コンティニュー、プレイ終了と連動してログ送信を行いたい場合は
        /// Sequence クラスのメンバ関数
        /// Sequence#beginPlay でAimeのUID値を紐付けすることを推奨する。
        /// それ以外のタイミングでログ送信を行いたい場合にこの関数を用いる。
        ///
        /// ビデオゲームでクレジットを消費してゲームを開始またはコンティニューした場合、
        /// この関数ではなくメンバ関数
        /// #sendLog(const AimeId&, AimeLogStatus, std::size_t, std::size_t)
        /// を用いることを推奨する。
        ///
        /// この関数を連続して複数回呼び出した場合、要求は内部キューに蓄えられ、
        /// 先に呼び出したものから逐次処理される。
        RequestState sendLog(const AimeId& aimeId, AimeLogStatus status);

        /// @brief ログ送信開始を要求する。
        /// @param[in] aimeId ログ送信対象のUID値。
        /// @param[in] status ログステータス。
        /// @param[in] gameCostIndex
        ///     付随情報として送信する消費ゲームコストのゲームコスト設定インデックス。
        ///     通常、 CreditUnit#payGameCost で引数 gameCostIndex に指定した値を用いる。
        /// @param[in] gameCostCount
        ///     付随情報として送信する消費ゲームコストのゲームコスト減算回数。
        ///     通常、 CreditUnit#payGameCost で引数 count に指定した値を用いる。
        /// @return 要求状態値。
        /// @see Sequence#beginPlay
        ///
        /// @exception Exception
        /// - 引数 aimeId に無効なUID値を指定した場合。
        /// - 引数 status に不正な値を指定した場合。
        /// - 引数 gameCostIndex に CreditConfig::MaxGameCostCount 以上の値を指定した場合。
        /// - 引数 gameCostCount に 0 以下もしくは 99 より大きい値を指定した場合。
        ///
        /// プレイ開始、コンティニュー、プレイ終了と連動してログ送信を行いたい場合は
        /// Sequence クラスのメンバ関数
        /// Sequence#beginPlay でAimeのUID値を紐付けすることを推奨する。
        /// それ以外のタイミングでログ送信を行いたい場合にこの関数を用いる。
        ///
        /// ビデオゲームでクレジットを消費してゲームを開始またはコンティニューした場合、
        /// こちらのオーバロードを用いること。
        ///
        /// この関数を連続して複数回呼び出した場合、要求は内部キューに蓄えられ、
        /// 先に呼び出したものから逐次処理される。
        RequestState sendLog(
            const AimeId& aimeId,
            AimeLogStatus status,
            std::size_t gameCostIndex,
            std::size_t gameCostCount = 1);

    public:
        // キャンペーン関連

        /// @brief キャンペーン情報の有効数を取得する。
        /// @return キャンペーン情報の有効数。 0 以上 AimeCampaignCountLimit 以下。
        std::size_t getCampaignInfoCount() const;

        /// @brief キャンペーン情報を取得する。
        /// @param[in] index インデックス。
        /// @return キャンペーン情報。
        ///
        /// @exception Exception
        /// 引数 index に有効数以上の値を指定した場合。
        /// 有効数はメンバ関数 #getCampaignInfoCount で取得できる。
        ///
        /// この情報はDaemonプロセスがバックグラウンドで定期的に更新する。
        /// 更新タイミング次第では、終了済みのキャンペーン情報が返る可能性がある。
        /// アプリ側で取得した情報の各種日時を確認して判断すること。
        const AimeCampaignInfo& getCampaignInfo(std::size_t index) const;

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

        /// @brief UID値に紐付くキャンペーン進捗状況の受信を要求する。
        /// @param[in] aimeId キャンペーン進捗状況受信対象のUID値。
        /// @return 要求状態値。引数や状態が不正な場合は無効値。
        ///
        /// @exception Exception
        /// 引数 aimeId に無効なUID値を指定した場合。
        ///
        /// この関数はUID値に紐付くキャンペーン進捗状況の受信要求のみを行う。
        /// 実際の処理は、 Core クラスのメンバ関数 Core#execute 呼び出しによって行われる。
        ///
        /// この関数の戻り値である RequestState クラスのメンバ関数 RequestState#isDone が
        /// true を返すようになれば処理完了済みであり、その際にメンバ関数
        /// RequestState#isSucceeded が true を返すのであれば処理成功を表す。
        ///
        /// 処理成功後は、メンバ関数 #getCampaignProgressCount および #getCampaignProgress
        /// によって受信した内容を参照できる。
        ///
        /// キャンペーン進捗状況は基本的にログ送信の内容に基づいて更新されるため、
        /// ログ送信後にこの関数を呼び出して最新の進捗状況を得ることが望ましい。
        ///
        /// この関数を連続して複数回呼び出した場合、要求は内部キューに蓄えられ、
        /// 先に呼び出したものから逐次処理される。
        RequestState requestCampaignProgress(const AimeId& aimeId);

        /// @brief 直近で受信完了したキャンペーン進捗状況の有効数を取得する。
        /// @param[in] aimeId 対象UID値。
        /// @return キャンペーン進捗状況の有効数。 0 以上 AimeCampaignCountLimit 以下。
        ///
        /// @exception Exception
        /// 引数 aimeId に無効なUID値を指定した場合。
        ///
        /// 対象UID値についてメンバ関数 #requestCampaignProgress を呼び出すと、
        /// その時点でライブラリ内のデータが初期化され、この関数は 0 を返すようになる。
        /// その後、受信が正常に完了すると再び有効な値を返すようになる。
        ///
        /// 当ライブラリ内では直近 8 ユーザ分だけ情報を保持している。
        /// 保持限界を超える進捗状況の受信を行った場合、古い受信データから順に破棄され、
        /// この関数は 0 を返すようになる。
        std::size_t getCampaignProgressCount(const AimeId& aimeId) const;

        /// @brief 直近で受信完了したキャンペーン進捗状況を取得する。
        /// @param[in] aimeId 対象UID値。
        /// @param[in] index インデックス。
        /// @return キャンペーン進捗状況。
        ///
        /// @exception Exception
        /// - 引数 aimeId に無効なUID値を指定した場合。
        /// - 引数 index に有効数以上の値を指定した場合。
        ///   有効数はメンバ関数 #getCampaignProgressCount で取得できる。
        ///
        /// 当ライブラリ内では直近 8 ユーザ分だけ情報を保持している。
        /// 保持限界を超える進捗状況の受信を行った場合、古い受信データから順に破棄され、
        /// この関数から取得した参照は無効となる。
        ///
        /// 情報を長期間に渡って参照したい場合、参照の保持ではなく値のコピーを行うこと。
        const AimeCampaignProgress& getCampaignProgress(
            const AimeId& aimeId,
            std::size_t index) const;

        /// @brief 直近で受信完了したキャンペーン進捗状況配列を取得する。
        /// @param[in] aimeId 対象UID値。
        /// @return キャンペーン進捗状況配列。
        ///
        /// @exception Exception
        /// 引数 aimeId に無効なUID値を指定した場合。
        ///
        /// 範囲for文や各種アルゴリズム関数に渡すことを想定している。
        ///
        /// - 有効数を知りたいだけならばメンバ関数 #getCampaignProgressCount を用いること。
        /// - 特定の進捗状況を取得したいだけならばメンバ関数 #getCampaignProgress を用いること。
        std::vector<std::reference_wrapper<const AimeCampaignProgress>>
        getCampaignProgresses(const AimeId& aimeId) const
        {
            return
                ::amdaemon::util::toContainer<decltype(this->getCampaignProgresses(aimeId))>(
                    this->getCampaignProgressCount(aimeId),
                    [aimeId, this](std::size_t i) -> const AimeCampaignProgress&
                    {
                        return this->getCampaignProgress(aimeId, i);
                    });
        }
    };

/// @}
} // namespace amdaemon

#endif // AMDAEMON_AIME_H