NetworkTestInfo.h

[詳解]

/// @file
/// @brief ネットワークセルフテスト情報を提供するクラス NetworkTestInfo のヘッダ。
///
/// Copyright(C)SEGA

#ifndef AMDAEMON_NETWORKTESTINFO_H
#define AMDAEMON_NETWORKTESTINFO_H

#include "amdaemon/env.h"
#include "amdaemon/ErrorInfo.h"
#include "amdaemon/NetworkTestItem.h"
#include "amdaemon/NetworkTestState.h"
#include "amdaemon/TestResult.h"
#include "amdaemon/util/container.h"

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

namespace amdaemon
{
/// @addtogroup g_network
/// @{

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

    /// @brief ネットワークセルフテスト情報を提供するクラス。
    /// @see Network
    ///
    /// このクラスのインスタンスをアプリ側で直接生成することはできない。
    /// Network クラスのメンバ関数
    /// Network#getPowerOnTestInfo や Network#getTestInfo から取得すること。
    ///
    /// AM Daemon がサポートするのは全タイトル共通で利用可能なテスト項目のみであり、
    /// タイトル固有のテスト項目はタイトル側で実装する必要がある。
    ///
    /// @par ネットワークセルフテスト項目について
    /// - テスト項目は @ref NetworkTestItem 列挙により定義される。
    ///     - 列挙値の定義順に沿って順番にテスト処理が行われる。
    /// - メンバ関数 #isAvailableItem が false を返す項目はテスト不可能であるため、
    ///   アプリでは項目自体が存在しないものとして扱うこと。(画面表示しない等)
    ///     - 各項目がテスト可能であるか否かは、
    ///       Daemonプロセスの設定ファイルの記述内容により一意に定まる。
    ///     - テスト可能な項目の一覧はメンバ関数 #getAvailableItems で取得できる。
    /// - テスト実施中は、各テスト項目について項目名とその状態を横に並べて表示すること。
    ///     - 関数 toString(NetworkTestItem) によって項目名を取得できる。
    ///     - メンバ関数 #getStatusText によって状態表示用文字列を取得できる。
    ///
    /// @par パワーオンセルフテスト
    /// - Daemonプロセスは、起動時およびゲームテストモードから抜けたタイミングで
    ///   パワーオンセルフテストを自動的に開始する。
    /// - パワーオンセルフテストが完了するか、ゲームテストモードに入るまで、
    ///   メンバ関数 #isRunning は true を返し続ける。
    /// - テスト項目処理が失敗した場合は次のように処理される。
    ///     - リトライによる復旧が可能である場合、Daemonプロセス側でリトライ処理が行われる。
    ///       リトライするのは失敗したテスト項目からであり、
    ///       既に成功済みのテスト項目はリトライされず正常完了状態のままとなる。
    ///     - リトライによる復旧が不可能である場合、以降の項目はすべて "N/A" となり、
    ///       パワーオンセルフテストは完了となる。
    /// - リトライ処理の関係上、メンバ関数 #isBusy が true を返す状態であっても
    ///   メンバ関数 #getResult が TestResult::Bad を返す場合がある。
    /// - ゲームテストモードに入った場合は処理が中断される。
    ///
    /// @par ネットワークテスト
    /// - ゲームテストモード中であれば、 Network クラスのメンバ関数
    ///   Network#startTest によってネットワークテストを開始することができる。
    ///     - 開始可能な状態であるか否かは Network クラスのメンバ関数
    ///       Network#canStartTest で取得できる。
    /// - テスト項目処理が失敗した場合、それ以降の項目はすべて "N/A" となる。
    ///   パワーオンセルフテストとは異なり、リトライ処理は行われない。
    /// - テストの実施中に再度テスト開始要求を行った場合、強制的にリスタートされる。
    /// - ゲームテストモードを抜けた場合は処理が中断される。
    ///
    /// @par ネットワークエラー情報
    /// - いずれかのテスト項目に失敗した場合、内部にネットワークエラー情報が設定される。
    ///   メンバ関数 #getErrorInfo で情報を取得することができる。
    ///     - ただしテスト項目 NetworkTestItem::Hops については設定されない。
    /// - 失敗したテスト項目がゲーム進行不能レベルのものであるか否かはアプリ依存である。
    ///   もしゲーム進行不能レベルである場合、何らかのエラー表示を行うことになるが、
    ///   その際にこのネットワークエラー情報を用いることができる。
    /// - パワーオンセルフテストにおいて、失敗したテスト項目がリトライ処理によって
    ///   成功した場合、ネットワークエラー情報はリセットされる。
    class NetworkTestInfo
    {
    public:
        /// @brief テスト項目のビジー状態表示用文字列を取得する。
        /// @param[in] blink
        ///     文字列 "CHECK" と空文字列を一定時間毎に交互に返させる場合は true (既定値)。
        ///     文字列 "CHECK" のみを返させる場合は false 。
        /// @return ビジー状態表示用文字列。 "CHECK" または空文字列。
        ///
        /// タイトル固有テスト項目の処理中に表示する文字列として利用できる。
        static const wchar_t* getBusyStatusText(bool blink = true);

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

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

