Error.h

[詳解]

/// @file
/// @brief アプリで表示すべきエラーの情報を提供するMonostateクラス Error のヘッダ。
///
/// Copyright(C)SEGA

#ifndef AMDAEMON_ERROR_H
#define AMDAEMON_ERROR_H

#include "amdaemon/env.h"
#include "amdaemon/ErrorInfo.h"
#include "amdaemon/ErrorLog.h"

#include <cstdint>

namespace amdaemon
{
/// @addtogroup g_error
/// @{

    /// @brief アプリで表示すべきエラーの情報を提供するMonostateクラス。
    ///
    /// Core クラスのメンバ関数 Core#execute 呼び出しによって内容が更新される。
    /// 一部の関数は処理完了まで呼び出し元スレッドをブロックする。
    ///
    /// @par ライブラリ利用アプリで実装すべきこと
    /// - メンバ関数 #isOccurred の戻り値を毎フレームチェックし、
    ///   true が返ってきた場合はアプリ側でエラー表示を行うこと。
    /// - アプリ独自のエラーが発生した場合、メンバ関数 #set でエラーを通知すること。
    /// - オペレータがエラーリセット操作(PushSwitch2の押下等)を行った場合、
    ///   メンバ関数 #reset でエラーリセットを行うこと。
    ///
    /// @par 利用可能タイミングについて
    /// - エラー発生情報は Core クラスのメンバ関数 Core#isReady が
    ///   false を返す場合でも参照することができる。
    /// - エラー操作(#set, #reset)やエラーログ情報(#getLog)については
    ///   Core クラスのメンバ関数 Core#isReady が true を返すまで利用できない。
    ///
    /// @par エラー発生時の挙動
    /// - 発生したエラーに関連するモジュールは更新されなくなる。
    ///   関連しないモジュールは引き続き更新される。
    ///     - 例えばネットワーク周りのエラー発生時、 Network クラス等は更新されないが、
    ///       Jvs クラス等は引き続き更新され、スイッチ入力を得ることもできる。
    /// - 全プレイヤーのゲームプレイ状態は強制的に解除される。
    ///     - Sequence クラスのメンバ関数 Sequence#isPlayingAny が false を返す状態となる。
    ///     - その時点でのプレイは無かったことになり、ブックキーピングに記録されない。
    /// - ゲームテストモード中に新たなエラーは発生しない。
    ///
    /// @par エラーリセットについて
    /// - メンバ関数 #getResetType の返すエラーリセット種別によってリセット方法が異なる。
    ///   詳しくは @ref ErrorResetType 列挙の説明を参照すること。
    /// - エラーの根本原因を解消していない場合、リセットしても即座に再発する場合がある。
    /// - ゲームテストモードを開始してもリセットされないエラーの場合、
    ///   ゲームテストモード中であっても Error クラスはエラー情報を返し続ける。
    ///     - アプリでエラー画面表示処理を実装する際には、
    ///       ゲームテストモード中には表示しないような組み方をする必要がある。
    ///
    /// @ingroup g_common
    class Error
    {
        // 下記は暗黙の定義を用いる。
        //Error() = default;
        //‾Error() = default;
        //Error(const Error&) = default;
        //Error& operator=(const Error&) = default;

    public:
        // エラー発生情報

        /// @brief エラー情報インスタンスを取得する。
        /// @return エラー情報インスタンス。
        /// @note Core#isReady が false を返す状態でも利用可能。
        const ErrorInfo& getInfo() const;

        /// @brief エラーが発生しているか否かを取得する。
        /// @retval true  エラーが発生している場合。
        /// @retval false エラーが発生していない場合。
        /// @note Core#isReady が false を返す状態でも利用可能。
        ///
        /// getInfo().isOccurred() を返す。
        bool isOccurred() const
        {
            return getInfo().isOccurred();
        }

        /// @brief エラー番号を取得する。
        /// @return エラー番号。エラーが発生していなければ 0 。
        /// @note Core#isReady が false を返す状態でも利用可能。
        ///
        /// getInfo().getNumber() を返す。
        std::uint32_t getNumber() const
        {
            return getInfo().getNumber();
        }

        /// @brief サブエラー番号(枝番)を取得する。
        /// @return サブエラー番号(枝番)。枝番が無いならば 0 。
        /// @note Core#isReady が false を返す状態でも利用可能。
        ///
        /// getInfo().getSubNumber() を返す。
        std::uint32_t getSubNumber() const
        {
            return getInfo().getSubNumber();
        }

