XACT_READFILE_CALLBACK

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