        /// @brief テストを実施中であるか否かを取得する。
        /// @retval true  実施中である場合。
        /// @retval false 実施中ではない場合。
        bool isRunning() const;

        /// @brief テストを完了済みであるか否かを取得する。
        /// @retval true  完了済みである場合。
        /// @retval false 未完了であるか、処理が中断された場合。
        ///
        /// テストが完了すると、テスト自体の成否は問わず true を返すようになる。
        /// 即ち、ゲームテストモード状態の切替により処理が中断されてさえいなければ、
        /// メンバ関数 #isRunning の戻り値とは逆の値を返す。
        /// 処理が中断された場合にはどちらの関数も false を返す。
        ///
        /// この関数が true を返す場合でも、テストがすべて成功しているとは限らない。
        /// いずれかの項目で失敗した場合、メンバ関数 #getErrorInfo にエラー情報が設定される。
        bool isCompleted() const;

        /// @brief テスト項目をテスト可能であるか否かを取得する。
        /// @param[in] item テスト項目。
        /// @retval true  テスト可能である場合。
        /// @retval false テスト不可能である場合。
        ///
        /// @exception Exception
        /// 引数 item に不正な値を指定した場合。
        ///
        /// 現在のネットワーク状態は考慮せず、単にテスト可能であるか否かを返す。
        /// Daemonプロセスの設定ファイルの記述内容により戻り値は一意に定まる。
        ///
        /// 例えばALL.NetおよびAimeを利用しないタイトルでは
        /// ALL.NetサーバやAimeサーバとの疎通チェックを行うことはできないため、
        /// @ref #isAvailableItem "isAvailableItem"(NetworkTestItem::Aime) は常に
        /// false を返す。
        ///
        /// 一方、ALL.NetおよびAimeを利用するタイトルであれば、
        /// たとえ前提となるALL.Netサーバとの疎通チェックに失敗していようがいまいが
        /// @ref #isAvailableItem "isAvailableItem"(NetworkTestItem::Aime) は常に
        /// true を返す。
        ///
        /// この関数が false を返すテスト項目について、
        /// アプリでは項目自体が存在しないものとして扱うこと。(画面表示しない等)
        bool isAvailableItem(NetworkTestItem item) const;

        /// @brief テスト可能なテスト項目数を取得する。
        /// @return テスト可能なテスト項目数。
        std::size_t getAvailableItemCount() const;

        /// @brief テスト可能なテスト項目を取得する。
        /// @param[in] index 項目インデックス。
        /// @return テスト可能なテスト項目。
        ///
        /// @exception Exception
        /// 引数 index にテスト可能なテスト項目数以上の値を指定した場合。
        /// 項目数はメンバ関数 #getAvailableItemCount で取得できる。
        NetworkTestItem getAvailableItem(std::size_t index) const;

        /// @brief テスト可能なテスト項目配列を取得する。
        /// @return テスト可能なテスト項目配列。
        ///
        /// アプリではこの関数が返すテスト項目のみを表示すること。
        std::vector<NetworkTestItem> getAvailableItems() const
        {
            return
                ::amdaemon::util::toContainer<decltype(getAvailableItems())>(
                    getAvailableItemCount(),
                    [this](std::size_t i) { return getAvailableItem(i); });
        }

        /// @brief テスト項目の実施状態を取得する。
        /// @param[in] item テスト項目。
        /// @return 実施状態。未実施の場合は NetworkTestState::None 。
        ///
        /// @exception Exception
        /// 引数 item に不正な値を指定した場合。
        ///
        /// メンバ関数 #isAvailableItem が false を返すテスト項目の場合、
        /// この関数の戻り値は未定義となる。
        NetworkTestState getState(NetworkTestItem item) const;

        /// @brief テスト項目を処理中であるか否かを取得する。
        /// @param[in] item テスト項目。
        /// @retval true  処理中である場合。
        /// @retval false 処理中ではない場合。
        ///
        /// @exception Exception
        /// 引数 item に不正な値を指定した場合。
        ///
        /// 条件式 (getState(item) == NetworkTestState::Busy) の結果を返す。
        ///
        /// メンバ関数 #isAvailableItem が false を返すテスト項目の場合、
        /// この関数の戻り値は未定義となる。
        bool isBusy(NetworkTestItem item) const
        {
            return (getState(item) == NetworkTestState::Busy);
        }

        /// @brief テスト項目が処理完了済みであるか否かを取得する。
        /// @param[in] item テスト項目。
        /// @retval true  処理完了済みである場合。
        /// @retval false 処理完了済みではない場合。
        ///
        /// @exception Exception
        /// 引数 item に不正な値を指定した場合。
        ///
        /// 条件式 (getState(item) == NetworkTestState::Done) の結果を返す。
        ///
        /// メンバ関数 #isAvailableItem が false を返すテスト項目の場合、
        /// この関数の戻り値は未定義となる。
        bool isDone(NetworkTestItem item) const
        {
            return (getState(item) == NetworkTestState::Done);
        }

