MGL::File::Utility#

概要#

MGL ::File::Utilityはファイルシステムに対する各種機能を提供するクラスです。

このクラスは処理の成否を手動でハンドリングする必要があります。例外を用いて失敗理由を取得したい場合はMGL::File::ThrowingUtilityを使用してください。

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

宣言#

namespace MGL::File
{
    class Utility
}

メンバ情報#

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

GetSize#

サイズの取得

宣言#

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

引数#

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

戻り値#

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

説明#

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

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

取得に失敗した場合は0が返り、HasErrorがtrueを返すようになります。失敗理由はGetResultにて取得できます。

利用例#

MGL::File::Utility utility;

// ファイルサイズを取得
auto size = utility.GetSize("$user/test.data");

// ファイルサイズが取得できているかをチェック
if (utility.HasError())
{
    printf("取得失敗: %d\n", utility.GetResult().GetErrorCode());
}
else
{
    printf("ファイルサイズ: %zu\n", size);
}

MakeDirectory#

ディレクトリの生成

宣言#

namespace MGL::File
{
    class Utility
    {
    public:
        const Result &MakeDirectory(const PathView &path) noexcept;
    };
}

引数#

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

戻り値#

const MGL::File::Result &: 処理結果

説明#

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

利用例#

MGL::File::Utility utility;

// ディレクトリを生成
auto result = utility.MakeDirectory("$user/test-directory");
if (result.HasError())
{
    printf("ディレクトリ生成失敗: %d\n", result.GetErrorCode());
}

Move#

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

宣言#

namespace MGL::File
{
    class Utility
    {
    public:
        const Result &Move(const PathView &sourcePath, const PathView &destPath) noexcept;
    };
}

引数#

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

戻り値#

const MGL::File::Result &: 処理結果

説明#

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

利用例#

MGL::File::Utility utility;

// ファイルをリネーム
auto result = utility.Move("$user/test.data", "$user/new-name-file.data");
if (result.HasError())
{
    printf("リネーム失敗: %d\n", result.GetErrorCode());
}

Remove#

ファイルの削除

宣言#

namespace MGL::File
{
    class Utility
    {
    public:
        const Result &Remove(const PathView &path) noexcept;
    };
}

引数#

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

戻り値#

const MGL::File::Result &: 処理結果

説明#

指定されたパスのファイルを削除し、処理結果を返します。

利用例#

MGL::File::Utility utility;

// ファイルを削除
auto result = utility.Remove("$user/test.data");
if (result.HasError())
{
    printf("削除失敗: %d\n", result.GetErrorCode());
}

Copy#

ファイルのコピー

宣言#

namespace MGL::File
{
    class Utility
    {
    public:
        const Result &Copy(const PathView &sourcePath, const PathView &destPath) noexcept;
    };
}

引数#

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

戻り値#

const MGL::File::Result &: 処理結果

説明#

コピー元のファイルの複製をコピー先のファイルに生成し、処理結果を返します。

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

利用例#

MGL::File::Utility utility;

// ファイルをコピー
auto result = utility.Copy("$user/test.data", "$user/duplicated-test.data");
if (result.HasError())
{
    printf("コピー失敗: %d\n", result.GetErrorCode());
}

Exists#

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

宣言#

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

引数#

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

戻り値#

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

説明#

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

正常に判別できなかった場合はfalseが返り、HasErrorがtrueを返すようになります。失敗理由はGetResultにて取得できます。

利用例#

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

MGL::File::Utility utility;

// ファイルが存在しているかをチェック
if (utility.Exists(kFilePath))
{
    printf("%s は存在している\n", kFilePath);
}
else
{
    if (utility.HasError())
    {
        printf("取得失敗: %d\n", utility.GetResult().GetErrorCode());
    }
    else
    {
        printf("%s は存在していない\n", kFilePath);
    }
}

IsSystemNativeFile#

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

宣言#

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

引数#

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

戻り値#

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

説明#

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

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

正常に取得できなかった場合はfalseが返り、HasErrorがtrueを返すようになります。失敗理由はGetResultにて取得できます。

利用例#

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

MGL::File::Utility utility;

// システム標準のファイルかどうかをチェック
if (utility.IsSystemNativeFile(kFilePath))
{
    printf("%s はシステム標準のファイル\n", kFilePath);
}
else
{
    if (utility.HasError())
    {
        printf("取得失敗: %d\n", utility.GetResult().GetErrorCode());
    }
    else
    {
        printf("%s はシステムが直接扱えないファイル\n", kFilePath);
    }
}

Mount#

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

宣言#

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

引数#

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

戻り値#

const MGL::File::Result &: 処理結果

説明#

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

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

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

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

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

利用例#

MGL::File::Utility utility;

// ユーザーディレクトリの "test-directory" を "test" という名前でマウント
auto result = utility.Mount(
                "test",
                "$user/test-directory",
                MGL::File::MountAccessType::ReadOnly);

