# MB_ReadSegment

## 構文

  `#include <nitro/mb.h>`
  `BOOL MB_ReadSegment(FSFile *file, void *buf, u32 len);`

## 引数

file

プログラムファイルのハンドルを保持するFSFile構造体
このファイルのシーク位置はプログラムバイナリの先頭を指している必要があります。
また、シーク位置はこの関数から返ったときに元の位置を保持します。
このポインタにNULLを指定した場合は親機アプリケーション自身を
ダウンロードプログラムファイルとみなしてセグメントを抽出します。

buf | 抽出したセグメント情報を格納するメモリへのポインタ
len | bufのバイトサイズ このサイズは、少なくとも`MB_SEGMENT_BUFFER_MIN`以上である必要があります。

## 返り値

プログラムから正しくセグメント情報を抽出できた場合はTRUE、そうでない場合はFALSEを返します。

## 説明

指定したプログラムファイルから、ダウンロード処理に直接必要となるセグメント情報だけを抽出します。
ユーザアプリケーションは、この関数で得られたセグメントデータを用いて`MB_RegisterFile()`を呼び出す必要があります。
指定したバッファのサイズが`MB_GetSegmentLength()`の返り値以上である場合は、
この関数呼び出しの中で前もって全てのセグメントデータをメモリ上に準備します。
サイズがそれよりも小さくかつ`MB_SEGMENT_BUFFER_MIN`以上である場合は、
メモリ上に準備できない残りの部分を、指定のアーカイブから必要に応じて動的に読み込むよう設定されます。
この設定の場合、子機の要求へ即座に応答できない状況がしばしば発生するために転送効率は若干低下します。
この設定を使用すると、MBライブラリの内部でスレッドがひとつだけ自動的に起動します。詳細は [内部動作] の項を参照ください。
サイズが`MB_SEGMENT_BUFFER_MIN`未満である場合は失敗します。

    例:
        BOOL    reg_file_done = FALSE;

        FSFile file[1];
        FS_InitFile(file);
        if(FS_OpenFileEx(file, p_game_reg->romFilePathp, FS_FILEMODE_R)) {
            u32  len = MB_GetSegmentLength(file);
            if(len > 0) {
                void *mem = OS_Alloc(len);
                if(mem != NULL) {
                    if(MB_ReadSegment(file, mem, len)) {
                        if(MB_RegisterFile(p_game_reg, mem)) {
                            reg_file_done = TRUE;
                        }
                    }
                }
            }
            FS_CloseFile(file);
        }

## 内部動作

この関数は内部で`FS_ReadFile()` を呼び出します。
アーカイブから動的に読み込むよう設定されたセグメントデータを使用して`MB_RegisterFile()`を呼び出した場合、
アーカイブへアクセスするためのスレッドが内部でひとつだけ自動的に起動する点に注意してください。
このスレッドは`MB_End()`か`MB_EndToIdle()`が完了するまで存在します。
このスレッドの優先度は0で、子機群のセグメントデータ要求が発生するまでスリープし、必要に応じて不定期にカードアクセスを行います。

## 参照

MB_SEGMENT_BUFFER_MIN
MB_GetSegmentLength MB_RegisterFile

## 履歴

2008/10/02 サンプルコードを一部訂正
2005/04/11 タスクスレッドに関する説明を追記
2004/12/07 遅延リード方式について、適用対象がNITRO-CARDから任意のアーカイブに拡張されたことにともなう記述変更
2004/11/11 クローンブート公開に伴う記述変更. 遅延リード方式追加に伴う記述変更
2004/09/10 ファイルポインタにNULLを指定した際の動作説明を追加
2004/08/09 初版