        /// @brief テスト項目の処理結果を取得する。
        /// @param[in] item テスト項目。
        /// @return 処理結果。処理未完了である場合は TestResult::None 。
        ///
        /// @exception Exception
        /// 引数 item に不正な値を指定した場合。
        ///
        /// テストが開始されるとすべての値が TestResult::None に初期化される。
        /// その後はメンバ関数 #getState の戻り値により下記のようになる。
        ///
        /// @par 実施状態が NetworkTestState::None である場合
        /// - TestResult::None が返る。
        ///
        /// @par 実施状態が NetworkTestState::Busy である場合
        /// - パワーオンセルフテストでは TestResult::None または TestResult::Bad が返る。
        ///     - TestResult::None が返ってきた場合は初回の処理中である。
        ///     - TestResult::Bad が返ってきた場合はリトライ処理中である。
        /// - ネットワークテストでは常に TestResult::None が返る。
        ///
        /// @par 実施状態が NetworkTestState::Done である場合、
        /// - TestResult::None 以外のいずれかの値が返る。
        ///
        /// ただし、メンバ関数 #isAvailableItem が false を返すテスト項目の場合、
        /// この関数の戻り値は未定義となる。
        TestResult getResult(NetworkTestItem item) const;

        /// @brief ホップ数を取得する。
        /// @return ホップ数。未取得の場合は 0 。
        ///
        /// テストが開始されると 0 に初期化される。
        /// その後、 @ref #isDone "isDone"(NetworkTestItem::Hops) が true を返し、
        /// かつ @ref #getResult "getResult"(NetworkTestItem::Hops) が
        /// TestResult::Good を返すと、この値が取得できるようになる。
        std::uint32_t getHops() const;

        /// @brief テスト項目の状態表示用文字列を取得する。
        /// @param[in] item テスト項目。
        /// @param[in] blinkBusy
        ///     テスト項目実施中に文字列
        ///     "CHECK" と空文字列を一定時間毎に交互に返させる場合は true (既定値)。
        ///     文字列 "CHECK" のみを返させる場合は false 。
        /// @return 状態表示用文字列。
        ///
        /// @exception Exception
        /// 引数 item に不正な値を指定した場合。
        ///
        /// 指定したテスト項目について、下記の値を返す。
        ///
        /// - テスト項目未実施の場合、空文字列を返す。
        /// - テスト項目実施中の場合(メンバ関数 #isBusy が true を返す)、下記のようになる。
        ///     - 引数 blinkBusy が true (既定値)の場合、
        ///       文字列 "CHECK" と空文字列を約 0.5 秒おきに切り替えて返す。
        ///     - 引数 blinkBusy が false の場合、常に文字列 "CHECK" を返す。
        /// - テスト項目実施済みの場合(メンバ関数 #isDone が true を返す)、下記のようになる。
        ///     - 引数 item が NetworkTestItem::Hops で、
        ///       かつメンバ関数 #getResult の戻り値が TestResult::Good である場合、
        ///       メンバ関数 #getHops で取得したホップ数を文字列化した値を返す。
        ///     - 上記以外の場合、メンバ関数 #getResult で取得した
        ///       TestResult 値を関数 toString(TestResult) で文字列化した値を返す。
        ///
        /// 関数 toString(NetworkTestItem) で取得した項目名と並べて表示することを想定している。
        ///
        /// 表示内容は ALL.Net Programmer's Manual を基にしているが、
        /// テスト結果が "BAD" だった場合のエラー表示についてはこの関数では対応しない。
        /// エラー情報はメンバ関数 #getErrorInfo より取得すること。
        const wchar_t* getStatusText(NetworkTestItem item, bool blinkBusy = true) const;

        /// @brief ネットワークエラー情報インスタンスを取得する。
        /// @return ネットワークエラー情報インスタンス。
        ///
        /// いずれかのテスト項目に失敗した場合、エラー情報が設定される。
        /// ただしテスト項目 NetworkTestItem::Hops については設定されない。
        ///
        /// 失敗したテスト項目がゲーム進行不能レベルのものである場合、
        /// アプリはこのエラー情報を表示して進行不能であることを示すことができる。
        ///
        /// - パワーオンセルフテストでは、リトライ処理によりテスト項目が成功した場合、
        ///   自動的にエラー情報がクリアされる。
        /// - ネットワークテストでは、再度テストを開始するまでクリアされない。
        const ErrorInfo& getErrorInfo() const;

    private:
        bool _powerOn;  ///< パワーオンセルフテスト用ならば true 。

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

/// @}
} // namespace amdaemon

#endif // AMDAEMON_NETWORKTESTINFO_H