1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2<HTML> 3<HEAD> 4<META http-equiv="Content-Type" content="text/html; charset=windows-1252"> 5<META name="GENERATOR" content="IBM WebSphere Studio Homepage Builder Version 6.5.0.0 for Windows"> 6<META http-equiv="Content-Style-Type" content="text/css"> 7<LINK rel="stylesheet" type="text/css" href="../CSS/revolution.css"> 8<TITLE>DVDReadAsync</TITLE> 9</HEAD> 10<BODY> 11<H1>DVDReadAsync</H1> 12<H2>C Specification</H2> 13<DL> 14 <DD> 15<PRE><code>#include <revolution/dvd.h></CODE></PRE> 16 <DD> 17<PRE><CODE>typedef void (*DVDCallback)(s32 result, DVDFileInfo* fileInfo);</CODE></PRE> 18 <DD> 19<PRE><CODE>BOOL DVDReadAsync(DVDFileInfo* fileInfo, void* addr, 20 s32 length, s32 offset, 21 DVDCallback callback);</CODE></PRE> 22</DL> 23<H2>Arguments</H2> 24<TABLE border="1" cellpadding="3" cellspacing="0.1"> 25 <TBODY> 26 <TR> 27<TD width="120" bgcolor="#ffffe8"><EM><STRONG><CODE>fileInfo</CODE></STRONG></EM></TD> 28<TD width="520">File information retrieved by calling the <A href="DVDOpen.html"><CODE>DVDOpen</CODE></A> function.</TD> 29 </TR> 30 <TR> 31<TD width="120" bgcolor="#ffffe8"><EM><STRONG><CODE>addr</CODE></STRONG></EM></TD> 32<TD width="520">Buffer address. Must be 32-byte aligned.</TD> 33 </TR> 34 <TR> 35<TD width="120" bgcolor="#ffffe8"><EM><STRONG><CODE>length</CODE></STRONG></EM></TD> 36<TD width="520">Number of bytes to read. Must be a multiple of 32.</TD> 37 </TR> 38 <TR> 39<TD width="120" bgcolor="#ffffe8"><EM><STRONG><CODE>offset</CODE></STRONG></EM></TD> 40<TD width="520">File position to start reading from. Must be a multiple of 4.</TD> 41 </TR> 42 <TR> 43<TD width="120" bgcolor="#ffffe8"><EM><STRONG><CODE>callback</CODE></STRONG></EM></TD> 44<TD width="520">Address of callback function that indicates read result.</TD> 45 </TR> 46 </TBODY> 47</TABLE> 48<H2>Return Values</H2> 49<P>Always returns <CODE>TRUE</CODE>.</P> 50<H2>Description</H2> 51<P>Asynchronously reads data from a file. First opens the file with the <A href="DVDOpen.html"><CODE>DVDOpen</CODE></A> function.</P> 52<P>Programmers must prepare enough memory space for storing the file read.</P> 53<P>By default, invalidating the data cache for the memory space is unnecessary. The <code>DVDReadAsync</code> function deletes the cache data inside the function. Programmers can change this default setting so that programs can decide if the cache should be invalidated. See the <a href="DVDSetAutoInvalidation.html"><code>DVDSetAutoInvalidation</code></a> function for details.</P> 54<P>When the read completes, the callback function specified by <STRONG><em><code>callback</code></em></STRONG> is called unless NULL is specified. If read succeeds, the length to transfer returns as <EM><CODE><STRONG>result</STRONG></CODE></EM> (the first argument of this function) of the <EM><CODE><STRONG>callback</STRONG></CODE></EM>. If a fatal error occurs, <CODE>DVD_RESULT_FATAL_ERROR</CODE> is returned. If the read is canceled, <CODE>DVD_RESULT_CANCELED</CODE> is returned. <CODE>DVD_RESULT_FATAL_ERROR</CODE> and <CODE>DVD_RESULT_CANCELED</CODE> are both negative values. The second argument of <STRONG><em><code>callback</code></em></STRONG> is the <CODE>DVDFileInfo</CODE> structure that the file uses.</P> 55<P>After calling the <code>DVDReadAsync</code> function, you can use two methods to determine if the file read has completed. Check that the <STRONG><em><code>callback</code></em></STRONG> function has been called or poll the <code><a href="DVDGetFileInfoStatus.html">DVDGetFileInfoStatus</a></code> function.</P> 56<P>You can call many asynchronous functions without waiting for previously issued functions to finish.</P> 57<p>Issuing zero length reads is valid. In this case, the <code>DVDReadAsync</code> function only calls <STRONG><i><code>callback</code></i></STRONG> if <STRONG><i><code>callback</code></i></STRONG> is specified.</p> 58<P><B><I>Caution: </I></B> Do not reuse the same <code>DVDFileInfo</code> structure multiple times within the same read. The <code>DVDFileInfo</code> must be used exclusively for each read request. The structure is used internally to schedule the read and track the read progress. If the same structure is simultaneously used multiple times, the system will become unreliable. A common symptom of this problem is that disc/drive errors will be incorrectly reported. See <EM>Optical Disc Drive Library (DVD) 4.3.2</EM> for more details.</P> 59<H2>See Also</H2> 60<P><CODE><A href="DVDOpen.html">DVDOpen</A><BR> <A href="DVDRead.html">DVDRead</A><BR> <A href="DVDGetLength.html">DVDGetLength</A><BR> <A href="DVDGetFileInfoStatus.html">DVDGetFileInfoStatus</A><BR> <A href="DVDSetAutoInvalidation.html">DVDSetAutoInvalidation</A></CODE><BR> <CODE><A href="DVDCancel.html">DVDCancel(Async)</A><BR> <A href="DVDCancelAll.html">DVDCancelAll(Async)</A></CODE></P> 61<H2>Revision History</H2> 62<P>2007/07/31 Revised the description.<BR>2006/03/01 Initial version.</P> 63<hr><p>CONFIDENTIAL</p></body> 64</HTML> 65