Backup.h

[詳解]

/// @file
/// @brief 不揮発データバックアップ処理を提供するMonostateクラス Backup のヘッダ。
///
/// Copyright(C)SEGA

#ifndef AMDAEMON_BACKUP_H
#define AMDAEMON_BACKUP_H

#include "amdaemon/env.h"
#include "amdaemon/BackupRecord.h"
#include "amdaemon/BackupRecordStatus.h"
#include "amdaemon/RequestState.h"

#include <vector>
#include <cstddef>

namespace amdaemon
{
/// @addtogroup g_backup
/// @{

    /// @brief 不揮発メモリアクセス処理を提供するMonostateクラス。
    ///
    /// Core クラスのメンバ関数 Core#execute 呼び出しによって内容が更新される。
    ///
    /// @par 初期化手順
    /// -# 必要であれば、メンバ関数 #setAsync により非同期モード設定を行う。
    /// -# メンバ関数 #setupRecords によりバックアップレコード情報配列の登録を要求する。
    ///     - この段階ではまだ実際の登録処理は行われていない。
    /// -# Core クラスのメンバ関数 Core#execute 呼び出しにより登録処理が行われる。
    ///     - 非同期モードの場合、1回の呼び出しでは完了せず、
    ///       完了するまでの間メンバ関数 #isBusy が true を返し続ける。
    /// -# メンバ関数 #isSetupSucceeded により登録が成功したか否か取得できる。
    ///    メンバ関数 #getRecordStatus により個々のレコードの状態が取得できる。
    ///
    /// @par データ保存手順
    /// -# レコード情報に登録したデータアドレス先のデータを必要に応じて書き換える。
    /// -# 書き換えたデータのレコードに対してメンバ関数 #saveRecord を呼び出す。
    ///     - この段階ではまだ実際の保存処理は行われていない。
    ///     - 即時書き出しを行いたい場合はメンバ関数 #executeSave を呼び出す。
    /// -# Core クラスのメンバ関数 Core#execute 呼び出しにより保存処理が行われる。
    ///     - 非同期モードの場合、1回の呼び出しでは完了せず、
    ///       完了するまでの間メンバ関数 #isBusy が true を返し続ける。
    ///     - アクセスエラーで書き込み失敗した場合は Error クラスにエラーが設定される。
    ///
    /// @par 要求関数について
    /// RequestState インスタンスを返す各メンバ関数は、即座に処理を行うわけではなく、
    /// 処理要求を内部キューに登録することのみを行う。
    /// 要求が実際にDaemonプロセスへ送信されるのは
    /// Core クラスのメンバ関数 Core#execute を呼び出した時点となる。
    /// RequestState インスタンスの各メンバ関数により、
    /// 対象の要求が処理完了済みか否かや処理の成否等を調べることができる。
    /// @par
    /// メンバ関数 #setupRecords を1フレーム内で連続して複数回呼び出した場合、
    /// その度に要求が上書きされ、最後に行った要求のみがDaemonプロセスへ送られる。
    /// @par
    /// メンバ関数 #saveRecord および #saveRecordByAddress を1フレーム内で連続して
    /// 複数回呼び出した場合、それらの要求は一度にまとめてDaemonプロセスへ送られる。
    /// @par
    /// メンバ関数 #setupRecords と #saveRecord, #saveRecordByAddress を互いの要求が
    /// 処理未完了の状態で混在して呼び出すことはできない。
    /// 呼び出そうとした場合、その関数は無効な RequestState インスタンスを返す。
    /// 意図しないデータ書き出しを防ぐためにこのような処理になっている。
    ///
    /// @par 同期モードについて
    /// メンバ関数 #setAsync によって処理を同期または非同期で行うように設定できる。
    /// 既定では同期モード(false)になっている。
    /// @par
    /// 同期モードでは、 Core クラスのメンバ関数 Core#execute を呼び出した時点で、
    /// 現在要求している処理がすべて完了するまで呼び出し元スレッドをブロックする。
    /// @par
    /// 非同期モードでは、 Core クラスのメンバ関数 Core#execute
    /// を何度か呼び出すまで処理が完了しない。具体的な回数はDaemonプロセスの処理速度による。
    /// 未処理の要求が存在するか否かはメンバ関数 #isBusy で取得できる。
    /// 処理中に新たな要求を行った場合、現在の処理が完了するまで保留される。
    ///
    /// @ingroup g_common
    class Backup
    {
    public:
        /// @brief 登録可能な最大レコード数を取得する。
        /// @return 登録可能な最大レコード数。
        static std::size_t getMaxRecordCount();

