mmioGetFormats

The mmioGetFormats function retrieves a list of all currently available I/O procedures (IOProcs) that match specific search criteria. This is used by applications to identify supported file formats and media types (such as audio, video, or images) registered in the system.

Syntax

#define INCL_MMIOOS2
#include <os2.h>

ULONG mmioGetFormats(PMMFORMATINFO pmmformatinfo, LONG lNumFormats, PVOID pFormatInfoList, PLONG plFormatsRead, ULONG ulReserved, ULONG ulFlags);

Parameters

pmmformatinfo (PMMFORMATINFO) - in/out

A pointer to an MMFORMATINFO structure used to define search criteria:

• If fccIOProc is set, the function searches for a specific I/O procedure.
• If ulMediaType is set (e.g., `MMIO_MEDIATYPE_AUDIO`), the function filters for formats of that type.
• If both are NULL, all installed I/O procedures are returned.

lNumFormats (LONG) - input

The maximum number of MMFORMATINFO structures that the pFormatInfoList buffer can hold.

pFormatInfoList (PVOID) - in/out

A pointer to a caller-allocated buffer. Upon success, this buffer is filled with an array of MMFORMATINFO structures matching the search criteria.

plFormatsRead (PLONG) - output

A pointer to a LONG that receives the actual number of structures copied into the 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: A general system error occurred.
• MMIOERR_INVALID_PARAMETER: An invalid parameter was passed.
• MMIOERR_INTERNAL_SYSTEM: An internal system error occurred.

Remarks

To use this function effectively, applications typically follow these steps:

1. Call mmioQueryFormatCount to find out how many I/O procedures are currently installed.
2. Allocate a buffer by multiplying that count by `sizeof(MMFORMATINFO)`.
3. Call mmioGetFormats to populate the buffer with detailed information about each format.

This process is essential for building "Open File" dialogs that need to show a list of supported extensions and format descriptions.

Example Code

The following example demonstrates how to retrieve up to three registered audio formats:

   MMFORMATINFO mmformatinfo;
   MMFORMATINFO FormatList[3];
   LONG         lFormatsRead;
   ULONG        rc;

   /* Initialize criteria to search for Audio formats */
   memset(&mmformatinfo, '\0', sizeof(MMFORMATINFO));
   mmformatinfo.ulStructLen = sizeof(MMFORMATINFO);
   mmformatinfo.ulMediaType = MMIO_MEDIATYPE_AUDIO;

   rc = mmioGetFormats(&mmformatinfo,
                       3,               /* Max structures to return */
                       FormatList,      /* Buffer to fill */
                       &lFormatsRead,
                       0, 0);

   if (rc == MMIO_SUCCESS) {
       /* lFormatsRead contains the number of audio formats found (0 to 3) */
       /* FormatList[0].fccIOProc contains the FOURCC for the first format */
   }

Related Functions

• mmioQueryFormatCount
• mmioGetFormatName