# MB_ReadSegment

## C Specification

      #include <nitro/mb.h>

      BOOL MB_ReadSegment( FSFile *file, void *buf, u32 len );

## Description

This function extracts only the segment data necessary for the download process from the specified program file. The function fails if the specified program is not the right program or if the buffer size is not large enough. Applications must call the `MB_RegisterFile` function using the segment data obtained with this function.

If the specified buffer size is at least `MB_GetSegmentLength`, calling this function prepares all segment data in memory. If the size is smaller than `MB_GetSegmentLength`, but at least `MB_SEGMENT_BUFFER_MIN` (as required), it is set to dynamically load the remainder from CARD-ROM that it cannot prepare in memory. In the case of this setting, it is frequently impossible to respond immediately to child requests, which reduce transfer efficiency.

The function fails if the size is less than `MB_SEGMENT_BUFFER_MIN`.

#### For Example

    BOOL    reg_file_done = FALSE;

    FSFile file[1];
    FS_InitFile(file);
    if(FS_OpenFile(file, p_game_reg->romFilePathp)) {
        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);
    }

#### Internal Operation

Internally, this function calls the `FS_ReadFile` function.

Note that when you use segment data that is dynamically set to be read from CARD-ROM, and call the `MB_RegisterFile` function, an internal thread is started automatically to access CARD-ROM. This thread exists until either the `MB_End` or `MB_EndToIdle` function completes.

## Arguments

`file` | The `FSFile` structure holding the handle of the program file. The seek position of this file must point to the top of the program binary. Also, the seek position maintains the initial position when returned from this function. When NULL is specified for this pointer, the parent application itself is seen as a download program file and the segment is extracted.
`buf` | Pointer to the memory that saves the extracted segment information.
`len` | Byte size of `buf`. This size must at least that of `MB_SEGMENT_BUFFER_MIN`.

## Return Values

This function returns `TRUE` when the segment data is extracted correctly from the program. Otherwise, it returns `FALSE`.

## See Also

`FS_ReadFile, MB_End, MB_EndToIdle, MB_GetSegmentLength, MB_SEGMENT_BUFFER_MIN, MB_RegisterFile`

## Revision History

11/11/2004 Changed description to include the clone boot release and new read delay method.
09/10/2004 Added description of the operation when specifying NULL for the file pointer.
08/09/2004 Initial version.