    public:
        // 下記は暗黙の定義を用いる。
        //Backup() = default;
        //‾Backup() = default;
        //Backup(const Backup&) = default;
        //Backup& operator=(const Backup&) = default;

        /// @brief 処理要求を非同期モードで行うか否かを取得する。
        /// @retval true  非同期モードで行う場合。
        /// @retval false 同期モードで行う場合。(既定値)
        bool isAsync() const;

        /// @brief 処理要求を非同期モードで行うか否かを設定する。
        /// @param[in] async
        ///     非同期モードで行うならば true 。同期モードで行うならば false 。
        ///
        /// 既定では同期モードになっている。
        void setAsync(bool async);

        /// @brief 処理未完了の要求があるか否かを取得する。
        /// @retval true  処理未完了の要求がある場合。
        /// @retval false アイドル状態の場合。
        ///
        /// 初期状態では false を返す。
        ///
        /// 下記のメンバ関数が正常に完了すると true を返すようになる。
        ///
        /// - #setupRecords
        /// - #saveRecord
        /// - #saveRecordByAddress
        /// - #saveAllRecords
        ///
        /// その後、 Core クラスのメンバ関数 Core#execute 呼び出し等によって
        /// 実際の処理が完了すると、再び false を返すようになる。
        bool isBusy() const;

        /// @brief バックアップレコード情報配列をセットアップするように要求する。
        /// @param[in] records バックアップレコード情報配列。
        /// @param[in] count records の有効要素数。
        /// @param[in] gameId
        ///     バックアップデータのゲームID。キーチップから取得させるなら nullptr 。
        ///     別ゲームIDのバックアップデータを取得したい場合は明示する必要がある。
        /// @return 要求状態値。引数や状態が不正な場合は無効値。
        /// @see isBusy
        ///
        /// @exception Exception
        /// - 引数 records に nullptr を指定した場合。
        /// - 引数 records に不正な値の要素が含まれている場合。
        /// - 引数 count に登録可能な最大レコード数よりも大きい値を指定した場合。
        ///   登録可能な最大レコード数は静的メンバ関数 #getMaxRecordCount で取得できる。
        /// - 引数 gameId に文字数が 4 文字以外の文字列を指定した場合。
        ///
        /// この関数はセットアップ処理の要求のみを行う。
        /// 実際の処理は、 Core クラスのメンバ関数 Core#execute 呼び出しによって行われる。
        ///
        /// 下記のいずれかを満たす場合、この関数は無効な要求状態値を返す。
        ///
        /// - メンバ関数 #saveRecord または #saveRecordByAddress によるデータ保存要求が
        ///   完了していない。
        /// - 例外フック関数によって例外スローが抑止された。
        ///
        /// 無効な要求状態値が返ってきた場合、要求は発行されていない。
        /// 有効であるか否かは
        /// RequestState クラスのメンバ関数 RequestState#valid で判別できる。
        ///
        /// 要求が成功すると、即座にレコード情報が無効となり、下記のように動作する。
        ///
        /// - メンバ関数 #isSetupSucceeded は false を返す。
        /// - メンバ関数 #getRecordCount は 0 を返す。
        /// - メンバ関数 #getRecordStatus は BackupRecordStatus::InvalidCall を返す。
        ///
        /// 要求がDaemonプロセスによって正常に処理されることで有効になる。
        ///
        /// この関数を1フレーム内で連続して複数回呼び出した場合、
        /// その度に要求が上書きされ、最後に行った要求のみがDaemonプロセスへ送られる。
        RequestState setupRecords(
            const BackupRecord records[],
            std::size_t count,
            const wchar_t* gameId = nullptr);

