XACT_READFILE_CALLBACK

Title-defined function called by XACT to read data from disk.

typedef BOOL (__stdcall *XACT_READFILE_CALLBACK)(
    HANDLE hFile,
    LPVOID lpBuffer,
    DWORD nNumberOfBytesToRead,
    LPDWORD lpNumberOfBytesRead,
    LPOVERLAPPED lpOverlapped
);

Parameters

hFile

Handle to the file to be read.

lpBuffer

Pointer to the buffer to contain the data read from the file.

nNumberOfBytesToRead

Number of bytes to be read from the file.

lpNumberOfBytesRead

Pointer to the variable that receives the number of bytes read.

lpOverlapped

Pointer to an OVERLAPPED structure. This structure is required if hFile was created with FILE_FLAG_OVERLAPPED.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

This function is analogous to the system ReadFile function. When reading data from disk, the XACT engine calls the title's read file callback instead of the system ReadFile function. The advantage of registering a callback is that the title can manage XACT's disk input to prioritize it along with the game's other I/O.

The simplest implementation of this callback function is to call ReadFile and return its return value, but doing so provides no benefit. The title will want to extend or modify read behavior when registering this callback.

ReadFile sets the lpNumberOfBytesRead variable to zero before doing any work or error checking, so the title callback should do the same.

XACT makes extensive use of the HasOverlappedIoCompleted macro, which references the Internal member of the OVERLAPPED structure passed in lpOverlapped. Titles must properly set this flag to indicate the status of the overlapped operation. The HasOverlappedIoCompleted macro is defined as follows:

#define HasOverlappedIoCompleted( lpOverlapped ) ( (lpOverlapped)->Internal != STATUS_PENDING )

Requirements

Header: Declared in Xact.h.

See Also

XACT Callbacks