Class CriFsGroupLoader

Inheritance
object
CriFsGroupLoader
Implements
Inherited Members
Namespace: CriWare
Assembly: CriWare.CriFs.dll
Syntax
public class CriFsGroupLoader : IDisposable

Constructors

CriFsGroupLoader(CriFsBind, ArgString, ArgString)

グループローダーの作成

Declaration
public CriFsGroupLoader(CriFsBind binderId, ArgString groupname, ArgString attrname)
Parameters
Type Name Description
CriFsBind binderId

バインドID
ArgString groupname

グループ名
ArgString attrname

アトリビュート名
Remarks

説明： バインドIDからグループローダーを作成し、グループローダーオブジェクトを返します。 本関数は完了復帰関数です。 グループ情報付きのCPKファイルをバインドしたバインドIDが必要です。 指定されたグループ名やアトリビュート名が存在しない場合、グループローダーを作成しません。 グループローダーが扱うグループ名とアトリビュート名は、グループローダー作成後に変更することは できません。 他のグループ＋アトリビュートを扱う場合、別のグループローダーを作成します。 アトリビュート名にnullを指定した場合、指定グループに属する全てのファイルがグループロードの対象となります。 また、パッキングツールのアトリビュート指定を「none」とした場合も、アトリビュート名にnullを指定します。

Properties

LoadStartCallback

コールバックイベントオブジェクト

Declaration
public CriFsGroupLoader.LoadStartCbFunc LoadStartCallback { get; }
Property Value
Type Description
CriFsGroupLoader.LoadStartCbFunc
See Also

NativeHandle

ネイティブハンドル

Declaration
public NativeHandleIntPtr NativeHandle { get; }
Property Value
Type Description
NativeHandleIntPtr

Methods

CreateFromBinderHn(CriFsBinder, ArgString, ArgString, out CriFsGroupLoader)

Pro

バインダーハンドル対応のグループローダーの作成

Declaration
public static CriErr.Error CreateFromBinderHn(CriFsBinder bndrhn, ArgString groupname, ArgString attrname, out CriFsGroupLoader grouploaderhn)
Parameters
Type Name Description
CriFsBinder bndrhn

バインダーハンドル(複数CPKファイルをバインドしているバインダー)
ArgString groupname

グループ名(NULL指定は不可)
ArgString attrname

アトリビュート名(NULL指定可能)
CriFsGroupLoader grouploaderhn

グループローダーハンドル
Returns
Type Description
CriErr.Error

CriErr.Error エラーコード
Remarks

説明: バインダーオブジェクトからグループローダーを作成し、グループローダーオブジェクトを返します。 この関数を利用すると、グループロード機能とマルチバインド機能を併用することができます。 フルビルドしたCPKファイルと、差分ビルドしたCPKファイルをマルチバインドすることで、一部のコンテンツファイルを更新した場合のCPKビルド時間やCPKファイル転送時間を節約することができます。 １回のグループロードは、どれか１つのCPKファイルが読み込み対象となります。この制約によって、グループロードの最大のメリットである一括処理の動作が維持されています。 よって、更新されたコンテンツファイルで差分CPKファイルを作成してマルチバインドする場合は、グループ単位で（変更のないコンテンツファイルも含めて）差分CPKファイルに含めておく必要があります。 差分CPKファイルの情報では、グループ内の全ファイルが削除されたこととグループに変更が無かったことが区別できません。削除やリネームで消えたはずのグループでも、フルビルドCPKからロード成功してしまいます。この動作が好ましくない場合、フルビルドCPKを作り直すことで解消できます。 本関数を利用する場合は、SetPriority(CriFsBind, int) 関数で明示的に優先度設定を行うことを推奨します。フルビルドCPKと差分CPKをマルチバインドする場合、差分CPKのプライオリティを高く設定してください。

Dispose()

Pro

グループローダーの破棄

Declaration
public void Dispose()
Remarks

説明： グループローダーを破棄します。 本関数は完了復帰関数です。 グループロード中に本関数を呼び出した場合はロードを中断し、ロードのためにグループローダー内部で確保していた CriFsLoader を解放します。 グループロード中のグループローダーを破棄する場合、内部の CriFsLoader が停止するのを待ちますので、 本関数から復帰するまでに時間がかかる場合があります。 これを回避するには、グループローダーのステータスが Loading でないことを確認してから、 本関数を呼出します。

GetAttributeName(out NativeString)

Pro

グループ属性の取得

Declaration
public CriErr.Error GetAttributeName(out NativeString attrname)
Parameters
Type Name Description
NativeString attrname

グループ属性
Returns
Type Description
CriErr.Error

CriErr.Error エラーコード
Remarks

説明： グループローダーで扱うグループのグループ属性を取得します。

GetGroupFileInfo(ArgString, out NativeReference<GroupFileInfo>)

Pro

CriFs.GroupFileInfo構造体の取得

Declaration
public CriErr.Error GetGroupFileInfo(ArgString fpath, out NativeReference<CriFs.GroupFileInfo> gfinfo)
Parameters
Type Name Description
ArgString fpath

ファイル名フルパス
NativeReference<CriFs.GroupFileInfo> gfinfo

CriFs.GroupFileInfo構造体へのポインターへのポインター
Returns
Type Description
CriErr.Error

CriErr.Error エラーコード
Remarks

説明： 指定されたファイルの CriFs.GroupFileInfo 構造体へのポインターを取得します。 ファイル名はフルパス名で指定します。 指定されたファイルが見つからない場合は、出力値が null となります。

GetGroupFileInfoById(int, out NativeReference<GroupFileInfo>)

Pro

CriFs.GroupFileInfo構造体の取得(ID指定)

Declaration
public CriErr.Error GetGroupFileInfoById(int id, out NativeReference<CriFs.GroupFileInfo> gfinfo)
Parameters
Type Name Description
int id

コンテンツファイルID
NativeReference<CriFs.GroupFileInfo> gfinfo

CriFs.GroupFileInfo構造体へのポインターへのポインター
Returns
Type Description
CriErr.Error

CriErr.Error エラーコード
Remarks

説明： 指定されたファイルの CriFs.GroupFileInfo 構造体へのポインターを取得します。 ファイルはコンテンツファイルIDで指定します。 指定されたファイルが見つからない場合は、出力値が null となります。

GetGroupFileInfoIndex(ArgString, out int)

Pro

CriFs.GroupFileInfo構造体の配列インデクスの取得

Declaration
public CriErr.Error GetGroupFileInfoIndex(ArgString fpath, out int index)
Parameters
Type Name Description
ArgString fpath

ファイル名フルパス
int index

配列インデクス
Returns
Type Description
CriErr.Error

CriErr.Error エラーコード
Remarks

説明： 指定されたファイルの CriFs.GroupFileInfo 構造体の配列インデクスを取得します。 ファイル名はフルパス名で指定します。指定されたファイルの検索にはバイナリサーチを使用します。 指定されたファイルが見つからない場合は、返値が-1となります。 グループロードされた個々のファイルが実際にロードされたアドレスは、 CriFs.GroupFileInfo 構造体に記述されます。 ロードされたデータへアクセスするには、CriFs.GroupFileInfo 構造体を取得する必要があります。 CriFs.GroupFileInfo 構造体を取得する方法には、ロードしたファイルのファイル名もしくは コンテンツファイルIDを指定し、該当する構造体要素を取得する方法と、本関数で取得したインデクスにより 構造体配列を直接アクセスする方法の２通りがあります。

GetGroupFileInfoIndexById(int, out int)

Pro

CriFs.GroupFileInfo構造体の配列インデクスの取得(ID指定)

Declaration
public CriErr.Error GetGroupFileInfoIndexById(int id, out int index)
Parameters
Type Name Description
int id

コンテンツファイルID
int index

配列インデクス
Returns
Type Description
CriErr.Error

CriErr.Error エラーコード
Remarks

