mmioSetHeader

The mmioSetHeader function sets the attributes of the media in a file opened for writing by mmioOpen. It issues an MMIOM_SETHEADER message to the I/O procedure.

The specific header used depends on the media type of the file and the current track setting. This function does not change the current file position. Typically, mmioGetHeader is issued first to obtain the current attribute data, which is then updated and sent back via **mmioSetHeader**.

Syntax

#define INCL_MMIOOS2
#include <os2.h>

ULONG mmioSetHeader(HMMIO hmmio, PVOID pHeader, LONG lHeaderLength, PLONG plBytesWritten, ULONG ulReserved, ULONG ulFlags);

Parameters

hmmio (HMMIO) - input: The open file handle returned by mmioOpen.

pHeader (PVOID) - input

Pointer to a header structure containing the data to be written. The expected structure depends on whether translation is enabled:

**Translated Header**: If `MMIO_TRANSLATEHEADER` was set in the ulTranslate field of MMIOINFO during mmioOpen, the structure should match the standard presentation format for that media type.
**Native Header**: If `MMIO_NOTRANSLATE` was specified (default), the header is in its native format.

Common media types and their structures include:

MMIO_MEDIATYPE_IMAGE: MMIMAGEHEADER
MMIO_MEDIATYPE_AUDIO: MMAUDIOHEADER
MMIO_MEDIATYPE_MIDI: MMMIDIHEADER
MMIO_MEDIATYPE_DIGITALVIDEO: MMVIDEOHEADER
MMIO_MEDIATYPE_MOVIE: MMMOVIEHEADER

lHeaderLength (LONG) - input: The size of the header structure in bytes.

plBytesWritten (PLONG) - in/out: Returns the number of bytes successfully written to the header structure.

ulReserved (ULONG) - input: Reserved for future use; must be set to zero.

ulFlags (ULONG) - input: Reserved for future use; must be set to zero.

Return Value

rc (ULONG) - returns

Return codes indicating success or type of failure:

MMIO_SUCCESS: Function succeeded (0).
MMIO_ERROR: The specified file is not a supported media-file format.
MMIOERR_INVALID_PARAMETER: An invalid parameter was passed.
MMIOERR_INVALID_HANDLE: The handle passed was not valid.
MMIOERR_SEEK_FAILED: A seek operation failed prior to writing.

Remarks

The contents of the header must represent the structure expected by the I/O procedure. Because the I/O procedure may translate or transpose data before saving it to disk, the value returned in plBytesWritten might differ from the actual physical bytes written to the file.

For multiple track movie files, this function can be used in conjunction with mmioSet to write a header for a specific track.

Example Code

The following code illustrates how to update header attributes for an audio file.

   HMMIO          hmmio1;
   MMAUDIOHEADER  mmAudioHeader;
   LONG           lBytesWritten;
   ULONG          ulReserved = 0L;
   ULONG          ulFlags = 0L;
   ULONG          rc;
    ...

   /* Initialize header structure to zeros */
   memset(&mmAudioHeader, '\0', sizeof(MMAUDIOHEADER));

   /* Populate mmAudioHeader fields here... */

   rc = mmioSetHeader(hmmio1,
                      (PVOID)&mmAudioHeader,
                      (LONG)sizeof(MMAUDIOHEADER),
                      &lBytesWritten,
                      ulReserved,
                      ulFlags);

   if (rc)
   {
      /* Error handling */
   }
   else
   {
      /* Header successfully updated */
   }
    ...

Related Functions