        /// @brief バックアップレコード情報配列をセットアップするように要求する。
        /// @param[in] records バックアップレコード情報配列。
        /// @param[in] gameId
        ///     バックアップデータのゲームID。キーチップから取得させるなら nullptr 。
        ///     別ゲームIDのバックアップデータを取得したい場合は明示する必要がある。
        /// @return 要求状態値。引数や状態が不正な場合は無効値。
        /// @see setupRecords(const BackupRecord[], std::size_t, const wchar_t*)
        /// @note std::vector<BackupRecord> による登録を行うオーバロード。
        RequestState setupRecords(
            const std::vector<BackupRecord>& records,
            const wchar_t* gameId = nullptr)
        {
            return setupRecords(records.data(), records.size(), gameId);
        }

        /// @brief バックアップレコード情報配列をセットアップするように要求する。
        /// @tparam Count 配列要素数。
        /// @param[in] records バックアップレコード情報配列。
        /// @param[in] gameId
        ///     バックアップデータのゲームID。キーチップから取得させるなら nullptr 。
        ///     別ゲームIDのバックアップデータを取得したい場合は明示する必要がある。
        /// @return 要求状態値。引数や状態が不正な場合は無効値。
        /// @see setupRecords(const BackupRecord[], std::size_t, const wchar_t*)
        /// @note 組み込み配列による登録を行うオーバロード。
        template<std::size_t Count>
        RequestState setupRecords(
            const BackupRecord (&records)[Count],
            const wchar_t* gameId = nullptr)
        {
            return setupRecords(records, Count, gameId);
        }

        /// @brief 直近のセットアップ処理が成功したか否かを取得する。
        /// @retval true  成功した場合。
        /// @retval false 失敗したか、まだ完了していない場合。
        ///
        /// 個々のレコードのデータが壊れていたりする場合でもこの関数は true を返す。
        /// 個々のレコードの状態はメンバ関数 #getRecordStatus で取得すること。
        ///
        /// この関数が false を返すのは、デバイス容量に対してレコードサイズの指定が
        /// 大きすぎる等、レコード情報自体に不備がある場合のみである。
        bool isSetupSucceeded() const;

        /// @brief 現在の有効レコード数を取得する。
        /// @return 有効レコード数。セットアップが未完了ならば 0 。
        std::size_t getRecordCount() const;

        /// @brief 直近のセットアップにおけるバックアップレコードステータスを取得する。
        /// @param[in] recordIndex バックアップレコードインデックス。
        /// @return バックアップレコードステータス。
        ///
        /// @exception Exception
        /// - セットアップが未完了である場合。
        /// - 引数 recordIndex に現在の有効レコード数以上の値を指定した場合。
        ///   現在の有効レコード数はメンバ関数 #getRecordCount で取得できる。
        ///
        /// 例外フック関数によって例外スローが抑止された場合は
        /// BackupRecordStatus::InvalidCall を返す。
        BackupRecordStatus getRecordStatus(std::size_t recordIndex) const;

        /// @brief 直近のセットアップにおけるバックアップレコードステータスを取得する。
        /// @param[in] recordAddress バックアップレコードデータのアドレス。
        /// @return バックアップレコードステータス。
        ///
        /// @exception Exception
        /// - セットアップが未完了である場合。
        /// - 引数 recordAddress に nullptr を指定した場合。
        /// - 引数 recordAddress に指定した値が有効なデータアドレスを指していない場合。
        /// - 引数 recordAddress に指定した値を持つレコードが複数存在する場合。
        ///
        /// バックアップレコードデータのアドレスを指定して保存要求を行う。
        /// アドレスとは、 BackupRecord 構造体の
        /// BackupRecord#address メンバに設定したものである。
        ///
        /// 内部でバックアップレコードデータが先頭から順に検索され、
        /// 該当レコードが見つかった後はメンバ関数 #getRecordStatus と同等の処理を行う。
        ///
        /// 該当レコードが見つからなかった場合や複数見つかった場合は例外をスローする。
        /// 例外フック関数によって例外スローが抑止された場合は
        /// BackupRecordStatus::InvalidCall を返す。
        BackupRecordStatus getRecordStatusByAddress(const void* recordAddress) const;

