I/Oインターフェイス
[詳解]
#include <cri_file_system.h>
|
CriFsIoError(* | Exists )(const CriChar8 *path, CriBool *result) |
| ファイルの有無の確認 [詳解]
|
|
CriFsIoError(* | Remove )(const CriChar8 *path) |
| ファイルの削除 [詳解]
|
|
CriFsIoError(* | Rename )(const CriChar8 *old_path, const CriChar8 *new_path) |
| ファイル名の変更 [詳解]
|
|
CriFsIoError(* | Open )(const CriChar8 *path, CriFsFileMode mode, CriFsFileAccess access, CriFsFileHn *filehn) |
| ファイルのオープン [詳解]
|
|
CriFsIoError(* | Close )(CriFsFileHn filehn) |
| ファイルのクローズ [詳解]
|
|
CriFsIoError(* | GetFileSize )(CriFsFileHn filehn, CriSint64 *file_size) |
| ファイルサイズの取得 [詳解]
|
|
CriFsIoError(* | Read )(CriFsFileHn filehn, CriSint64 offset, CriSint64 read_size, void *buffer, CriSint64 buffer_size) |
| 読み込みの開始 [詳解]
|
|
CriFsIoError(* | IsReadComplete )(CriFsFileHn filehn, CriBool *result) |
| 読み込み完了チェック [詳解]
|
|
CriFsIoError(* | CancelRead )(CriFsFileHn filehn) |
| ファイル読み込みのキャンセル発行 [詳解]
|
|
CriFsIoError(* | GetReadSize )(CriFsFileHn filehn, CriSint64 *read_size) |
| 読み込みサイズの取得 [詳解]
|
|
CriFsIoError(* | Write )(CriFsFileHn filehn, CriSint64 offset, CriSint64 write_size, void *buffer, CriSint64 buffer_size) |
| 書き込みの開始 [詳解]
|
|
CriFsIoError(* | IsWriteComplete )(CriFsFileHn filehn, CriBool *result) |
| 書き込み完了チェック [詳解]
|
|
CriFsIoError(* | CancelWrite )(CriFsFileHn filehn) |
| ファイル書き込みのキャンセル発行 [詳解]
|
|
CriFsIoError(* | GetWriteSize )(CriFsFileHn filehn, CriSint64 *write_size) |
| 書き込みサイズの取得 [詳解]
|
|
CriFsIoError(* | Flush )(CriFsFileHn filehn) |
| フラッシュの実行 [詳解]
|
|
CriFsIoError(* | Resize )(CriFsFileHn filehn, CriSint64 size) |
| ファイルサイズの変更 [詳解]
|
|
CriFsIoError(* | GetNativeFileHandle )(CriFsFileHn filehn, void **native_filehn) |
| ネイティブファイルハンドルの取得 [詳解]
|
|
CriFsIoError(* | SetAddReadProgressCallback )(CriFsFileHn filehn, void(*callback)(void *, CriSint32), void *obj) |
| 読み込みプログレス加算コールバックの設定 [詳解]
|
|
CriFsIoError(* | CanParallelRead )(CriBool *result) |
| 複数の同時ファイルアクセス要求が可能かどうかの問い合わせ [詳解]
|
|
◆ Exists
CriFsIoError( * Exists) (const CriChar8 *path, CriBool *result) |
ファイルの有無の確認
- 引数
-
[in] | path | ファイルのパス |
[out] | result | ファイルが存在するかどうか |
- 戻り値
- CriFsIoError エラーコード
- 説明:
- 指定されたファイルの有無を確認する関数です。
ファイルが存在する場合は CRI_TRUE を、 存在しない場合は CRI_FALSE を result にセットする必要があります。
◆ Remove
ファイルの削除
- 引数
-
- 戻り値
- CriFsIoError エラーコード
- 説明:
- 指定されたファイルを削除する関数です。
- 備考:
- デバイスで書き込みを行なわない場合には、この関数を実装せず、 構造体のメンバーに CRI_NULL を指定することも可能です。
◆ Rename
CriFsIoError( * Rename) (const CriChar8 *old_path, const CriChar8 *new_path) |
ファイル名の変更
- 引数
-
[in] | old_path | リネーム前のファイルのパス |
[in] | new_path | リネーム後のファイルのパス |
- 戻り値
- CriFsIoError エラーコード
- 説明:
- ファイル名の変更を行なう関数です。
old_path で指定されたファイルを、 new_path にリネームします。
- 備考:
- デバイスで書き込みを行なわない場合には、この関数を実装せず、 構造体のメンバーに CRI_NULL を指定することも可能です。
◆ Open
ファイルのオープン
- 引数
-
[in] | path | ファイルのパス |
[in] | mode | ファイルオープンモード |
[in] | access | ファイルアクセス種別 |
[out] | filehn | ファイルハンドル |
- 戻り値
- CriFsIoError エラーコード
- 説明:
- 指定されたファイルをオープンする関数です。
オープンに成功した場合、CriFsFileHn 型のファイルハンドルを返す必要があります。
- 補足:
- CriFsFileHn は void ポインターとして定義されています。
独自のファイル情報構造体を定義し、そのアドレスを CriFsFileHn 型にキャストして返してください。
尚、ファイルオープン時にメモリの確保が必要な場合には、本関数内で動的にメモリの確保を行なってください。
- 注意
- 戻り値のエラーコード( CriFsIoError )には、関数内で継続不能なエラーが発生した 場合に限り CRIFS_IO_ERROR_NG をセットしてください。
(ファイルのオープンに失敗した場合でも、アプリケーションで処理を継続可能な場合には filehn に NULL をセットし、CRIFS_IO_ERROR_OK を返す必要があります。)
また、ディスク挿入待ち等の理由により、関数が実行されたタイミングでオープン処理 を実行できない場合、エラーコードとして CRIFS_IO_ERROR_TRY_AGAIN を返すことで、 一定時間後(約10ms後)に再度オープン処理をやり直すことが可能です。
(関数の実行タイミングを先送りすることが可能です。)
◆ Close
ファイルのクローズ
- 引数
-
- 戻り値
- CriFsIoError エラーコード
- 説明:
- 指定されたファイルハンドルをクローズする関数です。
ファイルオープン時に動的にメモリの確保を行なった場合は、クローズ時にメモリを解放してください。
◆ GetFileSize
ファイルサイズの取得
- 引数
-
[in] | filehn | ファイルハンドル |
[out] | file_size | ファイルサイズ |
- 戻り値
- CriFsIoError エラーコード
- 説明:
- 指定されたファイルハンドルから、当該ファイルのサイズを取得する関数です。
- 注意
- この関数はメインスレッド上から直接実行される可能性があります。
そのため、この関数の中で長時間処理をブロックすることは避ける必要があります。
ファイルハンドルからファイルサイズを取得するのに時間がかかる場合には、 ファイルオープン時にあらかじめファイルサイズを取得(ファイルハンドル内に保持) しておき、本関数実行時にその値を返すよう関数を実装してください。
◆ Read
CriFsIoError( * Read) (CriFsFileHn filehn, CriSint64 offset, CriSint64 read_size, void *buffer, CriSint64 buffer_size) |
読み込みの開始
- 引数
-
[in] | filehn | ファイルハンドル |
[in] | offset | 読み込み開始位置 |
[in] | read_size | 読み込みサイズ |
[in] | buffer | 読み込み先バッファー |
[in] | buffer_size | バッファーサイズ |
- 戻り値
- CriFsIoError エラーコード
- 説明:
- データの読み込みを開始する関数です。
offset で指定された位置から、 read_size で指定されたサイズ分だけデータを buffer に読み込みます。
関数のインターフェイスとしては非同期I/O処理による実装を想定していますが、 スレッドを使用する場合(スレッドモデルに CRIFS_THREAD_MODEL_MULTI を指定する場合) には、この関数を同期I/O処理を使って実装しても問題ありません。
(関数内でファイルの読み込みを完了するまで待っても問題ありません。)
- 注意
- 実際に読み込めたサイズは、 GetReadSize 関数で返す必要があります。
同期I/O処理により本関数を実装する場合でも、読み込めたサイズは GetReadSize 関数 が実行されるまで、ファイルハンドル内に保持する必要があります。
◆ IsReadComplete
読み込み完了チェック
- 引数
-
[in] | filehn | ファイルハンドル |
[out] | result | ファイルの読み込みが完了したかどうか |
- 戻り値
- CriFsIoError エラーコード
- 説明:
- ファイルの読み込みが完了したかどうかを確認する関数です。
ファイルの読み込みが完了した場合は CRI_TRUE を、 読み込み途中の場合は CRI_FALSE を result にセットする必要があります。
- 注意
- result には、リード処理の成否に関係なく、リード処理が完了した時点 (デバイスへのアクセスが終了した時点)で CRI_TRUE をセットする必要があります。
リードエラーが発生した場合でも、 result に CRI_TRUE をセットし、 関数の戻り値は CRIFS_IO_ERROR_OK を返してください。
(リード処理が成功したかどうかについては、 GetReadSize 関数で判別しています。)
result に CRI_FALSE を返す限りは、CRI File System ライブラリは他の読み込み要求を一切処理しません。
(リードエラー発生時に result に CRI_FALSE をセットし続けた場合、 ファイルのロードができなくなったり、ハンドルの Destroy 関数から処理が復帰しなくなる可能性があります。
◆ CancelRead
ファイル読み込みのキャンセル発行
- 引数
-
- 戻り値
- CriFsIoError エラーコード
- 説明:
- デバイス側のファイル読み込みに対してキャンセルを発行し、即時に復帰する関数です。 戻り値は CRIFS_IO_ERROR_OK を返してください。
CRIFS_IO_ERROR_OK以外の値を返しても、 CRI File Systemの動作はCRIFS_IO_ERROR_OKを返した場合と同じです。
◆ GetReadSize
読み込みサイズの取得
- 引数
-
[in] | filehn | ファイルハンドル |
[out] | read_size | 読み込めたサイズ |
- 戻り値
- CriFsIoError エラーコード
- 説明:
- リード処理を行なった結果、実際にバッファーに読み込めたデータのサイズを返す関数です。
ファイルの終端等では、 Read 関数で指定したサイズ分のデータが必ずしも読み込めるとは限りません。
- 注意
- リードエラーが発生した場合、 read_size に -1 をセットし、 関数の戻り値は CRIFS_IO_ERROR_OK を返してください。
◆ Write
CriFsIoError( * Write) (CriFsFileHn filehn, CriSint64 offset, CriSint64 write_size, void *buffer, CriSint64 buffer_size) |
書き込みの開始
- 引数
-
[in] | filehn | ファイルハンドル |
[in] | offset | 書き込み開始位置 |
[in] | write_size | 書き込みサイズ |
[in] | buffer | 書き込み先バッファー |
[in] | buffer_size | バッファーサイズ |
- 戻り値
- CriFsIoError エラーコード
- 説明:
- データの書き込みを開始する関数です。
offset で指定された位置から、 write_size で指定されたサイズ分だけデータを buffer から書き込みます。
関数のインターフェイスとしては非同期I/O処理による実装を想定していますが、 スレッドを使用する場合(スレッドモデルに CRIFS_THREAD_MODEL_MULTI を指定する場合) には、この関数を同期I/O処理を使って実装しても問題ありません。
(関数内でファイルの書き込みを完了するまで待っても問題ありません。)
- 注意
- 実際に書き込めたサイズは、 GetWriteSize 関数で返す必要があります。
同期I/O処理により本関数を実装する場合でも、書き込めたサイズは GetWriteSize 関数 が実行されるまで、ファイルハンドル内に保持する必要があります。
- 備考:
- デバイスで書き込みを行なわない場合には、この関数を実装せず、 構造体のメンバーに CRI_NULL を指定することも可能です。
◆ IsWriteComplete
書き込み完了チェック
- 引数
-
[in] | filehn | ファイルハンドル |
[out] | result | ファイルの書き込みが完了したかどうか |
- 戻り値
- CriFsIoError エラーコード
- 説明:
- ファイルの書き込みが完了したかどうかを確認する関数です。
ファイルの書き込みが完了した場合は CRI_TRUE を、 書き込み途中の場合は CRI_FALSE を result にセットする必要があります。
- 注意
- ライトエラーが発生した場合、 result に CRI_TRUE をセットし、 関数の戻り値は CRIFS_IO_ERROR_OK を返してください。
- 備考:
- デバイスで書き込みを行なわない場合には、この関数を実装せず、 構造体のメンバーに CRI_NULL を指定することも可能です。
- 注意
- result には、ライト処理の成否に関係なく、ライト処理が完了した時点 (デバイスへのアクセスが終了した時点)で CRI_TRUE をセットする必要があります。
ライトエラーが発生した場合でも、 result に CRI_TRUE をセットし、 関数の戻り値は CRIFS_IO_ERROR_OK を返してください。
(ライト処理が成功したかどうかについては、 GetReadSize 関数で判別しています。)
result に CRI_FALSE を返す限りは、CRI File System ライブラリは他の読み込み要求を一切処理しません。
(ライトエラー発生時に result に CRI_FALSE をセットし続けた場合、 ファイルのロードができなくなったり、ハンドルの Destroy 関数から処理が復帰しなくなる可能性があります。
◆ CancelWrite
ファイル書き込みのキャンセル発行
- 引数
-
- 戻り値
- CriFsIoError エラーコード
- 説明:
- デバイス側のファイル書き込みに対してキャンセルを発行し、即時に復帰する関数です。 戻り値は CRIFS_IO_ERROR_OK を返してください。
CRIFS_IO_ERROR_OK以外の値を返しても、 CRI File Systemの動作はCRIFS_IO_ERROR_OKを返した場合と同じです。
◆ GetWriteSize
書き込みサイズの取得
- 引数
-
[in] | filehn | ファイルハンドル |
[out] | write_size | 書き込めたサイズ |
- 戻り値
- CriFsIoError エラーコード
- 説明:
- ライト処理を行なった結果、実際にバッファーに読み込めたデータのサイズを返す関数です。
- 注意
- ライトエラーが発生した場合、 write_size に -1 をセットし、 関数の戻り値は CRIFS_IO_ERROR_OK を返してください。
- 備考:
- デバイスで書き込みを行なわない場合には、この関数を実装せず、 構造体のメンバーに CRI_NULL を指定することも可能です。
◆ Flush
フラッシュの実行
- 引数
-
- 戻り値
- CriFsIoError エラーコード
- 説明:
- 書き込み用にバッファーリングされているデータを、 強制的にデバイスに書き出す処理を行う関数です。
( ANSI C 標準の API では fflush 関数に相当する処理です。)
- 備考:
- デバイスで書き込みを行なわない場合には、この関数を実装せず、 構造体のメンバーに CRI_NULL を指定することも可能です。
◆ Resize
ファイルサイズの変更
- 引数
-
[in] | filehn | ファイルハンドル |
[out] | size | ファイルサイズ |
- 戻り値
- CriFsIoError エラーコード
- 説明:
- ファイルのサイズを指定したサイズに変更する関数です。
- 補足:
- 本関数は、DMA転送サイズの制限等によりデバイスへの書き込みがバイト単位で 行なえない場合に、ファイルサイズを補正するために使用します。
そのため、書き込みがバイト単位で可能なデバイスについては、この関数を実装せず、 構造体のメンバーに CRI_NULL を指定することも可能です。
- 備考:
- デバイスで書き込みを行なわない場合には、この関数を実装せず、 構造体のメンバーに CRI_NULL を指定することも可能です。
◆ GetNativeFileHandle
ネイティブファイルハンドルの取得
- 引数
-
[in] | filehn | ファイルハンドル |
[out] | native_filehn | ネイティブのファイルハンドル |
- 戻り値
- CriFsIoError エラーコード
- 説明:
- プラットフォームSDKで利用されるファイルのハンドルを取得する関数です。
例えば、 ANSI C 標準の fopen 関数を使用してファイルをオープンした場合、 native_filehn としてファイルポインター( FILE * )を返す必要があります。
- 備考:
- 現状、PLAYSTATION3以外の機種ではこの関数を実装する必要はありません。
◆ SetAddReadProgressCallback
読み込みプログレス加算コールバックの設定
- 引数
-
[in] | filehn | ファイルハンドル |
[in] | callback | 読み込みプログレス加算コールバック |
[in] | obj | 内部オブジェクト |
- 説明:
- 本関数は、::criFsLoader_GetProgress で得られる進捗を、単位読み込みサイズより 細かい粒度で更新させるための、読み込みプログレス加算コールバックを設定する関数です。
本関数を実装しない場合や、本関数で渡されたコールバック関数を使用しない場合、 criFsLoader_GetProgress で得られる進捗は、基本的に単位読み込みサイズ毎に更新されます。
本関数を実装する場合は、渡されたコールバック関数を Read 関数内で呼び出してください。 また、呼び出す際には第一引数に obj、第二引数にメモリへの読み込みが完了したサイズを バイト単位で渡してください。
例えば、リード要求をデバイス内で 8192byte ずつに分割して読み込む場合は、 8192byte の読み込み完了毎に、第二引数に 8192 を渡して呼び出してください。
この、読み込みプログレス加算コールバック呼び出しによって criFsLoader_GetProgress で得られる進捗が更新されます。単位読み込みサイズより細かい粒度で更新を 行うことで criFsLoader_GetProgress で得られる進捗の粒度が細かくなります。
- 備考:
- 読み込みリクエストより細かい粒度で読み込み進捗を取得できない場合は、 実装するメリットはありません。
- 参照
- criFsLoader_GetProgress
◆ CanParallelRead
複数の同時ファイルアクセス要求が可能かどうかの問い合わせ
- 引数
-
[out] | result | 複数の同時ファイルアクセス要求が可能かどうか |
- 説明:
- このI/Oインターフェースが複数の同時ファイルアクセス要求が可能であるかどうかを返す関数です。
本関数を実装しない場合、不可能であるとみなされます。
本関数を実装されていて、result が CRI_TRUE だった場合、 criFsLoader は効率よく複数ファイルのロードを行うために並列でリード要求を行うようになります。
- 備考:
- 並列でリード要求を行う場合、CriFsFileIoMode が CRIFS_FILE_IO_MODE_OPEN_EVERY_TIME である必要があります。
この構造体詳解は次のファイルから抽出されました: