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>DVDRead</TITLE> 9</HEAD> 10<BODY> 11<H1>DVDRead</H1> 12<H2>C Specification</H2> 13<DL> 14 <DD> 15<PRE><code>#include <revolution/dvd.h></CODE></PRE> 16 <DD> 17<PRE><CODE>s32 DVDRead(DVDFileInfo* fileInfo, void* addr, s32 length, s32 offset);</CODE></PRE> 18</DL> 19<H2>Arguments</H2> 20<TABLE border="1" cellpadding="3" cellspacing="0.1"> 21 <TBODY> 22 <TR> 23<TD width="120" bgcolor="#ffffe8"><EM><STRONG><CODE>fileInfo</CODE></STRONG></EM></TD> 24<TD width="520">File information retrieved by calling the <A href="DVDOpen.html"><CODE>DVDOpen</CODE></A> function.</TD> 25 </TR> 26 <TR> 27<TD width="120" bgcolor="#ffffe8"><EM><STRONG><CODE>addr</CODE></STRONG></EM></TD> 28<TD width="520">Buffer address. Must be 32-byte aligned.</TD> 29 </TR> 30 <TR> 31<TD width="120" bgcolor="#ffffe8"><EM><STRONG><CODE>length</CODE></STRONG></EM></TD> 32<TD width="520">Number of bytes to read. Must be a multiple of 32.</TD> 33 </TR> 34 <TR> 35<TD width="120" bgcolor="#ffffe8"><EM><STRONG><CODE>offset</CODE></STRONG></EM></TD> 36<TD width="520">File position from which to start reading. Must be a multiple of 4.</TD> 37 </TR> 38 </TBODY> 39</TABLE> 40<H2>Return Values</H2> 41<P>Returns the number of bytes read if successful.</P> 42<P>If a fatal error occurs during a read, the function returns <FONT face="Courier New">DVD_RESULT_FATAL_ERROR</FONT>. If the read is canceled, the function returns <FONT face="Courier New">DVD_RESULT_CANCELED</FONT>. <CODE>DVD_RESULT_FATAL_ERROR</CODE> and <CODE>DVD_RESULT_CANCELED</CODE> are both negative values.</P> 43<H2>Description</H2> 44<P>Asynchronously reads data from a file. First opens the file with the <A href="DVDOpen.html"><CODE>DVDOpen</CODE></A> function.</P> 45<P><CODE>DVDRead</CODE> does not return until reading is completed. For example, if the disc is ejected during reading, the <CODE>DVDRead</CODE> function will wait internally until the disc is reinserted. In the meantime, other executable threads are executed, if there are any.</P> 46<P><strong><B>Note:</B></strong> Please be careful if you are considering to use a synchronous function in a real game; Synchronous functions can only be used in a multithreaded game. In single thread games, synchronous functions can't be used because there is no way to check errors.</P> 47 48<P>Programmers must prepare enough memory space for storing the file read.</P> 49<P>By default, invalidating the data cache for the memory space is unnecessary. The <code>DVDRead</code> function deletes the data in the cache from within the function. 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> 50 51<p>Issuing zero length reads is valid. In this case, the <code>DVDRead</code> function does nothing and returns 0.</p> 52 53<p>This function may put the current thread to sleep. Refer to <a href="../os/Interrupt/intro.html">Interrupts and Callback Functions</a>.</p> 54 55<H2>See Also</H2> 56<P><CODE><A href="DVDOpen.html">DVDOpen</A><BR> <A href="DVDReadAsync.html">DVDReadAsync</A><BR> <A href="DVDGetLength.html">DVDGetLength</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><BR> <a href="../os/Interrupt/intro.html">Interrupts and Callback Functions</a></P> 57<H2>Revision History</H2> 58<P>2007/09/25 Added explanation on thread behavior.<BR> 2007/08/28 Revised the description.<BR>2006/03/01 Initial version.</P> 59<hr><p>CONFIDENTIAL</p></body> 60</HTML> 61