Byte-Stream File Access

A set of function calls in the File folio eases the job of accessing the contents of a file in a byte-by-byte fashion, rather than in the block-by-block mode supported by the file driver interface. These functions include:

With these functions, a program can read an arbitrary number of bytes from anywhere within a file, without worrying about block boundaries.

Opening a File

Before you can read a file's data using the streaming routines, you must open the file:

Stream *OpenDiskStream( char *theName, int32 bSize )
OpenDiskStream() opens the file identified by an absolute or relative pathname, allocates the specified amount of buffer space, and initiates an asynchronous read to fill the buffer with the first portion of the file's data. It returns NULL if any of these functions cannot be performed for any reason.

Reading the Data

To read data from a stream file, you must call ReadDiskStream()

int32 ReadDiskStream( Stream *theStream, char *buffer, int32 nBytes )
ReadDiskStream() reads data from the given stream file starting at the current position within the file. The data is put into the supplied buffer. The number of bytes actually read from the file is returned. The position within the file is advanced by the number of bytes read, so that the next time ReadDiskStream() is called, the data that follows is read.

Setting Up the Read Position

To change the current position within a stream file, you must call:

SeekDiskStream( Stream *thream, int32 offset, enum SeekOrigin whence )
After you call SeekDiskStream(), data transfers start with the first byte at the new file position. The whence argument specifies whether the operation is relative to either the beginning or end of the file, or to the current position in the file. The offset argument specifies the number of bytes offset relative to the whence position. It returns the actual absolute file position that results from the seek position or a negative error code if unsuccessful.

The offset can be specified in any of three ways: absolute (positive) byte offset from the beginning of file (SEEK_SET), relative byte offset from the current position in the file (SEEK_CUR), or absolute (negative) byte offset from the end of the file (SEEK_END).

Cleaning Up

CloseDiskStream() closes the stream's file, deallocates the buffer memory, and releases the stream structure.

void CloseDiskStream(Stream *theStream);