AccountingUnit.h

[詳解]

/// @file
/// @brief プレイヤー単位のALL.Net課金処理を提供するクラス AccountingUnit のヘッダ。
///
/// Copyright(C)SEGA

#ifndef AMDAEMON_ALLNET_ACCOUNTINGUNIT_H
#define AMDAEMON_ALLNET_ACCOUNTINGUNIT_H

#include "amdaemon/env.h"
#include "amdaemon/allnet/AccountingHandle.h"

#include <cstdint>
#include <cstddef>

// 内部クラスの前方宣言
namespace amdaemon { class InnerIndexHolder; }

namespace amdaemon
{
namespace allnet
{
/// @addtogroup g_allnet
/// @{

    /// @brief プレイヤー単位のALL.Net課金処理を提供するクラス。
    /// @see Accounting, Player
    ///
    /// このクラスのインスタンスをアプリ側で直接生成することはできない。
    /// Accounting クラスのメンバ関数 Accounting#getPlayer から取得すること。
    ///
    /// @ingroup g_player
    class AccountingUnit
    {
    public:
        /// @brief 種別コードの最大許容値を取得する。
        /// @return 種別コードの最大許容値。固定値 654 。
        static std::uint32_t getKindCodeLimit();

        /// @brief 状態コードの最大許容値を取得する。
        /// @return 状態コードの最大許容値。固定値 99 。
        static std::uint32_t getStatusCodeLimit();

        /// @brief 商品数の最大許容値を取得する。
        /// @return 商品数の最大許容値。固定値 255 。
        static std::uint32_t getItemCountLimit();

        /// @brief 数量値の最大許容値を取得する。
        /// @return 数量値の最大許容値。固定値 7679 。
        static std::uint32_t getQuantityLimit();

        /// @brief 数列値の最大文字数を取得する。
        /// @return 数列値の最大文字数。少なくとも 127 以上の固定値。
        static std::size_t getMaxGeneralIdLength();

    public:
        /// @brief コンストラクタ。
        /// @note アプリ側からは利用できない。
        explicit AccountingUnit(::amdaemon::InnerIndexHolder);

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

        /// @brief 課金プレイを開始可能な状態であるか否かを取得する。
        /// @retval true  開始可能である場合。
        /// @retval false 開始不可能である場合。
        /// @see Accounting#isPlayable
        ///
        /// Accounting#isPlayable と同じ値を返す。
        ///
        /// この関数が true を返す場合であっても、
        /// メンバ関数 #beginPlay の呼び出しが必ず成功するとは限らない。
        bool canBeginPlay() const;

        /// @brief 課金プレイを開始する。
        /// @param[in] kindCode 種別コード。 0 以上 654 以下。
        /// @param[in] statusCode 状態コード。 0 以上 99 以下。
        /// @return 識別ハンドル値。開始できなかった場合は無効なハンドル値。
        /// @see Sequence#beginPlay, Sequence#continuePlay, Sequence#endPlay
        ///
        /// @exception Exception
        /// - 引数 kindCode に 654 より大きい値を指定した場合。
        /// - 引数 statusCode に 99 より大きい値を指定した場合。
        ///
        /// プレイ開始、コンティニュー、プレイ終了と連動して課金プレイを開始したい場合は
        /// Sequence クラスのプレイ状態変更関連メンバ関数を用いることを推奨する。
        /// それ以外のタイミングで課金プレイを開始したい場合にこの関数を用いる。
        ///
        /// メンバ関数 #canBeginPlay が false を返す場合は何もせずに無効なハンドル値を返す。
        ///
        /// Daemonプロセスが処理完了するまで呼び出し元スレッドをブロックする。
        AccountingHandle beginPlay(std::uint32_t kindCode, std::uint32_t statusCode);

        /// @brief 課金プレイを終了する。
        /// @param[in] handle
        ///     識別ハンドル値。メンバ関数 beginPlay や continuePlay から受け取った値。
        /// @param[in] kindCode 種別コード。 0 以上 654 以下。
        /// @param[in] statusCode 状態コード。 0 以上 99 以下。
        /// @param[in] itemCount 商品数。 0 以上 255 以下。 0 ならば課金しない。
        /// @retval true  終了できた場合。
        /// @retval false 終了できなかったか、開始していない場合。
        /// @see Sequence#beginPlay, Sequence#continuePlay, Sequence#endPlay
        ///
        /// @exception Exception
        /// - 引数 handle に無効なハンドル値を指定した場合。
        /// - 引数 kindCode に 654 より大きい値を指定した場合。
        /// - 引数 statusCode に 99 より大きい値を指定した場合。
        /// - 引数 itemCount に 255 より大きい値を指定した場合。
        ///
        /// メンバ関数 #beginPlay で開始した課金プレイを終了させる場合に用いる。
        /// Sequence クラスのプレイ状態変更関連メンバ関数を用いて開始した課金プレイを
        /// この関数で終了させることはできない。
        ///
        /// 通常、引数 itemCount には課金するならば 1 、しないならば 0 を指定する。
        /// ただしタイトルによっては 2 以上の値を指定する場合もある。
        /// 詳しくはALL.Net技術情報サイトの「課金ログ定義ガイドライン」等を参照すること。
        ///
        /// Daemonプロセスが処理完了するまで呼び出し元スレッドをブロックする。
        bool endPlay(
            AccountingHandle handle,
            std::uint32_t kindCode,
            std::uint32_t statusCode,
            std::uint32_t itemCount);

