MGL::File::Handle#

概要#

MGL::File::Handleはファイルに対するアクセス機能を提供するクラスです。

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

宣言#

namespace MGL::File
{
    class Handle;
}

メンバ情報#

種類	名前	内容
関数	コンストラクタ
関数	Open	ファイルをオープン
関数	Close	ファイルをクローズ
関数	IsOpen	ファイルがオープンされているかを取得
関数	Read	ファイルの読み込み
関数	Write	ファイルに書き込み
関数	Seek	ストリーム位置を設定
関数	Skip	ストリーム位置をスキップ
関数	GetOffset	ストリーム位置を取得
関数	IsEOF	ファイルストリームが終端に達しているかを取得
関数	GetSize	オープンしているファイルのサイズを取得
関数	GetResult	処理結果の取得
関数	HasError	最後の処理結果でエラーが発生しているかを取得

コンストラクタ#

宣言#

namespace MGL::File
{
    class Handle
    {
    public:
        // (1) 空のハンドルを生成
        constexpr Handle() noexcept;

        // (2) 生成と同時にファイルをオープン
        Handle(const PathView &path, OpenMode mode = OpenMode::Read) noexcept;
    };
}

引数#

(1) 空のハンドルを生成

引数なし

(2) 生成と同時にファイルをオープン

const MGL::File::PathView &path: オープンするファイルのパス
MGL::File::OpenMode mode: オープンモード

説明#

ファイルハンドルのコンストラクタです。

(1)は空のファイルハンドルを生成します。この方法で生成したハンドルはOpenを呼び出す必要があります。

(2)はファイルハンドルの生成とオープンを同時に行います。

利用例#

// (1) 空のハンドルを生成して読み込み専用でオープン
MGL::File::Handle handle;
handle.Open("$user/test.data")
if (!handle.IsOpen())
{
    // オープンに失敗した場合はここに到達
}

// (2) 生成と同時にファイルをオープン（効果は(1)と同等）
MGL::File::Handle handle("$user/test.data");
if (!handle.IsOpen())
{
    // オープンに失敗した場合はここに到達
}

Open#

ファイルをオープン

宣言#

namespace MGL::File
{
    class Handle
    {
    public:
        Result Open(const PathView &path, OpenMode mode = OpenMode::Read) noexcept;
    };
}

引数#

const MGL::File::PathView &path: オープンするファイルのパス
MGL::File::OpenMode mode: オープンモード

戻り値#

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

説明#

指定されたモードでファイルをオープンし、処理結果をMGL::File::Resultで返します。

ファイルパスはマウント名を含んだフォーマットになります。詳しくはファイルパスのフォーマットを参照してください。

modeを省略した場合はMGL::File::OpenMode::Readとして扱われます。

利用例#

MGL::File::Handle handle;

auto result = handle.Open("$resource/image.png");

if (!result)
{
    printf("ファイルのオープンに失敗: %d\n", result.GetErrorCode());
}

Close#

ファイルをクローズ

宣言#

namespace MGL::File
{
    class Handle
    {
    public:
        Result Close() noexcept;
    };
};

説明#

オープンしているファイルをクローズします。ファイルのクローズの動作は使用するデリゲートによって異なりますが、一般的にはハンドルはオープンされていない状態に戻ります。

ファイルをオープンしている状態でハンドルクラスの寿命が切れた場合、クローズ処理は自動で行われるため、通常はこの関数を明示的に呼び出す必要はありません。デリゲートがクローズ処理に失敗する可能性があり、その内容をハンドリングする必要がある場合において使用してください。

ファイルがオープンされていない状態では、この関数は何もせずに成功を返します。

利用例#

MGL::File::Handle handle("$resource/image.png");

if (handle.IsOpen())
{
    printf("ファイルのオープンに成功\n");
}

handle.Close();     // 明示的なクローズ処理
                    // もしファイルのオープンに失敗していた場合は何もしない

if (MGL::File::Handle handle2("$resource/image.png"); handle2.IsOpen())
{
    printf("ファイルのオープンに成功\n");
}

// この時点で handle2 は寿命が切れているため、クローズ処理も自動で行われている

IsOpen#

ファイルがオープンされているかを取得

宣言#

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

戻り値#

bool: オープンされている場合にtrue、されていない場合はfalse

説明#

ファイルハンドルがオープン済みかを取得します。

利用例#

MGL::File::Handle handle("$resource/image.png");

if (handle.IsOpen())
{
    // ファイルのオープンに成功している場合はここに到達
}

handle.Close();     // ファイルをクローズ

if (handle.IsOpen())
{
    // クローズされたのでここには到達しない
}

Read#

ファイルの読み込み

宣言#

namespace MGL::File
{
    class Handle
    {
    public:
        size_t Read(void *buffer, size_t size) noexcept;
    };
}

引数#

void *buffer: 読み込んだデータを格納するバッファのアドレス
size_t size: 読み込むサイズ（バイト数）