        /// @brief エラーメッセージを取得する。
        /// @return エラーメッセージ。エラーが発生していなければ不定値。
        /// @note Core#isReady が false を返す状態でも利用可能。
        ///
        /// getInfo().getMessage() を返す。
        const wchar_t* getMessage() const
        {
            return getInfo().getMessage();
        }

        /// @brief エラーリセット種別を取得する。
        /// @return エラーリセット種別。エラーが発生していなければ不定値。
        /// @note Core#isReady が false を返す状態でも利用可能。
        ///
        /// getInfo().getResetType() を返す。
        ErrorResetType getResetType() const
        {
            return getInfo().getResetType();
        }

        /// @brief エラーをリセット可能か否かを取得する。
        /// @retval true  リセット可能である場合。
        /// @retval false リセット不可能であるか、エラー発生中ではない場合。
        /// @note Core#isReady が false を返す状態でも利用可能。
        ///
        /// エラーが発生しており、かつメンバ関数 #getResetType の戻り値が
        /// ErrorResetType::Any または ErrorResetType::Operation の場合に true を返す。
        ///
        /// この関数が false を返す場合、メンバ関数 #reset は必ず失敗する。
        bool canReset() const;

        /// @brief エラー発生日時を取得する。
        /// @return エラー発生日時。エラーが発生していなければ不定値。
        /// @note Core#isReady が false を返す状態でも利用可能。
        ///
        /// getInfo().getTime() を返す。
        const ::amdaemon::util::DateTime& getTime() const
        {
            return getInfo().getTime();
        }

    public:
        // エラー操作

        /// @brief アプリからエラーを設定する。
        /// @param[in] number エラー番号。 1 以上 amdaemon::ErrorNumberLimit 以下。
        /// @param[in] subNumber
        ///     枝番。 1 以上 amdaemon::ErrorSubNumberLimit 以下。枝番無しならば 0 。
        /// @retval true  エラーを設定できた場合。
        /// @retval false エラーを設定できなかったか、既にエラー発生中である場合。
        ///
        /// @exception Exception
        /// - 引数 number に 0 もしくは
        ///   amdaemon::ErrorNumberLimit より大きい値を指定した場合。
        /// - 引数 subNumber に amdaemon::ErrorSubNumberLimit より大きい値を指定した場合。
        ///
        /// 主にアプリ固有のエラーを発生させる場合に用いる。
        ///
        /// 指定するエラー番号はエラーリソースDLLで定義されていなければならない。
        /// 未定義のエラー番号を渡した場合は ERROR 4103 が代わりに発生する。
        /// その場合もこの関数自体はエラーが設定できたものとして true を返す。
        ///
        /// リソースの言語(日本語、英語等)は Core クラスでの言語設定に準ずる。
        /// 現在の言語名はメンバ関数 Core#getLanguage で取得できる。
        ///
        /// 既にエラーが発生している場合は何もせずに false を返す。
        ///
        /// Daemonプロセスが処理完了するまで呼び出し元スレッドをブロックする。
        bool set(std::uint32_t number, std::uint32_t subNumber = 0);

        /// @brief エラーをリセットする。
        /// @retval true  リセットできた場合。
        /// @retval false リセットできなかったか、エラー発生中ではない場合。
        ///
        /// 所定のエラーリセット操作が行われた場合にこの関数を呼び出すこと。
        /// 操作内容はタイトル依存だが、例えば物理リセットキーを回した時などが該当する。
        ///
        /// メンバ関数 #canReset が false を返す場合、この関数は何も行わずに false を返す。
        /// 即ちこの関数は、メンバ関数 #getResetType の戻り値が
        /// ErrorResetType::Any または ErrorResetType::Operation の場合のみ成功する。
        ///
        /// Daemonプロセスが処理完了するまで呼び出し元スレッドをブロックする。
        bool reset();

    public:
        // エラーログ

        /// @brief エラーログ情報を取得する。
        /// @return エラーログ情報。
        const ErrorLog& getLog() const;

        /// @brief エラーログ情報のクリア処理を要求する。
        /// @retval true  成功した場合。
        /// @retval false 失敗した場合。
        ///
        /// Daemonプロセスが処理完了するまで呼び出し元スレッドをブロックする。
        bool clearLog();
    };

/// @}
} // namespace amdaemon

#endif // AMDAEMON_ERROR_H