説明： 指定されたファイルの CriFs.GroupFileInfo 構造体の配列インデクスを取得します。 ファイルはコンテンツファイルIDで指定します。指定されたファイルの検索にはリニアサーチを使用しています。 指定されたファイルが見つからない場合は、返値が-1となります。 グループロードされた個々のファイルが実際にロードされたアドレスは、 CriFs.GroupFileInfo 構造体に記述されます。 検索方法の都合上、既にグループロード済で CriFs.GroupFileInfo 情報を取得している場合は、 CriFs.GroupFileInfo 情報のIDを直接検索する方が、本関数でインデクスを取得するよりも検索効率が高いです。 ロードされたデータへアクセスするには、CriFs.GroupFileInfo 構造体を取得する必要があります。 CriFs.GroupFileInfo 構造体を取得する方法には、ロードしたファイルのファイル名もしくは コンテンツファイルIDを指定し、該当する構造体要素を取得する方法と、本関数で取得したインデクスにより 構造体配列を直接アクセスする方法の２通りがあります。

GetGroupFileInfoStartOffset(CriFsGroupLoader, out int)

Pro

特定アトリビュートのCriFs.GroupFileInfo構造体配列の開始オフセットの取得

Declaration
public CriErr.Error GetGroupFileInfoStartOffset(CriFsGroupLoader groupAttr, out int offset)
Parameters
Type Name Description
CriFsGroupLoader groupAttr

グループローダーハンドル(特定アトリビュート)
int offset

グループ全体のCriFs.GroupFileInfo構造体の配列に対する、特定アトリビュートが開始するオフセット
Returns
Type Description
CriErr.Error

CriErr.Error エラーコード
Remarks

説明： 下記の条件でグループローダーを利用する場合に、この関数を利用すると検索処理効率を改善することができます。

適用条件: 　・グループ内に複数のアトリビュートのファイルを含める。 　・グループ内の複数のアトリビュートのファイルを同時にロードする。 　・アトリビュート毎に転送先を切り分ける。 　・アトリビュートを特定する情報は持たずに、ファイル名またはファイルIDからグループファイル情報を検索する。 　・グループの階層構造（サブグループ）は利用していない。 　・CPKファイル内に本APIが利用する追加情報が記録されている。（本APIのサポートは環境依存です） この関数を利用しない場合は、個々のファイルがどのアトリビュートに属するか分からないので、全てのグループオブジェクトを逐次検索しなければなりません。 この関数を利用する場合は、１回の検索で目的のファイルを見つけることができます。 グループロードを実行するオブジェクトは、グループ名とアトリビュート名を指定して、グループローダーオブジェクトを作成してください。 さらに１つ、検索だけを目的とした、グループ全体のグループローダーオブジェクトを作成します。この時はグループ名だけを指定し、アトリビュート名にはCRI_NULLを指定してください。 CriFs.GroupFileInfo構造体配列については、グループ全体の配列を連続メモリとして確保してください。 このグループ全体の配列を切り分けて、個々の LoadBulk(Span<byte>, Span<GroupFileInfo>) 関数の引数に指定します。 個々のグループローダーの動作と、グループ全体に対する検索処理が整合するためには、グループ全体の配列を適切に切り分ける必要があります。 本関数が出力する「特定アトリビュートの開始オフセット」を利用して、全体の配列を切り分けてください。

注意: ※:グループに含まれる全てのアトリビュートをロード処理対象としない場合には注意が必要です。 ロードしなかったファイルでも検索が成功しますが、取得したインデックスで参照できる CriFs.GroupFileInfo構造体の内容は不定値となっています。 ロードしなかったファイルを検索する可能性があるなら、あらかじめ配列をゼロクリアしておき、 構造体の内容が無効であることを識別できるようにしてください。

注意: 本APIのサポートは環境依存です。未サポートの環境で呼び出した場合はエラーとなります。

GetGroupFileInfos(Span<GroupFileInfo>)

Pro

グループファイル情報の取得

Declaration
public CriErr.Error GetGroupFileInfos(Span<CriFs.GroupFileInfo> gfinf)
Parameters
Type Name Description
Span<CriFs.GroupFileInfo> gfinf
Returns
Type Description
CriErr.Error

CriErr.Error エラーコード
Remarks

説明： グループ化された複数ファイルデータ情報を取得します。 ファイル数分の CriFs.GroupFileInfo 構造体の配列を指定する必要があります。 パッキングツールのアトリビュート指定を「none」としたグループに対しては、本関数に指定するグループ ローダー作成時のアトリビュート名指定をnullとして下さい。 取得されるグループファイル情報( CriFs.GroupFileInfo )の内、datapointerで指される読込先はnullとなります。

GetGroupName(out NativeString)

