AsyncLoadFile

Starts loading a file asynchronously.

Synopsis

Err AsyncLoadFile (char *fname, LoadFileInfo *lf)

Description

Starts loading the specified file asynchronously, using the options in the LoadFileInfo structure.

The function opens the file, gets status information like filesize, then starts the I/O process. Upon successful return from this function you can refer to the buffer, bufSize, and bf (BlockFileInfo) fields of the LoadFileInfo structure, even while the I/O is still in progress. The contents of the buffer are, of course, indeterminate until the I/O process completes.

The LoadFileInfo structure is defined in blockfile.h. It contains values that control the load operation. If the buffer pointer in the structure is NULL, a buffer is allocated for you. If the buffer pointer is non-NULL, it is a pointer to a buffer you allocated for the file. If the ioDonePort value in the structure is non-zero, the I/O is set up to notify you via message when the load completes.

If you store a NULL buffer pointer into the LoadFileInfo structure and allow this function to allocate a buffer for you, use the UnloadFile() function to release the buffer when you no longer need its contents.

You must eventually follow a call to this function with a call to either AbortAsyncLoadFile(), WaitAsyncLoadFile(), or FinishAsyncLoadFile().

Arguments

fname: Name of the file to load.

lf: Pointer to a LoadFileInfo structure which describes the buffer and file characteristics.

Return Value

Returns zero on success or a negative error code.

Implementation

Library call implemented in lib3do.lib.

Associated Files

lib3do.lib, blockfile.h