AimeResult.h

[詳解]

/// @file
/// @brief
///     初期化処理やポーリング処理によって取得したAime関連情報を保持するクラス
///     AimeResult のヘッダ。
///
/// Copyright(C)SEGA

#ifndef AMDAEMON_AIMERESULT_H
#define AMDAEMON_AIMERESULT_H

#include "amdaemon/env.h"
#include "amdaemon/deprecated.h"
#include "amdaemon/AccessCode.h"
#include "amdaemon/AimeOfflineId.h"
#include "amdaemon/AimeId.h"

#include <cstddef>

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

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

    /// @brief 初期化処理やポーリング処理によって取得したAime関連情報を保持するクラス。
    /// @see AimeUnit
    ///
    /// このクラスのインスタンスをアプリ側で直接生成することはできない。
    /// AimeUnit クラスのメンバ関数 AimeUnit#getResult から取得すること。
    class AimeResult
    {
    public:
        /// @brief コンストラクタ。
        /// @note アプリ側からは利用できない。
        explicit AimeResult(InnerIndexHolder);

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

        /// @brief 有効な情報が保持されているか否かを取得する。
        /// @retval true  有効な情報が保持されている場合。
        /// @retval false 有効な情報が保持されていない場合。
        bool valid() const;

        /// @brief Aimeリーダーが接続されているか否かを取得する。
        /// @retval true  Aimeリーダーが接続されている場合。
        /// @retval false Aimeリーダーが接続されていないか、未チェックである場合。
        ///
        /// メンバ関数 #valid が true を返すのであれば必ず有意な値を返す。
        bool isReaderDetected() const;

        /// @brief Aimeリーダーのハードウェアバージョンを取得する。
        /// @return ハードウェアバージョン。未取得の場合は空文字列。
        ///
        /// この関数はすべてのポーリング処理コマンドで有意な値を返す。
        /// ただしメンバ関数 #isReaderDetected が false を返す場合、この関数は空文字列を返す。
        ///
        /// 表示等に利用する場合、値をキャッシュせず直接この関数の戻り値を利用すること。
        /// ポーリング処理開始直後からしばらくは空文字列となるが、
        /// Aimeリーダーが正しく接続されていればすぐに有効な値を返すようになる。
        ///
        /// 特に電子マネー対応タイトルでは、
        /// 第3世代以降のAimeリーダーが接続されているか判別するために、
        /// この関数の戻り値をゲームテストモード等で表示することを推奨する。
        const wchar_t* getHardVersion() const;

        /// @brief Aimeリーダーのファームウェアバージョンを取得する。
        /// @return ファームウェアバージョン。未取得の場合は空文字列。
        ///
        /// この関数はすべてのポーリング処理コマンドで有意な値を返す。
        /// ただしメンバ関数 #isReaderDetected が false を返す場合、この関数は空文字列を返す。
        ///
        /// 表示等に利用する場合、値をキャッシュせず直接この関数の戻り値を利用すること。
        /// ポーリング処理開始直後からしばらくは空文字列となるが、
        /// Aimeリーダーが正しく接続されていればすぐに有効な値を返すようになる。
        const wchar_t* getFirmVersion() const;

        /// @brief 読み取ったAimeのオフラインIDを取得する。
        /// @return オフラインID。未取得の場合は無効値。
        ///
        /// この関数はすべてのポーリング処理コマンドで有意な値を返す。
        /// ただしAimeリーダーによる読み取りに失敗した場合、この関数は無効値を返す。
        ///
        /// オフラインIDとは、各種DBにアクセスせずに取得できるID値であり、
        /// 他のオフラインIDとの比較やバイナリ書き出しが可能である。
        /// オフラインプレイをサポートするゲームで用いるとよい。
        const AimeOfflineId& getOfflineId() const;

        /// @brief 読み取ったAimeがFeliCaモバイル(おサイフケータイ)であるか否かを取得する。
        /// @retval true  FeliCaモバイルである場合。
        /// @retval false FeliCaモバイルではないか、未チェックである場合。
        ///
        /// この関数はすべてのポーリング処理コマンドで有意な値を返す。
        /// ただしメンバ関数 #getOfflineId が無効値を返す場合、この関数は false を返す。
        ///
        /// この関数はFeliCaモバイル(おサイフケータイ)の場合のみ true を返す。
        /// FeliCaスタンダード(キャラEdy)や FeliCa Lite-S (共通アミューズメントICカード)等、
        /// FeliCaモバイル以外のFeliCaデバイスである場合は false を返す。
        bool isMobile() const;

        /// @brief 読み取ったAimeのアクセスコードを取得する。
        /// @return アクセスコード。未取得の場合は無効値。
        ///
        /// この関数はすべてのポーリング処理コマンドで有意な値を返す。
        /// ただし下記の場合、この関数は無効値を返す。
        ///
        /// - Aimeリーダーによる読み取りに失敗した場合。
        /// - ポーリング処理コマンドに AimeCommand::ScanOffline を指定し、
        ///   読み取ったAimeの種別がFeliCaであった場合。
        ///     - FeliCaのアクセスコードはFeliCaDBにアクセスしないとわからないため。
        const AccessCode& getAccessCode() const;

        /// @brief 読み取ったAimeのUID値を取得する。
        /// @return UID値。未取得の場合は無効値。
        ///
        /// この関数はポーリング処理コマンド AimeCommand::Scan でのみ有意な値を返す。
        /// ただし何らかの理由でUID値を取得できない場合、この関数は無効値を返す。
        const AimeId& getAimeId() const;

        /// @brief 読み取ったAimeが SEGA ID に紐付いているか否かを取得する。
        /// @retval true  紐付いている場合。
        /// @retval false 紐付いていないか、取得できなかった場合。
        ///
        /// この関数はポーリング処理コマンド AimeCommand::Scan でのみ有意な値を返す。
        /// ただしメンバ関数 #getAimeId が無効値を返す場合、この関数は false を返す。
        bool isSegaIdRegistered() const;

        /// @brief 読み取ったAimeに紐付く SEGA ID への認証キーを取得する。
        /// @return 認証キー。紐付いていないか、取得できなかった場合は nullptr 。
        ///
        /// この関数はポーリング処理コマンド AimeCommand::Scan でのみ有意な値を返す。
        /// ただしメンバ関数 #isSegaIdRegistered が false を返す場合、この関数は
        /// nullptr を返す。
        const wchar_t* getSegaIdAuthKey() const;

        /// @brief SEGA ID に紐付くUID値の個数を取得する。
        /// @return UID値の個数。紐付いていないか、取得できなかった場合は 0 。
        ///
        /// この関数はポーリング処理コマンド AimeCommand::Scan でのみ有意な値を返す。
        /// ただしメンバ関数 #isSegaIdRegistered が false を返す場合、この関数は 0 を返す。
        ///
        /// 読み取ったAimeのUID値は含まない。
        std::size_t getRelatedAimeIdCount() const;

        /// @brief SEGA ID に紐付くUID値を取得する。
        /// @param[in] index インデックス。
        /// @return UID値。
        ///
        /// @exception Exception
        /// 引数 index にUID値個数以上の値を指定した場合。
        /// UID値個数はメンバ関数 #getRelatedAimeIdCount で取得できる。
        ///
        /// この関数はポーリング処理コマンド AimeCommand::Scan でのみ有意な値を返す。
        ///
        /// 読み取ったAimeのUID値は含まない。
        /// 読み取ったAimeのUID値を取得したい場合はメンバ関数 #getAimeId を用いること。
        const AimeId& getRelatedAimeId(std::size_t index) const;

    private:
        std::size_t _unitIndex; ///< ユニットインデックス。

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

/// @}
} // namespace amdaemon

#endif // AMDAEMON_AIMERESULT_H