MGL::File::ThrowingHandle#

概要#

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

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

宣言#

namespace MGL::File
{
    class ThrowingHandle;
}

メンバ情報#

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

コンストラクタ#

宣言#

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

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

引数#

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

引数なし

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

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

例外#

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

送出しない

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

MGL::File::Result: 失敗理由を表す処理結果

説明#

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

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

(2)はファイルハンドルの生成とオープンを同時に行います。オープンに失敗した場合、失敗理由を表すMGL::File::Resultを例外として送出します。

利用例#

// (1) 空のハンドルを生成して読み込み専用でオープン
try
{
    MGL::File::ThrowingHandle handle;
    handle.Open("$user/test.data");
}
catch (MGL::File::Result result)
{
    printf("ファイルのオープンに失敗: %d\n", result.GetErrorCode());
}

// (2) 生成と同時にファイルをオープン（効果は(1)と同等）
try
{
    MGL::File::ThrowingHandle handle("$user/test.data");
}
catch (MGL::File::Result result)
{
    printf("ファイルのオープンに失敗: %d\n", result.GetErrorCode());
}

Open#

ファイルをオープン

宣言#

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

引数#

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

例外#

MGL::File::Result: 失敗理由を表す処理結果

説明#

指定されたモードでファイルをオープンします。オープンに失敗した場合、失敗理由を表すMGL::File::Resultを例外として送出します。

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

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

利用例#

try
{
    MGL::File::ThrowingHandle handle;

    // ファイルをオープン
    handle.Open("$user/test.data");
}
catch (MGL::File::Result result)
{
    printf("ファイルのオープンに失敗: %d\n", result.GetErrorCode());
}

Close#

ファイルをクローズ

宣言#

namespace MGL::File
{
    class ThrowingHandle
    {
    public:
        void Close();
    };
};

例外#

MGL::File::Result: 失敗理由を表す処理結果

説明#

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

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

ファイルがオープンされていない場合、この関数は何もせず例外の送出も行いません。

利用例#

try
{
    MGL::File::ThrowingHandle handle("$user/test.data");

    /*
     *  ファイルアクセス処理
     */

    handle.Close();     // 明示的なクローズ処理
                        // クローズ処理のエラーハンドリングを行わない場合は省略可能
}
catch (MGL::File::Result result)
{
    printf("ファイルアクセス失敗: %d\n", result.GetErrorCode());
}

IsOpen#

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

宣言#

namespace MGL::File
{
    class ThrowingHandle
    {
    public:
        constexpr bool IsOpen() const noexcept;
    };
}

戻り値#

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

説明#

ファイルハンドルがオープン済みかを取得します。この関数は例外を送出しません。

利用例#

try
{
    MGL::File::ThrowingHandle handle("$user/test.data");

    // ファイルがオープンされているかをチェック
    if (handle.IsOpen())
    {
        // オープンに失敗した場合は例外を送出するため、ここには必ず到達する
    }

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

    // ファイルがオープンされているかを再度チェック
    if (handle.IsOpen())
    {
        // クローズされたのでここには到達しない
    }
}
catch (MGL::File::Result result)
{
    printf("ファイルアクセス失敗: %d\n", result.GetErrorCode());
}

Read#

ファイルの読み込み

宣言#

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

引数#

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

戻り値#

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

例外#

MGL::File::Result: 失敗理由を表す処理結果

説明#

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

戻り値には実際に読み込んだバイト数が返されます。

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

利用例#

try
{
    MGL::File::ThrowingHandle handle("$user/test.data");

    std::byte buffer[16];

    // 読み込み
    auto readSize = handle.Read(buffer, 16);
    printf("%zuバイト読み込み成功。\n", readSize);
}
catch (MGL::File::Result result)
{
    printf("ファイルアクセス失敗: %d\n", result.GetErrorCode());
}

Write#

ファイルに書き込み

宣言#

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

引数#

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

戻り値#

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

例外#

MGL::File::Result: 失敗理由を表す処理結果

説明#

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

戻り値には実際に書き込んだバイト数が返されます。

書き込みに失敗した場合、失敗理由を表すMGL::File::Resultを例外として送出します。

利用例#

try
{
    MGL::File::ThrowingHandle handle("$user/test.data", MGL::File::OpenMode::Write);

    const MGL::STL::string kTestMessage("Hello, MGL");

    // 書き込み
    auto writeSize = handle.Write(kTestMessage.c_str(), kTestMessage.size());
    printf("%zuバイト書き込み成功。\n", writeSize);
}
catch (MGL::File::Result result)
{
    printf("ファイルアクセス失敗: %d\n", result.GetErrorCode());
}

Seek#

ストリーム位置を設定