戻り値#

size_t: 実際に読み込んだバイト数

説明#

現在のストリーム位置から最大でsizeバイト分のデータを読み込み、その内容をbufferへと格納します。読み込み後はストリームのオフセットが更新されます。

戻り値には実際に読み込んだバイト数が返されます。失敗した場合は0が返り、ハンドルが持つ処理結果にエラーが書き込まれます。

利用例#

if (MGL::File::Handle handle("$resource/image.png"); handle.IsOpen())
{
    std::byte buffer[16];

    // 読み込み
    auto readSize = handle.Read(buffer, 16);

    // 読み込みに成功しているかをチェック
    if (handle.HasError())
    {
        printf("読み込み失敗: %d\n", handle.GetResult().GetErrorCode());
    }
    else
    {
        printf("%zuバイト読み込み成功。\n", readSize);
    }
}
else
{
    printf("ファイルのオープンに失敗: %d\n", handle.GetResult().GetErrorCode());
}

Write#

ファイルに書き込み

宣言#

namespace MGL::File
{
    class Handle
    {
    public:
        size_t Write(const void *buffer, size_t size) noexcept;
    };
}

引数#

void *buffer: 書き込むデータが格納されているアドレス
size_t size: 書き込むサイズ（バイト数）

戻り値#

size_t: 実際に書き込んだバイト数

説明#

指定したbufferの内容を、現在のストリーム位置からsizeバイト分だけファイルに書き込みます。書き込み後はストリームのオフセットが更新されます。

戻り値には実際に書き込んだバイト数が返されます。失敗した場合は0が返り、ハンドルが持つ処理結果にエラーが書き込まれます。

利用例#

if (MGL::File::Handle handle("$user/test.data", MGL::File::OpenMode::Write); handle.IsOpen())
{
    const MGL::STL::string kTestMessage("Hello, MGL");

    // 書き込み
    auto writeSize = handle.Write(kTestMessage.c_str(), kTestMessage.size());

    // 書き込みに成功しているかをチェック
    if (handle.HasError())
    {
        printf("書き込み失敗: %d\n", handle.GetResult().GetErrorCode());
    }
    else
    {
        printf("%zuバイト書き込み成功。\n", writeSize);
    }
}
else
{
    printf("ファイルのオープンに失敗: %d\n", handle.GetResult().GetErrorCode());
}

Seek#

ストリーム位置を設定

宣言#

namespace MGL::File
{
    class Handle
    {
    public:
        // (1) int32_t 型でオフセットを指定
        size_t Seek(SeekType seekType, int32_t offset) noexcept;

        // (2) size_t 型でオフセットを指定
        size_t Seek(SeekType seekType, size_t offset) noexcept;
    };
}

引数#

(1) int32_t型でオフセットを指定

MGL::File::SeekType seekType: シークタイプ
int32_t offset: オフセット

(2) size_t型でオフセットを指定

MGL::File::SeekType seekType: シークタイプ
size_t offset: オフセット

戻り値#

size_t: 設定後のストリーム位置

説明#

オープン済みのファイルのストリーム位置を変更します。

seekTypeは続くoffsetの基準位置を指定します。詳細はMGL::File::SeekTypeの説明を参照してください。

(1)と(2)の違いはオフセットの型のみです。seekTypeにMGL::File::SeekType::Currentを指定した場合において、オフセットに負数を指定する場合にint32_t型を利用します。

シークに成功した場合、戻り値に現在のストリーム位置が返ります。失敗した場合は0が返り、ハンドルの処理結果に失敗理由が書き込まれます。

利用例#

if (MGL::File::Handle handle("$user/test.data"); handle.IsOpen())
{
    // 先頭から8バイト目にストリーム位置を設定
    auto position = handle.Seek(MGL::File::SeekType::Top, 8);

    // シークに成功しているかをチェック
    if (handle.HasError())
    {
        printf("シーク失敗: %d\n", handle.GetResult().GetErrorCode());
    }
    else
    {
        printf("現在のストリーム位置: %zu\n", position);
    }
}
else
{
    printf("ファイルのオープンに失敗: %d\n", handle.GetResult().GetErrorCode());
}

Skip#

ストリーム位置をスキップ

宣言#

namespace MGL::File
{
    class Handle
    {
    public:
        size_t Skip(size_t size) noexcept;
    };
}

引数#

size_t size: スキップするサイズ

戻り値#

size_t: スキップ後のストリーム位置

説明#

オープン済みのファイルのストリーム位置をsizeバイト分先に進めます。この関数はSeekにSeekType::Currentを指定した場合と等価です。

スキップに成功した場合、戻り値に現在のストリーム位置が返ります。失敗した場合は0が返り、ハンドルの処理結果に失敗理由が書き込まれます。

利用例#

