DVDReadAsync

C Specification

#include <revolution/dvd.h>

typedef void (*DVDCallback)(s32 result, DVDFileInfo* fileInfo);

BOOL DVDReadAsync(DVDFileInfo* fileInfo, void* addr,
                  s32 length, s32 offset,
                  DVDCallback callback);

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 to start reading from. Must be a multiple of 4.
`callback`	Address of callback function that indicates read result.

Return Values

Always returns TRUE.

Description

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

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

By default, invalidating the data cache for the memory space is unnecessary. The DVDReadAsync function deletes the cache data inside the function. Programmers can change this default setting so that programs can decide if the cache should be invalidated. See the DVDSetAutoInvalidation function for details.

When the read completes, the callback function specified by callback is called unless NULL is specified. If read succeeds, the length to transfer returns as result (the first argument of this function) of the callback. If a fatal error occurs, DVD_RESULT_FATAL_ERROR is returned. If the read is canceled, DVD_RESULT_CANCELED is returned. DVD_RESULT_FATAL_ERROR and DVD_RESULT_CANCELED are both negative values. The second argument of callback is the DVDFileInfo structure that the file uses.

After calling the DVDReadAsync function, you can use two methods to determine if the file read has completed. Check that the callback function has been called or poll the DVDGetFileInfoStatus function.

You can call many asynchronous functions without waiting for previously issued functions to finish.

Issuing zero length reads is valid. In this case, the DVDReadAsync function only calls callback if callback is specified.

Caution: Do not reuse the same DVDFileInfo structure multiple times within the same read. The DVDFileInfo 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 simultaneously used multiple times, the system will become unreliable. A common symptom of this problem is that disc/drive errors will be incorrectly reported. See Optical Disc Drive Library (DVD) 4.3.2 for more details.

Revision History

2007/07/31 Revised the description.
2006/03/01 Initial version.