Pro

グループ名の取得

Declaration
public CriErr.Error GetGroupName(out NativeString groupname)
Parameters
Type Name Description
NativeString groupname

グループ名
Returns
Type Description
CriErr.Error

CriErr.Error エラーコード
Remarks

説明： グループローダーで扱うグループのグループ名を取得します。

GetLoadedFiles(out int)

Pro

ロードされたファイル数の取得

Declaration
public CriErr.Error GetLoadedFiles(out int nfiles)
Parameters
Type Name Description
int nfiles

ロードされたファイル数
Returns
Type Description
CriErr.Error

CriErr.Error エラーコード
Remarks

説明： LoadBulk(Span<byte>, Span<GroupFileInfo>) 関数で既に読み込まれたファイルの数を返します。

GetLoaderPriority(out Priority)

Pro

プライオリティの取得

Declaration
public CriErr.Error GetLoaderPriority(out CriFsLoader.Priority prio)
Parameters
Type Name Description
CriFsLoader.Priority prio

読み込みプライオリティ
Returns
Type Description
CriErr.Error

CriErr.Error エラーコード
Remarks

説明: グループローダー内で使用するローダー( CriFsLoader )のプライオリティを取得します（初期値は Normal です）。 ローダーのプライオリティに関しては、GetPriority(out Priority) や SetPriority(Priority) の説明も参照ください。

See Also

GetNumberOfGroupFiles(out int)

Pro

グループファイル数の取得

Declaration
public CriErr.Error GetNumberOfGroupFiles(out int nfiles)
Parameters
Type Name Description
int nfiles

グループファイル数
Returns
Type Description
CriErr.Error

CriErr.Error エラーコード
Remarks

説明： 指定のグループに属するファイル数を取得します。 LoadBulk(Span<byte>, Span<GroupFileInfo>) 関数の引数 gfinf の配列の要素数は、本関数で取得される グループファイル数となります。

GetStatus(out Status)

Pro

ロードステータスの取得

Declaration
public CriErr.Error GetStatus(out CriFsLoader.Status status)
Parameters
Type Name Description
CriFsLoader.Status status

CriFsGroupLoaderStatusロードステータス
Returns
Type Description
CriErr.Error

CriErr.Error エラーコード
Remarks

説明： グループローダーのロードステータスを返します。 グループロード対象の全てのファイルのロードを完了した場合、 Complete を返します。

GetTotalGroupDataSize(out long)

Pro

グループデータサイズの取得

Declaration
public CriErr.Error GetTotalGroupDataSize(out long datasize)
Parameters
Type Name Description
long datasize

データサイズ
Returns
Type Description
CriErr.Error

CriErr.Error エラーコード
Remarks

説明： グループロードに必要な読込領域のサイズを取得します。 アライメントなども加味されたデータサイズとなります。

IsLoaded(in GroupFileInfo, out NativeBool)

Pro

ファイルの読込状態の取得

Declaration
public static CriErr.Error IsLoaded(in CriFs.GroupFileInfo gfinfo, out NativeBool result)
Parameters
Type Name Description
CriFs.GroupFileInfo gfinfo

読込状態を取得するファイルの CriFs.GroupFileInfo 構造体へのポインター
NativeBool result

ファイルの読込状態（CRI_TRUE：読込済 CRI_FALSE:未読込)
Returns
Type Description
CriErr.Error

CriErr.Error エラーコード
Remarks

説明： 指定されたファイルが読み込まれたかどうかを取得します。 読込状態を取得するファイルの CriFs.GroupFileInfo 構造体へのポインターは GetGroupFileInfoIndex(ArgString, out int) 関数や GetGroupFileInfo(ArgString, out NativeReference<GroupFileInfo>) 関数で取得します。

LimitNumPreparingFiles(int)

Pro

サーバー処理当たりの準備ファイル数の制限

Declaration
public CriErr.Error LimitNumPreparingFiles(int nfilePerServer)
Parameters
Type Name Description
int nfilePerServer

１サーバー当たりの準備処理ファイル数、または、特別値 GrouploaderNoPreparationLimit
Returns
Type Description
CriErr.Error

CriErr.Error エラーコード
Remarks

