MGL::File::ThrowingUtility#

概要#

MGL::File::ThrowingUtilityはファイルシステムに対する各種機能を提供し、失敗時に例外によって失敗理由を送出するクラスです。

失敗理由を手動でハンドリングしたい場合はMGL::File::Utilityを使用してください。

このクラスが扱うファイルのパスは、特に指定がない限りはマウント名付きのフォーマットとなります。パスのフォーマットについてはファイルパスのフォーマットを参照してください。

宣言#

namespace MGL::File
{
    class ThrowingUtility
}

メンバ情報#

種類	名前	内容
関数	GetSize	サイズの取得
関数	MakeDirectory	ディレクトリの生成
関数	Move	ファイルの移動・リネーム
関数	Remove	ファイルの削除
関数	Copy	ファイルのコピー
関数	Exists	ファイルが存在するかをチェック
関数	IsSystemNativeFile	ファイルがシステム標準のファイルかをチェック
関数	Mount	ファイルまたはディレクトリのマウント
関数	Unmount	マウントの解除
関数	Remount	再マウント
関数	IsMounted	マウント済みかを取得
関数	GetSystemNativePath	マウントパスからシステム標準のパスに変換
関数	AddDelegate	ファイルデリゲートを追加
関数	RemoveDelegate	ファイルデリゲートを削除
関数	SetDefaultDelegate	デフォルトのファイルデリゲートを設定

GetSize#

サイズの取得

宣言#

namespace MGL::File
{
    class ThrowingUtility
    {
    public:
        [[nodiscard]] size_t GetSize(const PathView &path);
    };
}

引数#

const MGL::File::PathView &path: サイズを取得するファイルのパス

戻り値#

size_t: 指定されたファイルのサイズ

例外#

MGL::File::Result: 失敗理由

説明#

指定されたパスが示すファイルのサイズをバイト数で取得します。

この関数はMGL::File::Handle::GetSizeやMGL::File::ThrowingHandle::GetSizeとは異なり、ファイルをオープンする事なく利用可能です。

取得に失敗した場合は失敗理由を表すMGL::File::Resultを例外として送出します。

利用例#

try
{
    MGL::File::ThrowingUtility utility;

    // ファイルサイズを取得
    auto size = utility.GetSize("$user/test.data");
    printf("ファイルサイズ: %zu\n", size);
}
catch (MGL::File::Result result)
{
    printf("処理失敗: %d", result.GetErrorCode());
}

MakeDirectory#

ディレクトリの生成

宣言#

namespace MGL::File
{
    class ThrowingUtility
    {
    public:
        void MakeDirectory(const PathView &path);
    };
}

引数#

const MGL::File::PathView &path: 生成するディレクトリのパス

例外#

MGL::File::Result: 失敗理由

説明#

指定されたパスのディレクトリを生成します。既に同名のディレクトリが存在している場合は何も行わず、成功として扱います。

生成に失敗した場合は失敗理由を表すMGL::File::Resultを例外として送出します。

利用例#

try
{
    MGL::File::ThrowingUtility utility;

    // ディレクトリを生成
    utility.MakeDirectory("$user/test-directory");
}
catch (MGL::File::Result result)
{
    printf("処理失敗: %d", result.GetErrorCode());
}

Move#

ファイルの移動・リネーム

宣言#

namespace MGL::File
{
    class ThrowingUtility
    {
    public:
        void Move(const PathView &sourcePath, const PathView &destPath);
    };
}

引数#

const MGL::File::PathView &sourcePath: 変更元のファイルのパス
const MGL::File::PathView &destPath: 変更先のファイルのパス

例外#

MGL::File::Result: 失敗理由

説明#

指定したパスのファイルに別のパスを割り当てます。この動作は主にファイルの移動とリネームに使用します。

処理に失敗した場合は失敗理由を表すMGL::File::Resultを例外として送出します。

利用例#

