CreditUnit.h

[詳解]

/// @file
/// @brief ビデオゲームのプレイヤー別クレジット情報を保持するクラス CreditUnit のヘッダ。
///
/// Copyright(C)SEGA

#ifndef AMDAEMON_CREDITUNIT_H
#define AMDAEMON_CREDITUNIT_H

#include "amdaemon/env.h"

#include <cstdint>
#include <cstddef>

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

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

    /// @brief ビデオゲームのプレイヤー別クレジット情報を保持するクラス。
    /// @see Credit, Player
    ///
    /// このクラスのインスタンスをアプリ側で直接生成することはできない。
    /// Credit クラスのメンバ関数 Credit#getPlayer から取得すること。
    ///
    /// 一部の関数は処理完了まで呼び出し元スレッドをブロックする。
    ///
    /// @par INSERT COIN(S) 表示について
    /// 次の順序で INSERT COIN(S) 表示内容を決定する。
    /// -# メンバ関数 #isGameCostEnough が true を返すならばプレイ可能表示を行う。
    /// -# メンバ関数 #isZero が true を返すならば "INSERT COIN(S)" 表示を行う。
    /// -# どちらも満たさなければ "INSERT MORE COIN(S)" 表示を行う。
    ///
    /// @ingroup g_player
    class CreditUnit
    {
    public:
        /// @brief コンストラクタ。
        /// @note アプリ側からは利用できない。
        explicit CreditUnit(InnerIndexHolder);

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

        /// @brief 現在のクレジット値を取得する。
        /// @return 現在のクレジット値。
        std::uint32_t getCredit() const;

        /// @brief 現在のクレジット端数値を取得する。
        /// @return 現在のクレジット端数値。
        ///
        /// COIN TO CREDIT 設定値以上にはならない。
        /// COIN TO CREDIT 設定値が 1 ならば常に 0 を返す。
        std::uint32_t getRemain() const;

        /// @brief 現在のクレジット値およびクレジット端数値が 0 であるか否かを取得する。
        /// @retval true  クレジット値もクレジット端数値も 0 である場合。
        /// @retval false クレジット値もしくはクレジット端数値が 1 以上である場合。
        bool isZero() const;

        /// @brief 追加可能なコイン数を取得する。
        /// @return 追加可能なコイン数。 FREE PLAY 設定が有効である場合は 0 。
        ///
        /// 現在の状態から追加可能なコイン数を返す。
        /// ただし FREE PLAY 設定が有効である場合は 0 を返す。
        ///
        /// 主に、 EMoney クラスによる電子マネーでのコイン購入支払操作において、
        /// 購入予定のコイン数が追加可能であるか事前に調べるために用いる。
        ///
        /// BONUS ADDER 設定等があるため、追加可能なコイン数は単純計算で算出できない。
        /// 独自に計算せず、この関数の戻り値を利用すること。
        std::uint32_t getAddableCoin() const;

        /// @brief COIN TO CREDIT 設定値を取得する。
        /// @return COIN TO CREDIT 設定値。
        ///
        /// COIN数いくつで1クレジットになるかを表す。
        /// FREE PLAY 設定が有効であっても 0 にはならない。
        ///
        /// std::max(Credit().getConfig().coinToCredit, 1U) を返す。
        std::uint32_t getCoinToCredit() const;

        /// @brief FREE PLAY 設定が有効であるか否かを取得する。
        /// @retval true  FREE PLAY 設定が有効である場合。
        /// @retval false FREE PLAY 設定が無効である場合。
        ///
        /// Credit().getConfig().freePlay を返す。
        bool isFreePlay() const;

        /// @brief 現在のクレジット値情報を文字列化する。
        /// @return クレジット値情報文字列。
        /// @attention
        /// 内部でプレイヤーごとに共通の文字列バッファを使い回しているため、
        /// この関数を再度呼び出すと戻り値のポインタが指す文字列値が変更される。
        /// 以前の値を保持しておきたい場合は std::wstring 等にコピーする必要がある。
        ///
        /// 次の手順に従って文字列を生成する。
        /// FREE PLAY 設定は考慮しない。
        ///
        /// -# COIN TO CREDIT 設定値が 1 ならば、クレジット値を文字列化して返す。
        /// -# COIN TO CREDIT 設定値が 2 以上かつクレジット値が 0 ならば、
        ///    クレジット端数値および COIN TO CREDIT 設定値を文字列化したものを
        ///    "/" で連結した文字列を返す。
        /// -# COIN TO CREDIT 設定値が 2 以上かつクレジット値が 1 以上ならば、
        ///    上記手順 1 と 2 の文字列を " " で連結した文字列を返す。
        ///    ただしクレジット端数値が 0 の場合は上記手順 1 の文字列のみを返す。
        const wchar_t* toString() const;

        /// @brief ゲームコスト設定値を取得する。
        /// @param[in] gameCostIndex ゲームコスト設定インデックス。
        /// @return ゲームコスト設定値。
        ///
        /// @exception Exception
        /// 引数 gameCostIndex に CreditConfig::MaxGameCostCount 以上の値を指定した場合。
        ///
        /// Credit().getConfig().gameCosts[gameCostIndex] を返す。
        std::uint32_t getGameCost(std::size_t gameCostIndex) const;

        /// @brief 現在のクレジット値がゲームコストを満たすか否かを取得する。
        /// @param[in] gameCostIndex ゲームコスト設定インデックス。
        /// @param[in] count ゲームコスト減算回数。既定値は 1 。
        /// @retval true  ゲームコストを満たす場合。
        /// @retval false ゲームコストを満たさない場合。
        ///
        /// @exception Exception
        /// - 引数 gameCostIndex に CreditConfig::MaxGameCostCount 以上の値を指定した場合。
        /// - 引数 count に 0 以下もしくは 99 より大きい値を指定した場合。
        ///
        /// 下記の条件判定式の結果を返す。
        ///
        /// @code
        /// getCredit() >= (getGameCost(gameCostIndex) * count)
        /// @endcode
        ///
        /// ただし、 FREE PLAY 設定が有効である場合は常に true を返す。
        bool isGameCostEnough(std::size_t gameCostIndex, std::size_t count = 1) const;

        /// @brief 現在のクレジット値からゲームコスト分を減算するように要求する。
        /// @param[in] gameCostIndex ゲームコスト設定インデックス。
        /// @param[in] count ゲームコスト減算回数。既定値は 1 。
        /// @retval true  成功した場合。
        /// @retval false クレジット不足等で失敗した場合。
        /// @see Sequence#beginPlay, Sequence#continuePlay
        ///
        /// @exception Exception
        /// - 引数 gameCostIndex に CreditConfig::MaxGameCostCount 以上の値を指定した場合。
        /// - 引数 count に 0 以下もしくは 99 より大きい値を指定した場合。
        ///
        /// プレイ開始、コンティニューと連動してゲームコスト(クレジット)支払いを行いたい場合は
        /// Sequence クラスのメンバ関数
        /// Sequence#beginPlay や Sequence#continuePlay を用いることを推奨する。
        /// それ以外のタイミングで支払いを行いたい場合にこの関数を用いる。
        ///
        /// 事前にメンバ関数 #isGameCostEnough でクレジットが足りていることを確認済みでも、
        /// Daemonプロセス側でクレジット減算に失敗する可能性はある。
        /// よって必ずこの関数の戻り値を確認すること。
        ///
        /// FREE PLAY 設定が有効ならば、要求は発行されるが、クレジット減算は行われない。
        /// その場合、要求処理自体は成功したものとして扱われる。
        ///
        /// Daemonプロセスが処理完了するまで呼び出し元スレッドをブロックする。
        ///
        /// @par 引数 count について
        /// ゲーム内アイテム購入等によってゲームコストのパターンが多岐に渡り、
        /// 標準のゲームコスト設定では賄いきれない場合、この引数値を設定することで
        /// @code
        /// (ゲームコスト設定値 * count)
        /// @endcode
        /// のクレジット減算を行うことができる。
        /// @par
        /// 標準のゲームコスト設定で賄える場合、既定値の 1 を用いること。
        /// @par
        /// この関数を複数回呼び出すことでも同等の処理を行えるように思えるかもしれないが、
        /// 関数を呼び出す度にDaemonプロセス側でクレジット数のバックアップが行われるため、
        /// 途中電断等によって中途半端なクレジット減算が行われてしまう可能性がある。
        /// 一度のプレイヤー操作に対してこの関数を複数回呼び出すような処理は避けること。
        bool payGameCost(std::size_t gameCostIndex, std::size_t count = 1);

    private:
        std::size_t _playerIndex;   ///< プレイヤーインデックス。

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

/// @}
} // namespace amdaemon

#endif // AMDAEMON_CREDITUNIT_H