mmioGetHeader
The mmioGetHeader function retrieves the media-specific header for an open file. This header provides critical information (such as sampling rate for audio or dimensions for images) required to interpret the media data correctly.
Syntax
#define INCL_MMIOOS2 #include <os2.h> ULONG mmioGetHeader(HMMIO hmmio, PVOID pHeader, LONG lHeaderLength, PLONG plBytesRead, ULONG ulReserved, ULONG ulFlags);
Parameters
- pHeader (PVOID) - input
- A pointer to a buffer to receive the header structure. The format of the returned data depends on whether header translation is active:
- Translated Header: If `MMIO_TRANSLATEHEADER` was specified during `mmioOpen`, the IOProc converts the file's native header into a standard OS/2 multimedia structure.
- Native Header: If `MMIO_NOTRANSLATE` was used (default), the raw header exactly as it appears in the file is returned.
- lHeaderLength (LONG) - input
- The size, in bytes, of the buffer pointed to by pHeader.
- plBytesRead (PLONG) - in/out
- A pointer to a LONG that receives the actual number of bytes copied into the header buffer.
- ulReserved (ULONG) - input
- Reserved for future use. Must be set to 0.
- ulFlags (ULONG) - input
- Reserved for future use. Must be set to 0.
Return Values
- rc (ULONG)
- Returns a code indicating the result:
- MMIO_SUCCESS: The function succeeded (0).
- MMIO_ERROR: The file is not a supported media-file format.
- MMIOERR_INVALID_PARAMETER: An invalid parameter was passed.
- MMIOERR_INTERNAL_SYSTEM: An internal system error occurred.
- MMIOERR_SEEK_FAILED: A seek operation failed during header retrieval.
Header Structures by Media Type
When translation is enabled, the buffer should point to the appropriate structure based on the file's media type:
| Media Type (ulMediaType) | Header Structure |
|---|---|
| MMIO_MEDIATYPE_IMAGE | MMIMAGEHEADER |
| MMIO_MEDIATYPE_AUDIO | MMAUDIOHEADER |
| MMIO_MEDIATYPE_MIDI | MMMIDIHEADER |
| MMIO_MEDIATYPE_DIGITALVIDEO | MMVIDEOHEADER |
| MMIO_MEDIATYPE_MOVIE | MMMOVIEHEADER |
Remarks
It is highly recommended to call mmioGetHeader before calling mmioRead. Without the header information, the application cannot determine how to process the raw data bytes (e.g., bit depth, channels, or compression type).
mmioGetHeader does not change the current file position. It supports non-compound files and individual compound-file elements, but it cannot be called on a compound file container itself.
For movie files with multiple tracks, you can use mmioSet to select a specific track before calling mmioGetHeader to retrieve that specific track's information.
Example Code
The following example shows how to retrieve a translated audio header:
HMMIO hmmio;
MMAUDIOHEADER audioHeader;
LONG lBytesRead;
ULONG rc;
/* Assume hmmio was opened with MMIO_TRANSLATEHEADER */
rc = mmioGetHeader(hmmio,
&audioHeader,
sizeof(MMAUDIOHEADER),
&lBytesRead,
0, 0);
if (rc == MMIO_SUCCESS) {
/* The audioHeader structure now contains valid data */
/* e.g., audioHeader.mmXWAVHeader.WAVEHeader.usChannels */
}