Log.h

[詳解]

/// @file
/// @brief ABaaS Log 関連処理を提供するMonostateクラス Log のヘッダ。
///
/// Copyright(C)SEGA

#ifndef AMDAEMON_ABAAS_LOG_H
#define AMDAEMON_ABAAS_LOG_H

#include "amdaemon/env.h"

#include <cstdint>

namespace amdaemon
{
namespace abaas
{
/// @addtogroup g_abaas
/// @{

    /// @brief ABaaS Log 関連処理を提供するMonostateクラス。
    ///
    /// Core クラスのメンバ関数 Core#execute 呼び出しによって内容が更新される。
    ///
    /// 共通サーバにログファイルやエラーメッセージを収集する機能を提供する。
    /// ALL.Net認証処理が無効である場合、メンバ関数 #getRootPath 以外は利用できない。
    ///
    /// @par 通信タイミングについて
    /// ゲームプレイ中の通信処理等を阻害しないよう、
    /// ABaaS Log の通信処理は下記のすべてを満たしている間のみ行われる。
    /// @par
    /// - ALL.Net認証に成功済みである。
    /// - ゲームプレイ中ではない。
    ///
    /// @ingroup g_common
    class Log
    {
    public:
        // 下記は暗黙の定義を用いる。
        //Log() = default;
        //Log(const Log&) = default;
        //‾Log() = default;
        //Log& operator=(const Log&) = default;

        /// @brief ABaaS Log 機能を利用可能であるか否かを取得する。
        /// @retval true  利用可能である場合。
        /// @retval false 機能が無効である場合。
        ///
        /// 条件式 (getRootPath()[0] != L'¥0') の結果を返す。
        bool isAvailable() const;

        /// @brief ログ収集対象となるファイル群のルートディレクトリパスを取得する。
        /// @return ルートディレクトリパス。 ABaaS Log 機能が無効である場合は空文字列。
        ///
        /// このディレクトリ以下に置かれているファイルがログ収集対象となる。
        /// サブディレクトリも含むが、絶対パスが長すぎるファイルは除外される。
        ///
        /// ファイルのアップロード指示はサーバの管理ページより行う。
        ///
        /// ALL.Net認証機能が無効であってもこの関数は利用可能である。
        const wchar_t* getRootPath() const;

        /// @brief ログ収集サーバの生存が確認できているか否かを取得する。
        /// @retval true  生存が確認できている場合。
        /// @retval false 生存していないか、生存が確認できない場合。
        ///
        /// 生存確認を一度行った後はしばらく時間を空けるようになっているため、
        /// 実際の生存状態とは異なる値を返す場合がある。
        bool isServerAlive() const;

        /// @brief ファイルのアップロード処理中であるか否かを取得する。
        /// @retval true  アップロード処理中である場合。
        /// @retval false アップロード処理中ではないか、アップロード不可能な状態である場合。
        ///
        /// この関数が true を返す間はゲームプレイ開始しないことを推奨する。
        /// ただしログファイルの重要性が低い場合等はその限りではない。
        ///
        /// この関数の戻り値は下記のように決定される。
        ///
        /// - ABaaS Log 機能またはALL.Net認証機能が無効である場合は false 。
        /// - 正常にアップロード処理中である場合は true 。
        /// - アップロード待ちのファイルが存在しない場合は false 。
        /// - アップロード指示ファイル一覧をサーバから取得できない場合や、
        ///   アップロード中にサーバとの通信が切断された場合、一定時間は true 。
        ///   復旧の見込みがないと判断した後は false 。
        bool isUploading() const;

        /// @brief アップロード待ちのファイル数を取得する。
        /// @return アップロード待ちのファイル数。取得できていない場合は -1 。
        ///
        /// サーバの管理ページよりアップロード指示されており、
        /// なおかつまだアップロード済みでないファイルの数を返す。
        ///
        /// サーバからアップロード指示ファイル一覧を取得できていない場合は -1 を返す。
        ///
        /// アップロード処理完了を待つ目的であればメンバ関数 #isUploading の使用を推奨する。
        std::int32_t getUploadingFileCount() const;

        /// @brief エラー事象メッセージを送信キューに追加する。
        /// @param[in] message エラー事象メッセージ。
        /// @retval true  送信キューへの追加に成功した場合。
        /// @retval false 送信キュー上限により追加できなかったか、機能が無効である場合。
        ///
        /// @exception Exception
        /// - 引数 message に nullptr を指定した場合。
        /// - 引数 message に空文字列を指定した場合。
        ///
        /// サーバの管理ページでエラーリストとして参照できる文字列を送信要求する。
        /// タイトルのポリシー次第では、エラーと無関係な文字列でも構わない。
        /// ただし、 ABaaS Log の内部エラーもこの機能を利用してサーバに送信される。
        ///
        /// 送信キューの上限は 100 件である。
        /// サーバ不通状態でこの関数を呼び出し続ける等により送信キュー上限を超えた場合、
        /// 指定したメッセージは追加されず、
        /// 代わりにキュー上限に達したことを示すエラーメッセージが優先的に送信される。
        ///
        /// 引数 message は、UTF-8文字列に変換後、最大 1024 バイトが送信対象となる。
        /// サイズ超過分は切り捨てられる。
        bool putErrorMessage(const wchar_t* message);
    };

/// @}
} // namespace abaas
} // namespace amdaemon

#endif // AMDAEMON_ABAAS_LOG_H