        /// @brief 課金プレイを一旦終了し、新たに開始する。
        /// @param[in] prevHandle
        ///     終了用の識別ハンドル値。
        ///     メンバ関数 beginPlay や continuePlay から受け取った値。
        /// @param[in] prevKindCode 終了用の種別コード。 0 以上 654 以下。
        /// @param[in] prevStatusCode 終了用の状態コード。 0 以上 99 以下。
        /// @param[in] prevItemCount 終了用の商品数。 0 以上 255 以下。 0 ならば課金しない。
        /// @param[in] nextKindCode 新規開始用の種別コード。 0 以上 654 以下。
        /// @param[in] nextStatusCode 新規開始用の状態コード。 0 以上 99 以下。
        /// @return 新たな識別ハンドル値。開始できなかった場合は無効なハンドル値。
        /// @see Sequence#continuePlay
        ///
        /// @exception Exception
        /// - 引数 prevHandle に無効なハンドル値を指定した場合。
        /// - 引数 prevKindCode に 654 より大きい値を指定した場合。
        /// - 引数 prevStatusCode に 99 より大きい値を指定した場合。
        /// - 引数 prevItemCount に 255 より大きい値を指定した場合。
        /// - 引数 nextKindCode に 654 より大きい値を指定した場合。
        /// - 引数 nextStatusCode に 99 より大きい値を指定した場合。
        ///
        /// コンティニューと連動して課金プレイを新たに開始したい場合は
        /// Sequence クラスのメンバ関数 Sequence#continuePlay を用いることを推奨する。
        /// それ以外のタイミングで課金プレイを新たに開始したい場合にこの関数を用いる。
        ///
        /// メンバ関数 #endPlay と #beginPlay を続けて呼び出すこととほぼ同義だが、
        /// そちらの場合と異なり、課金プレイの終了直後に締め処理が走ってしまうことがない。
        /// そのため安全に課金プレイを新規開始することができる。
        ///
        /// Daemonプロセスが処理完了するまで呼び出し元スレッドをブロックする。
        AccountingHandle continuePlay(
            AccountingHandle prevHandle,
            std::uint32_t prevKindCode,
            std::uint32_t prevStatusCode,
            std::uint32_t prevItemCount,
            std::uint32_t nextKindCode,
            std::uint32_t nextStatusCode);

        /// @brief 単発課金を行う。
        /// @param[in] kindCode 種別コード。 0 以上 654 以下。
        /// @param[in] statusCode 状態コード。 0 以上 99 以下。
        /// @param[in] itemCount 商品数。 0 以上 255 以下。
        /// @retval true  課金できた場合。
        /// @retval false 課金できなかった場合。
        ///
        /// @exception Exception
        /// - 引数 kindCode に 654 より大きい値を指定した場合。
        /// - 引数 statusCode に 99 より大きい値を指定した場合。
        /// - 引数 itemCount に 255 より大きい値を指定した場合。
        ///
        /// 課金プレイ中でなければ課金できない。
        ///
        /// Daemonプロセスが処理完了するまで呼び出し元スレッドをブロックする。
        bool accountItem(
            std::uint32_t kindCode,
            std::uint32_t statusCode,
            std::uint32_t itemCount);

        /// @brief 数量値を保存する。
        /// @param[in] kindCode 種別コード。 0 以上 654 以下。
        /// @param[in] quantity 数量値。 0 以上 7679 以下。
        /// @retval true  保存できた場合。
        /// @retval false 保存できなかった場合。
        ///
        /// @exception Exception
        /// - 引数 kindCode に 654 より大きい値を指定した場合。
        /// - 引数 quantity に 7679 より大きい値を指定した場合。
        ///
        /// Daemonプロセスが処理完了するまで呼び出し元スレッドをブロックする。
        bool putQuantity(std::uint32_t kindCode, std::uint32_t quantity);

        /// @brief 数列値を保存する。
        /// @param[in] kindCode 種別コード。 0 以上 654 以下。
        /// @param[in] generalId 数列値。 '0' 〜 '9' で構成される文字列。
        /// @retval true  保存できた場合。
        /// @retval false 保存できなかった場合。
        ///
        /// @exception Exception
        /// - 引数 kindCode に 654 より大きい値を指定した場合。
        /// - 引数 generalId に nullptr を指定した場合。
        /// - 引数 generalId に空文字列を指定した場合。
        /// - 引数 generalId の文字数が最大文字数より多い場合。
        ///   最大文字数は静的メンバ関数 #getMaxGeneralIdLength で取得できる。
        /// - 引数 generalId に '0' 〜 '9' 以外の文字が含まれている場合。
        ///
        /// Daemonプロセスが処理完了するまで呼び出し元スレッドをブロックする。
        bool putGeneralId(std::uint32_t kindCode, const wchar_t* generalId);

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

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

/// @}
} // namespace allnet
} // namespace amdaemon

#endif // AMDAEMON_ALLNET_ACCOUNTINGUNIT_H