1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2<html> 3 4<head> 5<META http-equiv="Content-Type" content="text/html; charset=windows-1252"> 6<META name="GENERATOR" content="IBM WebSphere Studio Homepage Builder Version 7.0.0.0 for Windows"> 7<META http-equiv="Content-Style-Type" content="text/css"> 8<title>MB_ReadSegment</title> 9<LINK rel="stylesheet" href="../../css/nitro.css" type="text/css"> 10</head> 11 12<body> 13 14<h1 align="left">MB_ReadSegment <IMG src="../../image/NTR.gif" width="24" height="12" border="0" align=middle><IMG src="../../image/TWL.gif" width="24" height="12" border="0" align=middle></h1> 15<h2>Syntax</h2> 16 17<dl> 18 <dd> 19<CODE>#include <nitro/mb.h></CODE><BR> 20 <BR> 21 <CODE>BOOL MB_ReadSegment(FSFile *file, void *buf, u32 len);</CODE><br> 22 <br> 23 </dd> 24</dl> 25<h2>Arguments</h2> 26<p> 27<TABLE border="1" width="100%"> 28 <TBODY> 29 <TR> 30<TD width="13%"><EM><STRONG>file</STRONG></EM></TD> 31<TD width="87%">The <code>FSFile</code> structure that holds the program file handle. The seek position of this file must point to the top of the program binary. Also, the seek position holds the initial position when returned from this function. When NULL is specified for this pointer, the parent application is seen as a download program file and the segment is extracted. 32 </TD> 33 </TR> 34 <TR> 35<TD width="13%"><EM><STRONG>buf</STRONG></EM></TD> 36<TD width="87%">Pointer to the memory that saves the extracted segment information.</TD> 37 </TR> 38 <TR> 39<TD width="13%"><EM><STRONG>len</STRONG></EM></TD> 40<TD width="87%">Byte size of <code>buf</code>. This size must at least that of <code><A href="../mb_segment_buffer_min_const.html">MB_SEGMENT_BUFFER_MIN</A></code>.</TD> 41 </TR> 42 </TBODY> 43</TABLE> 44</p> 45 46<h2>Return Values</h2> 47<p>This function returns <code>TRUE</code> when the segment data is extracted correctly from the program. Otherwise, it returns <code>FALSE</code>.</p> 48 49<H2>Description</H2> 50<P> 51This function extracts only the segment data necessary for the download process from the specified program file. Applications must call the <CODE><A href="MB_RegisterFile.html">MB_RegisterFile</A></CODE> function using the segment data obtained with this function.<br><br> When the specified buffer size is at least the value returned by the <code><A href="MB_GetSegmentLength.html">MB_GetSegmentLength</A></code> function, calling this function prepares all segment data in memory. When the size is smaller than that returned by the <code><A href="MB_GetSegmentLength.html">MB_GetSegmentLength</A></code> function, but at least <code><A href="../mb_segment_buffer_min_const.html">MB_SEGMENT_BUFFER_MIN</A></code> (as required), it is set to dynamically load the remainder that it cannot prepare in memory from the specified archive. In the case of this setting, it is frequently impossible to respond immediately to child requests, which slightly reduces transfer efficiency.<br><font color="#800000">When this setting is used, a single thread will be automatically started in the MB library. For details, see the <B>Internal Operation</B> section.</font><br><br>This function fails if the size is less than <code><A href="../mb_segment_buffer_min_const.html">MB_SEGMENT_BUFFER_MIN</A></code>.<br> <br> 52<pre><CODE> 53<STRONG>Example:</STRONG> 54 BOOL reg_file_done = FALSE; 55 56 FSFile file[1]; 57 FS_InitFile(file); 58 if(FS_OpenFileEx(file, p_game_reg->romFilePathp, FS_FILEMODE_R)) { 59 u32 len = MB_GetSegmentLength(file); 60 if(len > 0) { 61 void *mem = OS_Alloc(len); 62 if(mem != NULL) { 63 if(MB_ReadSegment(file, mem, len)) { 64 if(MB_RegisterFile(p_game_reg, mem)) { 65 reg_file_done = TRUE; 66 } 67 } 68 } 69 } 70 FS_CloseFile(file); 71 } 72<BR> 73</CODE></pre><BR> 74<h2>Internal Operation</h2> 75<p> 76This function calls the <CODE><A href="../../fs/file/FS_ReadFile.html">FS_ReadFile</A></CODE> function internally.<br><br> Note that when you use segment data that is dynamically set to be read from the archive, and call the <code><A href="MB_RegisterFile.html">MB_RegisterFile</A></code> function, only one internal thread is started automatically to access the archive. This thread exists until either the <CODE><A href="../common/MB_End.html">MB_End</a></CODE> or <CODE><A href="../common/MB_EndToIdle.html">MB_EndToIdle</a></CODE> function completes. The priority of this thread is 0 and it will sleep until there is a child group request for segment data, accessing the card at irregular intervals as necessary.<br> 77</p> 78<h2>See Also</h2> 79<p> 80<code><A href="../../fs/file/FS_ReadFile.html">FS_ReadFile</A><BR> <A href="../common/MB_End.html">MB_End</A><BR> <A href="../common/MB_EndToIdle.html">MB_EndToIdle</A><BR> <A href="MB_GetSegmentLength.html">MB_GetSegmentLength</A><BR> <A href="../mb_segment_buffer_min_const.html">MB_SEGMENT_BUFFER_MIN</A><BR> <A href="MB_RegisterFile.html">MB_RegisterFile</A></code> 81</P> 82<H2>Revision History</H2> 83<P> 842008/10/02 Revised part of the sample code.<br>2005/04/11 Added description of task thread.<br /> 2004/12/07 Changed description because in the read delay method, the target has been extended from <code>NITRO-CARD</code> to any archive.<br /> 2004/11/11 Changed description to include the clone boot release and new read delay method.<br /> 2004/09/10 Added description of the operation when specifying NULL for the file pointer.<br /> 2004/08/09 Initial version. 85</P> 86<hr><p>CONFIDENTIAL</p></body> 87</html> 88
