DVDRead

C Specification

#include <revolution/dvd.h>

s32 DVDRead(DVDFileInfo* fileInfo, void* addr, s32 length, s32 offset);

Arguments

`fileInfo`	File information retrieved by calling the `DVDOpen` function.
`addr`	Buffer address. Must be 32-byte aligned.
`length`	Number of bytes to read. Must be a multiple of 32.
`offset`	File position from which to start reading. Must be a multiple of 4.

Return Values

Returns the number of bytes read if successful.

If a fatal error occurs during a read, the function returns DVD_RESULT_FATAL_ERROR. If the read is canceled, the function returns DVD_RESULT_CANCELED. DVD_RESULT_FATAL_ERROR and DVD_RESULT_CANCELED are both negative values.

Description

Asynchronously reads data from a file. First opens the file with the DVDOpen function.

DVDRead does not return until reading is completed. For example, if the disc is ejected during reading, the DVDRead function will wait internally until the disc is reinserted. In the meantime, other executable threads are executed, if there are any.

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

Programmers must prepare enough memory space for storing the file read.

By default, invalidating the data cache for the memory space is unnecessary. The DVDRead 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 DVDSetAutoInvalidation function.

Issuing zero length reads is valid. In this case, the DVDRead function does nothing and returns 0.

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

Revision History

2007/09/25 Added explanation on thread behavior.
2007/08/28 Revised the description.
2006/03/01 Initial version.