宣言#

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

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

引数#

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

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

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

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

戻り値#

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

例外#

MGL::File::Result: 失敗理由を表す処理結果

説明#

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

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

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

シークに成功した場合、戻り値に現在のストリーム位置が返ります。失敗した場合、失敗理由を表すMGL::File::Resultを例外として送出します。

利用例#

try
{
    MGL::File::ThrowingHandle handle("$user/test.data");

    // 先頭から8バイト目にストリーム位置を設定
    auto position = handle.Seek(MGL::File::SeekType::Top, 8);

    printf("現在のストリーム位置: %zu\n", position);
}
catch (MGL::File::Result result)
{
    printf("ファイルアクセス失敗: %d\n", result.GetErrorCode());
}

Skip#

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

宣言#

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

引数#

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

戻り値#

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

例外#

MGL::File::Result: 失敗理由を表す処理結果

説明#

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

スキップに成功した場合、戻り値に現在のストリーム位置が返ります。失敗した場合、失敗理由を表すMGL::File::Resultを例外として送出します。

利用例#

try
{
    MGL::File::ThrowingHandle handle("$user/test.data");

    // 現在のストリーム位置から8バイト分スキップ
    auto position = handle.Skip(8);

    printf("現在のストリーム位置: %zu\n", position);
}
catch (MGL::File::Result result)
{
    printf("ファイルアクセス失敗: %d\n", result.GetErrorCode());
}

GetOffset#

ストリーム位置を取得

宣言#

namespace MGL::File
{
    class ThrowingHandle
    {
    public:
        size_t GetOffset();
    };
}

戻り値#

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

例外#

MGL::File::Result: 失敗理由を表す処理結果

説明#

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

戻り値として現在のストリーム位置が返ります。失敗した場合、失敗理由を表すMGL::File::Resultを例外として送出します。

利用例#

try
{
    MGL::File::ThrowingHandle handle("$user/test.data");

    // 現在のストリーム位置から8バイト分スキップ
    handle.Skip(8);

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

    printf("現在のストリーム位置: %zu\n", position);
}
catch (MGL::File::Result result)
{
    printf("ファイルアクセス失敗: %d\n", result.GetErrorCode());
}

IsEOF#

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

宣言#

namespace MGL::File
{
    class ThrowingHandle
    {
    public:
        bool IsEOF();
    };
}

戻り値#

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

例外#

MGL::File::Result: 失敗理由を表す処理結果

説明#

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

オープンしていないファイルハンドルに対して呼び出した場合など、取得に失敗した場合は失敗理由を表すMGL::File::Resultを例外として送出します。

利用例#

try
{
    MGL::File::ThrowingHandle handle("$user/test.data");

    // ファイルの終端に達するまで1バイトづつ読み込んで表示
    while (!handle.IsEOF())
    {
        uint8_t byte;
        handle.Read(&byte, 1);

        printf("%02X\n", byte);
    }
}
catch (MGL::File::Result result)
{
    printf("ファイルアクセス失敗: %d\n", result.GetErrorCode());
}

GetSize#

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

宣言#

namespace MGL::File
{
    class ThrowingHandle
    {
    public:
        size_t GetSize();
    };
}

戻り値#

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

例外#

MGL::File::Result: 失敗理由を表す処理結果

説明#

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

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

利用例#

try
{
    MGL::File::ThrowingHandle handle("$user/test.data");

    // ファイルサイズを取得して表示
    auto size = handle.GetSize();
    printf("ファイルサイズ: %zu\n", size);
}
catch (MGL::File::Result result)
{
    printf("ファイルアクセス失敗: %d\n", result.GetErrorCode());
}

MGLドキュメント

MGL::File::ThrowingHandle

Contents

MGL::File::ThrowingHandle#

概要#

宣言#

メンバ情報#

コンストラクタ#

宣言#

引数#

例外#

説明#

利用例#

関連#

Open#

宣言#

引数#

例外#

説明#

利用例#

関連#

Close#

宣言#

例外#

説明#

利用例#

関連#

IsOpen#

宣言#

戻り値#

説明#

利用例#

関連#

Read#

宣言#

引数#

戻り値#

例外#

説明#

利用例#

Write#

宣言#

引数#

戻り値#

例外#

説明#

利用例#

Seek#

宣言#

引数#

戻り値#

例外#

説明#

利用例#

関連#

Skip#

宣言#

引数#

戻り値#

例外#

説明#

利用例#

関連#

GetOffset#

宣言#

戻り値#

例外#

説明#

利用例#

関連#

IsEOF#

宣言#

戻り値#

例外#

説明#

利用例#

GetSize#

宣言#

戻り値#

例外#