try
{
    MGL::File::ThrowingUtility utility;

    // ファイルをリネーム
    utility.Move("$user/test.data", "$user/new-name-file.data");
}
catch (MGL::File::Result result)
{
    printf("処理失敗: %d", result.GetErrorCode());
}

Remove#

ファイルの削除

宣言#

namespace MGL::File
{
    class ThrowingUtility
    {
    public:
        void Remove(const PathView &path);
    };
}

引数#

const MGL::File::PathView &path: 削除するファイルのパス

例外#

MGL::File::Result: 失敗理由

説明#

指定されたパスのファイルを削除します。

処理に失敗した場合は失敗理由を表すMGL::File::Resultを例外として送出します。

利用例#

try
{
    MGL::File::ThrowingUtility utility;

    // ファイルを削除
    utility.Remove("$user/test.data");
}
catch (MGL::File::Result result)
{
    printf("処理失敗: %d", result.GetErrorCode());
}

Copy#

ファイルのコピー

宣言#

namespace MGL::File
{
    class ThrowingUtility
    {
    public:
        void Copy(const PathView &sourcePath, const PathView &destPath);
    };
}

引数#

const MGL::File::PathView &sourcePath: コピー元のファイルのパス
const MGL::File::PathView &destPath: コピー先のファイルのパス

例外#

MGL::File::Result: 失敗理由

説明#

コピー元のファイルの複製をコピー先のファイルに生成します。

この関数はファイルの内容のみをコピーします。タイムスタンプや権限など、システムが管理するファイル属性はコピーされません。

処理に失敗した場合は失敗理由を表すMGL::File::Resultを例外として送出します。

利用例#

try
{
    MGL::File::ThrowingUtility utility;

    // ファイルをコピー
    utility.Copy("$user/test.data", "$user/duplicated-test.data");
}
catch (MGL::File::Result result)
{
    printf("処理失敗: %d", result.GetErrorCode());
}

Exists#

ファイルが存在するかをチェック

宣言#

namespace MGL::File
{
    class ThrowingUtility
    {
    public:
        [[nodiscard]] bool Exists(const PathView &path);
    };
}

引数#

const MGL::File::PathView &path: チェックするファイルのパス

戻り値#

bool: 存在する場合はtrue、存在しない場合はfalse

例外#

MGL::File::Result: 失敗理由

説明#

指定されたパスのファイルが存在するかをチェックし、存在する場合はtrueを返します。

正常に判別できなかった場合は失敗理由を表すMGL::File::Resultを例外として送出します。

利用例#

try
{
    constexpr const char *kFilePath = "$user/test.data";

    MGL::File::ThrowingUtility utility;

    // ファイルが存在しているかをチェック
    if (utility.Exists(kFilePath))
    {
        printf("%s は存在している\n", kFilePath);
    }
    else
    {
        printf("%s は存在していない\n", kFilePath);
    }
}
catch (MGL::File::Result result)
{
    printf("処理失敗: %d", result.GetErrorCode());
}

IsSystemNativeFile#

ファイルがシステム標準のファイルかをチェック

宣言#

namespace MGL::File
{
    class ThrowingUtility
    {
    public:
        [[nodiscard]] bool IsSystemNativeFile(const PathView &path);
    };
}

引数#

const MGL::File::PathView &path: チェックするファイルのパス

戻り値#

bool: システム標準のファイルである場合はtrue、そうでない場合はfalse

例外#

MGL::File::Result: 失敗理由

説明#

指定されたファイルがシステム標準のファイルシステムで扱えるものかを取得します。

特殊なアクセスを行うファイルデリゲートを用いた場合、この戻り値はfalseになる場合があります。MGLの標準のファイルデリゲートを用いている限りは常にtrueとなります。ファイルデリゲートの詳細はファイルデリゲートの作成（準備中）を参照してください。

正常に取得できなかった場合は失敗理由を表すMGL::File::Resultを例外として送出します。

利用例#

try
{
    constexpr const char *kFilePath = "$user/test.data";

    MGL::File::ThrowingUtility utility;

    // ファイルが存在しているかをチェック
    if (utility.IsSystemNativeFile(kFilePath))
    {
        printf("%s はシステム標準のファイル\n", kFilePath);
    }
    else
    {
        printf("%s はシステムが直接扱えないファイル\n", kFilePath);
    }
}
catch (MGL::File::Result result)
{
    printf("処理失敗: %d", result.GetErrorCode());
}

Mount#

ファイルまたはディレクトリのマウント

宣言#

namespace MGL::File
{
    class ThrowingUtility
    {
    public:
        void Mount(
            const PathView &mountName,
            const PathView &path,
            MountAccessType accessType,
            DelegateKey delegateKey = Mounter::kDefaultDelegateKey);
    };
}

引数#

const MGL::File::PathView &mountName: 設定するマウント名
const MGL::File::PathView &path: マウント先のディレクトリまたはファイルのパス
MGL::File::MountAccessType accessType: アクセスタイプ
MGL::File::DelegateKey delegateKey: マウント先を扱うデリゲートの指定。省略時はデフォルトのデリゲートキー

例外#

MGL::File::Result: 失敗理由

説明#

ディレクトリまたはファイルを指定の名前でマウントし、その名前を用いてアクセス可能にします。

mountNameにはマウント名を、pathにはマウント先のディレクトリまたはファイルのパスを指定します。MGLの標準のファイルデリゲートではディレクトリのマウントにのみ対応しています。

accessTypeはマウント先のアクセス権限を指定します。ReadOnlyを指定した場合、マウント先が本来書き込み可能な領域であったとしても、そのマウント先への書き込み動作が制限されるようになります。Writableを指定した場合は書き込み動作の制限はありませんが、マウント先が読み込み専用の領域であった場合は失敗する可能性があります。

delegateKeyはマウント先を扱うデリゲートの指定になります。この引数はアーカイブファイルを直接扱う場合など、ファイルアクセスを特殊化したい場合に利用します。省略時はデフォルトのファイルデリゲートを用いてマウント先を扱います。

マウントの詳細についてはディレクトリやファイルのマウントを参照してください。

利用例#

try
{
    MGL::File::ThrowingUtility utility;

    // ユーザーディレクトリの "test-directory" を "test" という名前でマウント
    utility.Mount("test", "$user/test-directory", MGL::File::MountAccessType::ReadOnly);
}
catch (MGL::File::Result result)
{
    printf("処理失敗: %d", result.GetErrorCode());
}

// 以降、"$user/test-directory/file-path" を "$test/file-path" として扱えるようになる。
// マウント時のアクセスタイプを ReadOnly にしているため、"$test/" で指定したパスは書き込み動作が禁止される。

Unmount#

マウントの解除

宣言#

namespace MGL::File
{
    class ThrowingUtility
    {
    public:
        void Unmount(const PathView &mountName);
    };
}

引数#

const MGL::File::PathView &mountName: 解除するマウント名

例外#

MGL::File::Result: 失敗理由

説明#

指定したマウント名のマウント解除を行います。

処理に失敗した場合は失敗理由を表すMGL::File::Resultを例外として送出します。

利用例#

try
{
    MGL::File::ThrowingUtility utility;

    // "test' のマウントを解除
    utility.Unmount("test");
}
catch (MGL::File::Result result)
{
    printf("処理失敗: %d", result.GetErrorCode());
}

Remount#

再マウント

宣言#

namespace MGL::File
{
    class ThrowingUtility
    {
    public:
        void Remount(
            const PathView &mountName,
            const PathView &path,
            MountAccessType accessType,
            DelegateKey delegateKey = Mounter::kDefaultDelegateKey);
    };
}

引数#

const MGL::File::PathView &mountName: 設定するマウント名
const MGL::File::PathView &path: マウント先のディレクトリまたはファイルのパス
MGL::File::MountAccessType accessType: アクセスタイプ
MGL::File::DelegateKey delegateKey: マウント先を扱うデリゲートの指定。省略時はデフォルトのデリゲートキー

例外#

MGL::File::Result: 失敗理由

