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 6.5.0.0 for Windows"> 7<META http-equiv="Content-Style-Type" content="text/css"> 8<LINK rel="stylesheet" type="text/css" href="../CSS/revolution.css"> 9<title>DVDChangeDisk</title> 10</head> 11 12<body> 13 14<h1>DVDChangeDisk</h1> 15 16 17<h2>C Specification</h2> 18 19<dl> 20<dd><pre><code>#include <revolution/dvd.h></code></pre> 21 </dd> 22<dd><pre><CODE>typedef void (*DVDCBCallback)(s32 result, <a href="DVDCommandBlock.html">DVDCommandBlock</a>* block);</CODE></pre> 23 </dd> 24<dd><pre><CODE>s32 DVDChangeDisk(<a href="DVDCommandBlock.html">DVDCommandBlock</a>* block, DVDDiskID* id);</CODE></pre> 25 </dd> 26<dd><pre><CODE>BOOL DVDChangeDiskAsync(<a href="DVDCommandBlock.html">DVDCommandBlock</a>* block, DVDDiskID* id, 27 DVDCBCallback callback);</CODE></pre> 28 </dd> 29</dl> 30<h2>Arguments</h2> 31<TABLE border="1" cellpadding="3" cellspacing="0.1"> 32 <tr> 33<TD width="120" bgcolor="#ffffe8"><code><em><strong>block</strong></em></code></TD> 34<TD width="520">Command block of this command.</TD> 35 </tr> 36 <tr> 37<TD width="120" bgcolor="#ffffe8"><code><em><strong>id</strong></em></code></TD> 38<TD width="520">Pointer to disc ID.</TD> 39 </tr> 40 <tr> 41<TD width="120" bgcolor="#ffffe8"><code><em><strong>callback</strong></em></code></TD> 42<TD width="520">Callback function that indicates completion. (Only for <code>DVDChangeDiskAsync</code>.)</TD> 43 </tr> 44 </TABLE> 45<h2>Return Values</h2> 46<P><code>DVDChangeDisk</code>: Returns <CODE>0</CODE> if the command completes normally; otherwise, returns a negative value.</P> 47<P><code>DVDChangeDiskAsync</code>: Returns <CODE>TRUE</CODE> if the command terminates normally; otherwise, returns <CODE>FALSE</CODE>. </P> 48<h2>Description</h2> 49<P>The <code>DVDChangeDiskAsync</code> function waits for the game player to insert the Game Disc that has the matching <i><code>id</code></i>. </P> 50<P>After the read finishes, the <em><code><STRONG>callback</STRONG></code></em> function is called (unless <CODE>NULL</CODE> is specified for <em><code><STRONG>callback</STRONG></code></em>). When the Game Disc is successfully changed, zero is returned as the first argument <em><code><STRONG>result</STRONG></code></em> of the <em><code><STRONG>callback</STRONG></code></em> function. If a fatal error occurs, <code>DVD_RESULT_FATAL_ERROR</code> is returned. If the function 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 the <em><code><STRONG>callback</STRONG></code></em> function is the <code><a href="DVDCommandBlock.html">DVDCommandBlock</a></code> structure--the same structure passed to the <code>DVDChangeDiskAsync</code> function when it is called.</P> 51<P>After calling the <code>DVDChangeDiskAsync</code> function, there are two methods to determine if the Game Disc change is completed. One is to check that the <em><code><STRONG>callback</STRONG></code></em> function was called. The other is to poll with the <code><a href="DVDGetDriveStatus.html">DVDGetDriveStatus</a></code> function and wait until the <code><a href="DVDGetDriveStatus.html">DVDGetDriveStatus</a></code> function returns <code>DVD_STATE_END</code>.</P> 52<P>The <code>DVDChangeDisk</code> function is a synchronous version of the <code>DVDChangeDiskAsync</code> function.</P> 53<P><B>Note:</B> Take care if you are considering the use of synchronous functions in a real game program; use synchronous functions if the game program is multithreaded. In single threaded games, synchronous functions can't be used because there is no method for error checking.</P> 54 55<p>The <CODE>DVDChangeDisk</CODE> function may put the current thread to sleep. Refer to <a href="../os/Interrupt/intro.html">Interrupts and Callback Functions</a>.</p> 56 57<h2>See Also</h2> 58 59<p><code><a href="DVDGenerateDiskID.html">DVDGenerateDiskID</a></code><BR> <a href="../os/Interrupt/intro.html">Interrupts and Callback Functions</a></p> 60<H2>Revision History</H2> 61<P>2007/09/25 Added explanation on thread behavior.<BR> 2006/03/01 Initial version.</P> 62<hr><p>CONFIDENTIAL</p></body> 63</html>