説明： グループローダーの準備処理の処理方法を設定します。 この関数を呼び出さない場合、または、GrouploaderNoPreparationLimit を指定した場合は、 LoadBulk(Span<byte>, Span<GroupFileInfo>) 内部で準備処理を完結させます。この処理方法では、グループ内ファイル数が多い 場合に LoadBulk(Span<byte>, Span<GroupFileInfo>) 関数の処理時間が長くなり、コマ落ちが発生する場合があります。 この問題を回避する手段として、グループローダーの準備処理をサーバー処理に分散させる機能を追加しました。 特別値以外の数値を指定した場合、準備処理は LoadBulk(Span<byte>, Span<GroupFileInfo>) 関数からサーバー処理に移管され、 1回のサーバー処理で準備処理を行うファイルの数は指定した数に制限されます。 グループローダーのサーバー処理は、GetStatus(out Status) 関数内で実行されます。 具体的なコードの例は以下のとおりです。

LoadBulk(Span<byte>, Span<GroupFileInfo>)

Pro

グループロードの開始

Declaration
public CriErr.Error LoadBulk(Span<byte> buffer, Span<CriFs.GroupFileInfo> gfinf)
Parameters
Type Name Description
Span<byte> buffer

ロード先バッファーへのポインター
Span<CriFs.GroupFileInfo> gfinf
Returns
Type Description
CriErr.Error

CriErr.Error エラーコード
Remarks

説明： グループ化された複数ファイルデータの読み込みを開始します。 ファイル数分の CriFs.GroupFileInfo 構造体の配列を指定する必要があります。 指定のグループファイルを読み込めるサイズのロード領域が必要です。 本関数は即時復帰関数です。 ロードの完了状態を取得するには GetStatus(out Status) 関数を使用してください。 パッキングツールのアトリビュート指定を「none」としたグループを読み込む場合、本関数に指定するグループ ローダーは、グループローダー作成時にアトリビュート名指定をnullとします。 グループロードコールバック関数を設定した場合、コールバック関数の返値をロードアドレスとしますので、 本関数の引数 buffer, buffer_size は参照されません。 なお指定した gfinf はロード後も GetGroupFileInfoIndex(ArgString, out int) 関数等の情報取得関数にてライブラリから参照を行います。 そのため基本的にはオブジェクト破棄まで領域は保持しておく必要があります。 グループローダー内部で複数の CriFsLoader を利用してロードを行います。 CriFsLoader を１つも作成 できない場合、エラーコールバックが呼ばれます。グループローダーで作成した CriFsLoader は、 グループロード完了時に破棄されます。

SetLoadLimiter(LoadLimiterNo)

Pro

ロードリミッタ番号の設定

Declaration
public CriErr.Error SetLoadLimiter(CriFs.LoadLimiterNo limiterNo)
Parameters
Type Name Description
CriFs.LoadLimiterNo limiterNo

ロードリミッタ番号
Returns
Type Description
CriErr.Error

CriErr.Error エラーコード
Remarks

説明: CriFsGroupLoaderオブジェクトにロードリミッタ番号を割り当てます。 共通のリミッタ番号を割り当てた全てのローダー、グループローダー、バッチローダーの合計読み込みサイズが制限されます。

注意: ゲーム機向けではロードリミッタ機能は非サポートです。この関数は呼び出さないでください。

See Also

SetLoadStartCallback(delegate* unmanaged[Cdecl]<IntPtr, GroupFileInfo*, IntPtr>, IntPtr)

Pro

ロード開始コールバック関数の設定

Declaration
public CriErr.Error SetLoadStartCallback(delegate* unmanaged[Cdecl]<IntPtr, CriFs.GroupFileInfo*, IntPtr> func, IntPtr obj)
Parameters
Type Name Description
delegate* unmanaged[Cdecl]<IntPtr, GroupFileInfo*, IntPtr> func

グループローダーコールバック関数
IntPtr obj

グループローダーコールバック関数引数
Returns
Type Description
CriErr.Error

CriErr.Error エラーコード
Remarks