説明#

指定したマウント名に対し、UnmountとMountを順に実行します。

詳細についてはそれぞれの説明と利用例を参照してください。

IsMounted#

マウント済みかを取得

宣言#

namespace MGL::File
{
    class ThrowingUtility
    {
    public:
        [[nodiscard]] static bool IsMounted(const PathView &mountName) noexcept;
    };
}

引数#

const MGL::File::PathView &mountName: チェックするマウント名

戻り値#

bool: マウント済みであればtrue、マウントされていなければfalse

説明#

指定した名前がマウント名として使用されているかを取得します。

この関数は例外を送出しません。

利用例#

MGL::File::ThrowingUtility utility;

// ユーザーディレクトリがマウントされているかを取得
if (utility.IsMounted("user"))
{
    printf("ユーザーディレクトリは利用可能\n");

    // Windows, macOS, iOS/iPadOS の標準構成は初期化時に自動でマウントされるため、
    // 通常はこちらに到達する
}
else
{
    printf("ユーザーディレクトリは利用不可\n");

    // tvOSはユーザーディレクトリを持たないため、通常はこちらに到達する
}

GetSystemNativePath#

マウントパスからシステム標準のパスに変換

宣言#

namespace MGL::File
{
    class ThrowingUtility
    {
    public:
        [[nodiscard]] STL::string GetSystemNativePath(const PathView &path);
    };
}

引数#

const MGL::File::PathView &path: MGLが扱うマウントパス

戻り値#

MGL::STL::string: システム標準のパス

例外#

MGL::File::Result: 失敗理由

説明#

MGLが扱うマウント名を、システム標準のパスに変換します。

引数に指定するパスはIsSystemNativeFileがtrueを返すパスである必要があります。変換を行うのはマウント名に関連付けられたデリゲートであり、デリゲートがシステム標準のファイルシステムを扱うものでない場合は変換できません。

正常に変換できなかった場合は失敗理由を表すMGL::File::Resultを例外として送出します。

注釈

標準のWindows向けファイルデリゲートは指定されたパスをドライブレターから始まる形式に変換しますが、次の点で標準フォーマットと相違しています。

パスの区切り文字は'/'（0x2F）を使用
文字コードはUTF-8

変換結果をWin32 APIなどに渡す場合、パスの区切り文字はそのまま使用できますが、文字コードは変換が必要になる場合があります。

利用例#

try
{
    MGL::File::ThrowingUtility utility;

    // ユーザーディレクトリのパスを取得
    auto userDirectoryPath = utility.GetSystemNativePath("$user");
    printf("ユーザーディレクトリ: %s\n", userDirectoryPath.c_str());
}
catch (MGL::File::Result result)
{
    printf("処理失敗: %d", result.GetErrorCode());
}

AddDelegate#

ファイルデリゲートを追加

宣言#

namespace MGL::File
{
    class ThrowingUtility
    {
    public:
        template <class DelegateClass, class... Args>
        constexpr void AddDelegate(DelegateKey key, Args... args);
    };
}

引数#

DelegateClass: 追加するファイルデリゲートのクラス名
MGL::File::DelegateKey key: 関連付けるデリゲートキー
Args... args: ファイルデリゲートのコンストラクタに渡す引数リスト

例外#

MGL::File::Result: 失敗理由

説明#

ファイルデリゲートを追加するためのテンプレート関数です。この関数で追加したファイルデリゲートはMountの際にデリゲートキーを指定して利用可能となります。

テンプレート引数のDelegateClassには、追加するデリゲートクラスの名前を指定します。

引数のkeyデリゲートキーと呼ばれる値で、そのデリゲートを表す一意の値を指定します。この値はMGL::File::MakeDelegateKeyを用いて生成することを推奨します。

key以降の引数はDelegateClassのコンストラクタの引数にそのまま渡されます。

処理に失敗した場合は失敗理由を表すMGL::File::Resultを例外として送出します。

