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.

Syntax

C

DevHelp_FileReadAt (PFILEIOINFO pFileReadAt)

Assembler

Calling Sequence in Assembler

LES DI, ReadFileAt
MOV DL, DevHlp_ReadFileAt

CALL [Device_Help]

Parameters

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

Return Code

C

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

Assembler

• C Clear if file is closed. AX = zero.
• C Set if error. AX = Error code.

Possible errors

• 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.

Example Code

C

#include "dhcalls.h"

USHORT APIENTRY DevHelp_FileReadAt (PFILEIOINFO pFileReadAt)