DevHlp ReadFileAt

DevHlp_ReadFileAt is used by base device drivers to read a file previously opened using DevHlp_OpenFile from a specified file location.

This devhlp is used to read from a file opened with DevHlp_OpenFile, in contrast to a normal read, a start position can be specified.

C
 DevHelp_FileReadAt (PFILEIOINFO pFileReadAt) 

Assembler
Calling Sequence in Assembler  LES DI, ReadFileAt MOV DL, DevHlp_ReadFileAt

CALL [Device_Help] 

C
Pointer to the FILEIOINFO structure defined as follows  typedef struct FOPEN { PSZ FileName; /* (input) pointer to file name */ ULONG FileSize; /* (output) size of file returned by FileOpen */ } FILEOPEN;

typedef struct FCLOSE { USHORT reserved /* reserved */ } FILECLOSE;

typedef struct FREAD { PBYTE Buffer; /* (input) pointer to input buffer */ ULONG ReadSize; /* (input) number of bytes to read from file */ } FILEREAD;

typedef struct FREADAT { PBYTE Buffer; /* (input) pointer to input buffer */ ULONG ReadSize; /* (input) number of bytes to read from file */ ULONG StartPosition /* (input) starting file position relative to the beginning of the file */ } FILEREADAT;

typedef union FILEIOOP { struct FOPEN FileOpen; struct FCLOSE FileClose; struct FREAD FileRead; struct FREADAT FileReadAt; } FILEIOOP;

typedef struc _DDFileIo { USHORT Length; /* (input) length of imbedded structure */ FILEIOOP Data; /* (input) imbedded file system operation structure */ } FILEIOINFO, FAR * PFILEIOINFO 

Assembler
ES DI points to a FILEIOINFO structure defined as follows  FILEIOINFO struc length        dw        12    ; length of embedded file system operation structure / length of structure (must be 12) FREADAT struc Buffer        dd        ? ; 1616 pointer to input buffer / 16:16 address of a read buffer Readsize      dd        ? ; length of data to read / number of bytes to read StartPosition dd        ? ; starting position relative to the beginning of the file / starting position of read relative to FREADAT ends FILEIOINFO ends 

C

 * Success Indicator 0 if file was read.
 * 24 ERROR_BAD_LENGTH Length in the FILEIOINFO structure is invalid.

Assembler
Possible errors
 * C Clear if file is closed. AX = zero.
 * C Set if error. AX = Error code.
 * 24 ERROR_BAD_LENGTH The length in the FILEIOINFO structure is invalid.

Remarks
DevHlp_ReadFileAt may be called at initialization time only. It provides a primitive interface to the mini-IFS or micro_IFS at initialization time.

The current file position is set according to the StartPosition. The file is read from that file position. After a successful read, the current file position is updated.

Using this interface, one file only may be opened at a time. No handle is assigned by open. The file read is assumed to be the most recent opened using DevHlp_OpenFile.

Restrictions
Valid at INIT time only. Although the size argument of the data structure implies, I'd recommend to better not read more than 32K at a time. Note that the buffer itself is segmented, so DMA overrun and other effects might apply, depending on the quality of the miniIFS in use.

Bugs
In Holget Veit's opinion the length of structure should be 14, not 12.

C

 * 1) include "dhcalls.h"

USHORT APIENTRY DevHelp_FileReadAt (PFILEIOINFO pFileReadAt) 