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
13<H2>Syntax</H2>
14<dl><dd><pre class="construction">
15#include &lt;revolution/dvd.h&gt;
16
17typedef void (*DVDCallback)(s32 result, DVDFileInfo* fileInfo);
18
19BOOL DVDReadAsync(DVDFileInfo* fileInfo, void* addr,
20                  s32 length, s32 offset,
21                  DVDCallback callback);
22</pre></dd></dl>
23
24<H2>Arguments</H2>
25<TABLE class="arguments" border="1" >
26  <TBODY>
27    <TR>
28<TH>fileInfo</TH>
29<TD>Information about the file associated by calling the <A href="DVDOpen.html"><CODE>DVDOpen</CODE></A> function beforehand.</TD>
30    </TR>
31    <TR>
32<TH>addr</TH>
33<TD>Buffer address. Must be 32-byte aligned.</TD>
34    </TR>
35    <TR>
36<TH>length</TH>
37<TD>Number of bytes to read. Must be a multiple of 32.</TD>
38    </TR>
39    <TR>
40<TH>offset</TH>
41<TD>File position to start reading from. Must be a multiple of 4.</TD>
42    </TR>
43    <TR>
44<TH>callback</TH>
45<TD>Address of callback function that indicates read result.</TD>
46    </TR>
47  </TBODY>
48</TABLE>
49
50<H2>Return Values</H2>
51<P>Always returns <CODE>TRUE</CODE>.</P>
52
53<H2>Description</H2>
54<P>Asynchronously reads data from a file. First opens the file with the <A href="DVDOpen.html"><CODE>DVDOpen</CODE></A> function.</P>
55<P>Programmers must prepare enough memory space for storing the file read.</P>
56<P>By default, invalidating the data cache for the memory space is unnecessary. The <CODE>DVDReadAsync</CODE> function internally invalidates the data in the cache. Programmers can change this default setting so that programs can decide if the cache should be invalidated. For more detail, see the <A href="DVDSetAutoInvalidation.html"><CODE>DVDSetAutoInvalidation</CODE></A> function.</P>
57<P>When the read completes, the callback function specified by <SPAN class="argument">callback</SPAN> is called unless <CODE>NULL</CODE> is specified. If read succeeds, the length to be transferred returns as <SPAN class="argument">result</SPAN> (first argument of this function) of the <SPAN class="argument">callback</SPAN>. If a fatal error occurs, <CODE>DVD_RESULT_FATAL_ERROR</CODE> is returned. If the read is cancelled, <CODE>DVD_RESULT_CANCELED</CODE> is returned. Both <CODE>DVD_RESULT_FATAL_ERROR</CODE> and <CODE>DVD_RESULT_CANCELED</CODE> are negative values. The second argument of <SPAN class="argument">callback</SPAN> is the <CODE>DVDFileInfo</CODE> structure used by the file.</P>
58<P>After calling the <code>DVDReadAsync</code> function, you can use two methods to determine if the file read has completed. Check that the <SPAN class="argument">callback</SPAN> function has been called, or poll the <A href="DVDGetFileInfoStatus.html"><CODE>DVDGetFileInfoStatus</CODE></A> function.</P>
59<P>You can call many asynchronous functions without waiting for previously issued functions to finish.</P>
60<p>Issuing zero length reads is valid. In this case, the <code>DVDReadAsync</code> function only calls <SPAN class="argument">callback</SPAN> if <SPAN class="argument">callback</SPAN> is specified.</p>
61<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 used simultaneously multiple times, the system will become unreliable. A common symptom of this problem is that disc/drive errors will be incorrectly reported. For more details, see <EM>Optical Disc Drive Library (DVD) 4.3.2</EM>.</P>
62
63<H2>See Also</H2>
64<P class="reference">
65<A href="DVDOpen.html">DVDOpen</A>,
66<A href="DVDRead.html">DVDRead</A>,
67<A href="DVDGetLength.html">DVDGetLength</A>,
68<A href="DVDGetFileInfoStatus.html">DVDGetFileInfoStatus</A>,
69<A href="DVDSetAutoInvalidation.html">DVDSetAutoInvalidation</A>,
70<A href="DVDCancel.html">DVDCancel(Async)</A>,
71<A href="DVDCancelAll.html">DVDCancelAll(Async)</A>
72</P>
73
74<H2>Revision History</H2>
75<P>
762007/07/31 Revised explanation. <BR>2006/03/01 Initial version.<BR>
77</P>
78
79<hr><p>CONFIDENTIAL</p></body>
80</HTML>
81