説明： グループロード実施時にファイル毎に呼び出されるコールバック関数を設定します。 本関数で設定したコールバック関数は、ロードリクエストを行う前にファイル毎に呼出されます （つまり、ファイル数と同じ回数コールバック関数が呼出されます）。 グループロードコールバック関数を設定した場合、ファイル毎にコールバック関数を呼出すため、 複数ファイルの一括ロードは行えません。 グループロードコールバック関数にnullを設定した場合、コールバック関数の設定は解除されます。 ●コールバック関数について コールバック関数は引数として、obj:ユーザーが指定したオブジェクトと、gfinfo:ロードするファイルの 情報構造体が渡されます。 コールバック関数の返値は、そのファイルを読み込むバッファーへのポインターとなります。 ファイルの読込を行いたくない場合は、 null を返値としてください。

注意: コールバック関数は1つしか登録できません。 登録操作を複数回行った場合、既に登録済みのコールバック関数が、 後から登録したコールバック関数により上書きされてしまいます。 funcにnullを指定するとことで登録済み関数の登録解除が行えます。

SetLoaderPriority(Priority)

Pro

プライオリティの設定

Declaration
public CriErr.Error SetLoaderPriority(CriFsLoader.Priority prio)
Parameters
Type Name Description
CriFsLoader.Priority prio

読み込みプライオリティ
Returns
Type Description
CriErr.Error

CriErr.Error エラーコード
Remarks

説明: グループローダー内で使用するローダー( CriFsLoader )のプライオリティを設定します（初期値は Normal です）。 ローダーのプライオリティに関しては、GetPriority(out Priority) や SetPriority(Priority) の説明も参照ください。

See Also

SetReadUnitSize(long)

Pro

単位読み込みサイズの設定

Declaration
public CriErr.Error SetReadUnitSize(long unitSize)
Parameters
Type Name Description
long unitSize

単位読み込みサイズ
Returns
Type Description
CriErr.Error

CriErr.Error エラーコード
Remarks

説明: グループローダー内で使用するローダーの単位読み込みサイズを設定します。 CriFsLoaderは、大きなサイズのリード要求を処理する際、それを複数の小さな単位のリード処理に分割して連続実行します。 この関数を使用することで単位リード処理サイズを変更することが可能です。 リード要求のキャンセルや、高プライオリティのリード処理の割り込み等は、単位リードサイズ境界でのみ処理されます。 そのため、ユニットサイズを小さく設定すると、I/O処理のレスポンスが向上します。逆に、ユニットサイズを大きく設定すると、ファイル単位の読み込み速度が向上します。

SetUseLoadedFlag(NativeBool)

Pro

単一ファイルのロード確認の設定

Declaration
public static void SetUseLoadedFlag(NativeBool useFlag)
Parameters
Type Name Description
NativeBool useFlag

CRI_TRUE または CRI_FALSE
Remarks

説明: IsLoaded(in GroupFileInfo, out NativeBool)関数を使用するかを設定します。 trueを指定すると使用し、falseを指定すると使用しません IsLoaded(in GroupFileInfo, out NativeBool)関数を使用しない場合、ロード完了時の処理が早くなりまが、 単一ファイルのロード確認が行えません。 LoadBulk(Span<byte>, Span<GroupFileInfo>) 関数を実行する前に本関数を呼んでください。

See Also

Stop()

Pro

グループロードの停止（中断）

Declaration
public CriErr.Error Stop()
Returns
Type Description
CriErr.Error

CriErr.Error エラーコード
Remarks

説明： グループローダーでのファイルロードを中断します。 グループロードを中断するまでにロードされたファイル数やファイルの内容はそのまま保持されます。 本関数は即時復帰関数です。 グループロードの際、グループローダー内部で CriFsLoader を作成してファイルロードを行います。 本関数を呼出した場合、グループロードに使用している CriFsLoader に中断（Stop）の指示を出して 復帰します。 そのため、本関数復帰時点では、まだファイルロード中である可能性があります。 グループローダーは、内部で使用している CriFsLoader のロード停止確認後に、その CriFsLoader を 解放し、グループローダーのステータスを Stop にします。 この一連の処理は GetStatus(out Status) 関数呼び出し時に行われますので、本関数呼び出し後は、 グループローダーのステータスが Loading でないことを確認してください。 そうしない場合、グループローダー内部で使用している CriFsLoader が解放されませんので、 他のグループローダーが CriFsLoader を確保できなくなる可能性があります。

Implements