DVDChangeDisk

C Specification

#include <revolution/dvd.h>

typedef void (*DVDCBCallback)(s32 result, DVDCommandBlock* block);

s32 DVDChangeDisk(DVDCommandBlock* block, DVDDiskID* id);

BOOL DVDChangeDiskAsync(DVDCommandBlock* block, DVDDiskID* id,
                        DVDCBCallback callback);

Arguments

`block`	Command block of this command.
`id`	Pointer to disc ID.
`callback`	Callback function that indicates completion. (Only for `DVDChangeDiskAsync`.)

Return Values

DVDChangeDisk: Returns 0 if the command completes normally; otherwise, returns a negative value.

DVDChangeDiskAsync: Returns TRUE if the command terminates normally; otherwise, returns FALSE.

Description

The DVDChangeDiskAsync function waits for the game player to insert the Game Disc that has the matching id.

After the read finishes, the callback function is called (unless NULL is specified for callback). When the Game Disc is successfully changed, zero is returned as the first argument result of the callback function. If a fatal error occurs, DVD_RESULT_FATAL_ERROR is returned. If the function is canceled, DVD_RESULT_CANCELED is returned. DVD_RESULT_FATAL_ERROR and DVD_RESULT_CANCELED are both negative values. The second argument of the callback function is the DVDCommandBlock structure--the same structure passed to the DVDChangeDiskAsync function when it is called.

After calling the DVDChangeDiskAsync function, there are two methods to determine if the Game Disc change is completed. One is to check that the callback function was called. The other is to poll with the DVDGetDriveStatus function and wait until the DVDGetDriveStatus function returns DVD_STATE_END.

The DVDChangeDisk function is a synchronous version of the DVDChangeDiskAsync function.

Note: 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.

The DVDChangeDisk function may put the current thread to sleep. Refer to Interrupts and Callback Functions.

Revision History

2007/09/25 Added explanation on thread behavior.
2006/03/01 Initial version.