if (MGL::File::Handle handle("$user/test.data"); handle.IsOpen())
{
    // 現在のストリーム位置から8バイト分スキップ
    auto position = handle.Skip(8);

    // スキップに成功しているかをチェック
    if (handle.HasError())
    {
        printf("スキップ失敗: %d\n", handle.GetResult().GetErrorCode());
    }
    else
    {
        printf("現在のストリーム位置: %zu\n", position);
    }
}
else
{
    printf("ファイルのオープンに失敗: %d\n", handle.GetResult().GetErrorCode());
}

GetOffset#

ストリーム位置を取得

宣言#

namespace MGL::File
{
    class Handle
    {
    public:
        [[nodiscard]] size_t GetOffset() noexcept;
    };
}

戻り値#

size_t: 現在のストリーム位置

説明#

オープン済みのファイルのストリーム位置を取得します。

戻り値として現在のストリーム位置が返ります。処理に失敗した場合は0が返り、ハンドルの処理結果に失敗理由が書き込まれます。

利用例#

if (MGL::File::Handle handle("$user/test.data"); handle.IsOpen())
{
    // 現在のストリーム位置から8バイト分スキップ
    handle.Skip(8);

    // 現在のストリーム位置を取得
    auto position = handle.GetOffset();

    // 正しくストリーム位置が取得できたかチェック
    if (handle.HasError())
    {
        printf("取得失敗: %d\n", handle.GetResult().GetErrorCode());
    }
    else
    {
        printf("現在のストリーム位置: %zu\n", position);
    }
}
else
{
    printf("ファイルのオープンに失敗: %d\n", handle.GetResult().GetErrorCode());
}

IsEOF#

ファイルストリームが終端に達しているかを取得

宣言#

namespace MGL::File
{
    class Handle
    {
    public:
        [[nodiscard]] bool IsEOF() noexcept;
    };
}

戻り値#

bool: ストリーム位置が終端に達していればtrue、そうでなければfalse

説明#

オープン済みのファイルに対し、現在のストリーム位置が終端に達しているかを取得します。

オープンしていないファイルハンドルに対して呼び出した場合など、取得に失敗している場合はtrueを返し、ハンドルの処理結果に失敗理由が書き込まれます。

利用例#

if (MGL::File::Handle handle("$user/test.data"); handle.IsOpen())
{
    // ファイルの終端に達するまで1バイトづつ読み込んで表示
    while (!handle.IsEOF())
    {
        uint8_t byte;
        if (handle.Read(&byte, 1) == 1)
        {
            printf("%02X\n", byte);
        }
    }
}
else
{
    printf("ファイルのオープンに失敗: %d\n", handle.GetResult().GetErrorCode());
}

GetSize#

オープンしているファイルのサイズを取得

宣言#

namespace MGL::File
{
    class Handle
    {
    public:
        [[nodiscard]] size_t GetSize() noexcept;
    };
}

戻り値#

size_t: オープンしているファイルのサイズ（バイト数）

説明#

オープン済みのファイルのサイズを取得します。この関数の戻り値はシーク可能な最大オフセットと同値です。

取得に失敗した場合は0が返り、ハンドルが持つ処理結果にエラーが書き込まれます。

利用例#

if (MGL::File::Handle handle("$user/test.data"); handle.IsOpen())
{
    // オープンしたファイルのサイズを取得
    auto size = handle.GetSize();

    // 取得に成功しているかをチェック
    if (handle.HasError())
    {
        printf("取得失敗: %d\n", handle.GetResult().GetErrorCode());
    }
    else
    {
        printf("ファイルサイズ: %zu\n", size);
    }
}
else
{
    printf("ファイルのオープンに失敗: %d\n", handle.GetResult().GetErrorCode());
}

GetResult#

処理結果の取得

宣言#

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

戻り値#

MGL::File::Result: 最後に実行した処理結果

説明#

このハンドルが最後に実行した処理結果を取得します。

利用例#

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

HasError#

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

宣言#

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

戻り値#

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

説明#

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

利用例#

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

MGLドキュメント

MGL::File::Handle

Contents

MGL::File::Handle#

概要#

宣言#

メンバ情報#

コンストラクタ#

宣言#

引数#

説明#

利用例#

関連#

Open#

宣言#

引数#

戻り値#

説明#

利用例#

関連#

Close#

宣言#

説明#

利用例#

関連#

IsOpen#

宣言#

戻り値#

説明#

利用例#

関連#

Read#

宣言#

引数#

戻り値#

説明#

利用例#

関連#

Write#

宣言#

引数#

戻り値#

説明#

利用例#

関連#

Seek#

宣言#

引数#

戻り値#

説明#

利用例#

関連#

Skip#

宣言#

引数#

戻り値#

説明#

利用例#

関連#

GetOffset#

宣言#

戻り値#

説明#

利用例#

関連#

IsEOF#

宣言#

戻り値#

説明#

利用例#

GetSize#

宣言#

戻り値#

説明#

利用例#

GetResult#

宣言#

戻り値#

説明#

利用例#