I/O Buffer Control Functions

The Multimedia file I/O services also include some functions giving you more control over the file I/O buffer. Using the following functions, you can force the contents of an I/O buffer to be written to disk, enable buffered I/O on a file opened for unbuffered I/O, change the size of an I/O buffer, and supply your own I/O buffer:

mmioFlush

Writes the contents of the I/O buffer to disk.

mmioSetBuffer

Changes the size of the I/O buffer, and allows applications to supply their own buffer.

Flushing an I/O Buffer

Flushing an I/O buffer means writing the contents of the buffer to disk. You don't have to call mmioFlush to flush an I/O buffer—the buffer is automatically flushed when you close a file using mmioClose. If you don't close a file immediately after writing to it, you should flush the buffer to ensure the information is written to disk.

Note:

If you run out of disk space, mmioFlush might fail, even if the preceding mmioWrite calls were successful. Similarly, mmioClose might fail when it is flushing its I/O buffer.

Changing the Size of the Internal I/O Buffer

The default size of the internal I/O buffer is 8K. If this size is not adequate, you can use mmioSetBuffer to change the size of the buffer. You can also use mmioSetBuffer to enable buffering on a file opened for unbuffered I/O. The mmioSetBuffer function has the following syntax:

WORD mmioSetBuffer(hmmio, pchBuffer, cchBuffer, wFlags)

The hmmio parameter specifies the file handle for the file associated with the buffer.

The pchBuffer parameter specifies a pointer to a user-supplied buffer. For an internal buffer, set this parameter to NULL.

The cchBuffer parameter specifies the size of the buffer.

The wFlags parameter is unused and should be zero.

The return value is zero if the function is successful; otherwise, the return value specifies an error code.

Summary: Changing the I/O Buffer Size

For example, the following code fragment opens a file named “SAMPLE.TXT” for unbuffered I/O, and then enables buffered I/O with an internal 16K buffer:

HMMIO hFile;
.
.
.
if ((hFile = mmioOpen("SAMPLE.TXT", NULL, MMIO_READ)) != NULL) {
        /* File opened successfully; request an I/O buffer */
        if (mmioSetBuffer(hFile, NULL, 16384L, 0))
                /* Buffer cannot be allocated */
        else
                /* Buffer allocated successfully */
}

else
        /* File cannot be opened */

Supplying Your Own I/O Buffer

You can also use mmioSetBuffer to supply your own buffer for use as a memory file. For details on using memory files, see “Performing File I/O on Memory Files,” later in this chapter.