        /// @brief バックアップレコードデータを保存するように要求する。
        /// @param[in] recordIndex バックアップレコードインデックス。
        /// @return 要求状態値。引数や状態が不正な場合は無効値。
        /// @see executeSave, isBusy
        ///
        /// @exception Exception
        /// - セットアップが未完了である場合。
        /// - 引数 recordIndex に現在の有効レコード数以上の値を指定した場合。
        ///   現在の有効レコード数はメンバ関数 #getRecordCount で取得できる。
        ///
        /// この関数は保存処理の要求のみを行う。
        /// 実際の処理は、 Core クラスのメンバ関数 Core#execute 呼び出しか、
        /// 当クラスのメンバ関数 #executeSave 呼び出しによって行われる。
        ///
        /// 下記のいずれかを満たす場合、この関数は無効な要求状態値を返す。
        ///
        /// - メンバ関数 #setupRecords によるセットアップ要求が完了していない。
        /// - 例外フック関数によって例外スローが抑止された。
        ///
        /// 無効な要求状態値が返ってきた場合、要求は発行されていない。
        /// 有効であるか否かは
        /// RequestState クラスのメンバ関数 RequestState#valid で判別できる。
        ///
        /// この関数を1フレーム内で連続して複数回呼び出した場合、
        /// それらの要求は一度にまとめてDaemonプロセスへ送られる。
        RequestState saveRecord(std::size_t recordIndex);

        /// @brief バックアップレコードデータを保存するように要求する。
        /// @param[in] recordAddress バックアップレコードデータのアドレス。
        /// @return 要求状態値。引数や状態が不正な場合は無効値。
        /// @see executeSave, isBusy
        ///
        /// @exception Exception
        /// - セットアップが未完了である場合。
        /// - 引数 recordAddress に nullptr を指定した場合。
        /// - 引数 recordAddress に指定した値が有効なデータアドレスを指していない場合。
        ///
        /// バックアップレコードデータのアドレスを指定して保存要求を行う。
        /// アドレスとは、 BackupRecord 構造体の
        /// BackupRecord#address メンバに設定したものである。
        ///
        /// 内部でバックアップレコードデータが先頭から順に検索され、
        /// 該当レコードが見つかった後はメンバ関数 #saveRecord と同等の処理を行う。
        /// 該当レコードが複数見つかった場合はそれらすべてを対象とする。
        ///
        /// 該当レコードが見つからなかった場合は例外をスローする。
        /// 例外フック関数によって例外スローが抑止された場合は無効な要求状態値を返す。
        RequestState saveRecordByAddress(const void* recordAddress);

        /// @brief すべてのバックアップレコードデータを保存するように要求する。
        /// @return 要求状態値。状態が不正な場合は無効値。
        /// @see executeSave, isBusy
        ///
        /// @exception Exception
        /// セットアップが未完了である場合。
        ///
        /// 登録されている全バックアップレコードの保存要求を行う。
        ///
        /// この関数は保存処理の要求のみを行う。
        /// 実際の処理は、 Core クラスのメンバ関数 Core#execute 呼び出しか、
        /// 当クラスのメンバ関数 #executeSave 呼び出しによって行われる。
        ///
        /// メンバ関数 #setupRecords によるセットアップ要求が完了していない場合、
        /// この関数は無効な要求状態値を返す。
        /// 無効な要求状態値が返ってきた場合、要求は発行されていない。
        /// 有効であるか否かは
        /// RequestState クラスのメンバ関数 RequestState#valid で判別できる。
        ///
        /// この関数を1フレーム内で連続して複数回呼び出した場合、
        /// 2回目以降は何もせずに有効な要求状態値を返す。
        RequestState saveAllRecords();

        /// @brief バックアップレコードデータの保存要求を即座に完了させる。
        /// @retval true  保存処理に成功した場合。
        /// @retval false 保存処理に失敗したか、保存要求が行われていない場合。
        ///
        /// メンバ関数 #saveRecord 等によるバックアップレコードデータの保存要求は、
        /// 通常 Core クラスのメンバ関数 Core#execute が呼び出されるまで実施されない。
        ///
        /// この関数を呼び出すと、その時点で未完了の保存要求を、
        /// Core#execute の呼び出しを待たず即座に完了させる。
        ///
        /// この関数は同期モード、非同期モードには依存しない。
        /// どちらのモードであっても動作に違いはない。
        ///
        /// 未完了の保存要求が存在しない場合、この関数は何も行わずに false を返す。
        ///
        /// Daemonプロセスが処理完了するまで呼び出し元スレッドをブロックする。
        bool executeSave();
    };

/// @}
} // namespace amdaemon

#endif // AMDAEMON_BACKUP_H