// エラーチェック
if (result.HasError())
{
    printf("マウント失敗: %d\n", result.GetErrorCode());
}

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

Unmount#

マウントの解除

宣言#

namespace MGL::File
{
    class Utility
    {
    public:
        const Result &Unmount(const PathView &mountName) noexcept;
    };
}

引数#

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

戻り値#

const MGL::File::Result &: 処理結果

説明#

指定したマウント名のマウント解除を行い、処理結果を返します。

利用例#

MGL::File::Utility utility;

// "test' のマウントを解除
auto result = utility.Unmount("test");

if (result.HasError())
{
    printf("マウント解除失敗: %d\n", result.GetErrorCode());
}

Remount#

再マウント

宣言#

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

引数#

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

戻り値#

const MGL::File::Result &: 処理結果

説明#

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

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

IsMounted#

マウント済みかを取得

宣言#

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

引数#

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

戻り値#

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

説明#

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

利用例#

MGL::File::Utility utility;

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

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

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

GetSystemNativePath#

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

宣言#

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

引数#

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

戻り値#

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

説明#

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

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

正常に変換できなかった場合は空の文字列を返し、HasErrorがtrueを返すようになります。失敗理由はGetResultにて取得できます。

注釈

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

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

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

利用例#

MGL::File::Utility utility;

// ユーザーディレクトリのパスを取得
auto userDirectoryPath = utility.GetSystemNativePath("$user");

// 取得結果をチェック
if (utility.HasError())
{
    printf("取得失敗: %d\n", utility.GetResult().GetErrorCode());
}
else
{
    printf("ユーザーディレクトリ: %s\n", userDirectoryPath.c_str());
}

AddDelegate#

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

宣言#

namespace MGL::File
{
    class Utility
    {
    public:
        template <class DelegateClass, class... Args>
        constexpr const Result &AddDelegate(DelegateKey key, Args... args) noexcept;
    };
}

引数#

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

戻り値#

const MGL::File::Result &: 処理結果

説明#

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

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

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

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

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

利用例#

MGL::File::Utility utility;

// "YourFileDelegate" という名前のファイルデリゲートを追加
auto result = utility.AddDelegate<YourFileDelegate>(YourFileDelegate::kDelegateKey);

// エラーチェック
if (result.HasError())
{
    printf("デリゲートの追加に失敗: %d\n", result.GetErrorCode());
}

RemoveDelegate#

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

宣言#

namespace MGL::File
{
    class Utility
    {
    public:
        const Result &RemoveDelegate(DelegateKey key) noexcept;
    };
}

引数#

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

戻り値#

const MGL::File::Result &: 処理結果

説明#

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

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

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

利用例#

MGL::File::Utility utility;

// "YourFileDelegate" を削除
auto result = utility.RemoveDelegate(YourFileDelegate::kDelegateKey);
if (result.HasError())
{
    printf("デリゲートの削除に失敗: %d\n", result.GetErrorCode());
}

SetDefaultDelegate#

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

宣言#

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

引数#

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

説明#

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

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

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

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

利用例#

MGL::File::Utility utility;

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

GetResult#

最後の処理の結果を取得

宣言#

namespace MGL::File
{
    class Utility
    {
    public:
        [[nodiscard]] constexpr const Result &GetResult() const noexcept;
    };
}

戻り値#

const MGL::File::Result &: 最後の処理の結果

説明#

最後に実行した処理の結果を取得します。

利用例#

他の関数の利用例に含まれているた省略します。

HasError#

最後の処理でエラーが発生しているかを取得

宣言#

namespace MGL::File
{
    class Utility
    {
    public:
        [[nodiscard]] constexpr bool HasError() const noexcept;
    };
}

戻り値#

bool: 最後に実行した処理でエラーが発生している場合はtrue、成功している場合はfalse

説明#

このクラスが最後に実行した処理において、何らかのエラーが発生しているかを取得します。具体的な処理結果はGetResultにて取得します。

利用例#

他の関数の利用例に含まれているた省略します。

MGLドキュメント

MGL::File::Utility

Contents

MGL::File::Utility#

概要#

宣言#

メンバ情報#

GetSize#

宣言#

引数#

戻り値#

説明#

利用例#

関連#

MakeDirectory#

宣言#

引数#

戻り値#

説明#

利用例#

関連#

Move#

宣言#

引数#

戻り値#

説明#

利用例#

関連#

Remove#

宣言#

引数#

戻り値#

説明#

利用例#

関連#

Copy#

宣言#

引数#

戻り値#

説明#

利用例#

関連#

Exists#

宣言#

引数#

戻り値#

説明#

利用例#

関連#

IsSystemNativeFile#

宣言#

引数#

戻り値#

説明#

利用例#

関連#

Mount#

宣言#

引数#

戻り値#

説明#

利用例#

関連#

Unmount#

宣言#

引数#

戻り値#

説明#

利用例#

関連#

Remount#

宣言#

引数#

戻り値#

説明#

関連#

IsMounted#

宣言#

引数#

戻り値#