ファイルデリゲートはプラットフォーム毎の差異を吸収したり、ファイルアクセスを特殊化する目的で使用します。詳細はファイルアクセスおよびファイルデリゲートの作成（準備中）を参照してください。

利用例#

try
{
    MGL::File::ThrowingUtility utility;

    // "YourFileDelegate" という名前のファイルデリゲートを追加
    utility.AddDelegate<YourFileDelegate>(YourFileDelegate::kDelegateKey);
}
catch (MGL::File::Result result)
{
    printf("処理失敗: %d", result.GetErrorCode());
}

RemoveDelegate#

ファイルデリゲートを削除

宣言#

namespace MGL::File
{
    class ThrowingUtility
    {
    public:
        void RemoveDelegate(DelegateKey key);
    };
}

引数#

MGL::File::DelegateKey key: 削除するデリゲートのキー

例外#

MGL::File::Result: 失敗理由

説明#

登録済みのファイルデリゲートを削除します。削除したデリゲートは、それ以降はマウント不可能となります。

使用中のデリゲートを削除した場合、削除処理には成功しますが、デリゲートのインスタンスの削除は全ての使用を終えるまで遅延されます。具体的には、そのデリゲートを用いる全てのマウントが解除され、オープン済みのハンドルがクローズされるまでインスタンスは残り続けます。

全てのデリゲートはアプリケーション終了時に自動で削除されるため、アプリケーション動作中に常駐するデリゲートは明示的に削除する必要はありません。

処理に失敗した場合は失敗理由を表すMGL::File::Resultを例外として送出します。

利用例#

try
{
    MGL::File::ThrowingUtility utility;

    // "YourFileDelegate" を削除
    utility.RemoveDelegate(YourFileDelegate::kDelegateKey);
}
catch (MGL::File::Result result)
{
    printf("処理失敗: %d", result.GetErrorCode());
}

SetDefaultDelegate#

デフォルトのファイルデリゲートを設定

宣言#

namespace MGL::File
{
    class ThrowingUtility
    {
    public:
        static void SetDefaultDelegate(DelegateKey key) noexcept;
    };
}

引数#

MGL::File::DelegateKey key: デフォルトに設定するデリゲートのキー

説明#

標準で利用するデリゲートの設定を行います。

MountおよびRemountにおいて、デリゲートキーを省略した場合はここで設定したデリゲートキーを利用します。

各APIのファイルパスの指定でマウント名を省略した場合、そのパスはこの関数で設定したデリゲートにそのまま渡されます。ただし、そのパスをどのように解釈するかはデリゲート側に委ねられているため、アプリケーション側からはマウント名の省略は推奨されません。

標準構成においては、各プラットフォーム標準のファイルデリゲートが設定されています。通常、このデリゲートのデフォルト設定を変更することは推奨されません。

この関数は例外を送出しません。

利用例#

MGL::File::ThrowingUtility utility;

// "YourFileDelegate" をデフォルトのデリゲートに設定（非推奨）
utility.SetDefaultDelegate(YourFileDelegate::kDelegateKey);

MGLドキュメント

MGL::File::ThrowingUtility

Contents

MGL::File::ThrowingUtility#

概要#

宣言#

メンバ情報#

GetSize#

宣言#

引数#

戻り値#

例外#

説明#

利用例#

関連#

MakeDirectory#

宣言#

引数#

例外#

説明#

利用例#

関連#

Move#

宣言#

引数#

例外#

説明#

利用例#

関連#

Remove#

宣言#

引数#

例外#

説明#

利用例#

関連#

Copy#

宣言#

引数#

例外#

説明#

利用例#

関連#

Exists#

宣言#

引数#

戻り値#

例外#

説明#

利用例#

関連#

IsSystemNativeFile#

宣言#

引数#

戻り値#

例外#

説明#

利用例#

関連#

Mount#

宣言#

引数#

例外#

説明#

利用例#

関連#

Unmount#

宣言#

引数#

例外#

説明#

利用例#

関連#

Remount#

宣言#

引数#

例外#

説明#

関連#

IsMounted#