mmioWrite
The mmioWrite function writes data to a file that was opened using mmioOpen.
Syntax
#define INCL_MMIOOS2 #include <os2.h> LONG mmioWrite(HMMIO hmmio, PCHAR pchBuffer, LONG cBytes);
Parameters
- pchBuffer (PCHAR) - input
- A pointer to the buffer containing the data to be written.
- cBytes (LONG) - input
- The number of bytes to write from the pchBuffer to the file.
Return Value
- rc (LONG) - returns
- Returns the number of bytes actually written. If an error occurs, `MMIO_ERROR` is returned. A call to mmioGetLastError might return one of the following error codes:
- MMIOERR_READ_ONLY_FILE: File not opened in a write-compatible mode.
- MMIOERR_INVALID_HANDLE: Invalid handle specified.
- MMIOERR_WRITE_FAILED: Unable to write; probable hardware error.
- MMIOERR_SEEK_FAILED: Unable to seek; probable hardware error.
- MMIOERR_READ_FAILED: Unable to read; probable hardware error.
- MMIOERR_INVALID_BUFFER_LENGTH: The buffer length is invalid.
- MMIOERR_NO_BUFFER_ALLOCATED: A buffer was expected but none was found.
- MMIOERR_CANNOTWRITE: The target media has no space available.
Remarks
The behavior of **mmioWrite** varies depending on the type of file being accessed:
- Memory Files (MEM): For a memory file that cannot expand, the function might write fewer bytes than requested if the end of the buffer is reached. If the file pointer is already past the EOF, `MMIO_ERROR` is returned. If the file is expandable (system-allocated), it will grow to accommodate the requested bytes.
- Compound Files: Elements of a compound file behave similarly to memory files. They can be expanded if opened with the `MMIO_APPEND` flag.
- Translated Data: If the `MMIO_TRANSLATEDATA` flag was used during mmioOpen, the I/O procedure expects data in the standard presentation format (e.g., uncompressed PCM for audio or OS/2 2.0 bitmap for images). The I/O procedure translates this into the file's specific format before writing.
> Note: User-supplied buffers cannot be expanded by the system, whereas system-allocated buffers can.
Example Code
The following code illustrates how to write data to an open MMIO file.
HMMIO hmmio1;
PCHAR pchBuffer;
LONG cBytes;
LONG lBytesWritten;
...
/* Assume pchBuffer is allocated and filled with cBytes of data */
lBytesWritten = mmioWrite(hmmio1, pchBuffer, cBytes);
if (lBytesWritten == MMIO_ERROR)
{
/* Error handling */
}
else if (lBytesWritten < cBytes)
{
/* Handle partial write (e.g., non-expandable memory file reached limit) */
}
...