mmioGetFormatName
The mmioGetFormatName function retrieves the descriptive, human-readable name of the media format supported by a specific I/O procedure (IOProc).
Syntax
#define INCL_MMIOOS2 #include <os2.h> ULONG mmioGetFormatName(PMMFORMATINFO pmmformatinfo, PSZ pszFormatName, PLONG plBytesRead, ULONG ulReserved, ULONG ulFlags);
Parameters
- pmmformatinfo (PMMFORMATINFO) - input
- A pointer to an MMFORMATINFO structure. The caller must initialize the following fields:
- fccIOProc: The FOURCC code of the I/O procedure to query.
- lNameLength: The maximum length (in bytes) of the buffer provided in pszFormatName.
- pszFormatName (PSZ) - output
- A pointer to the buffer that will receive the null-terminated descriptive string (e.g., "IBM Multimedia Bundle File"). The buffer should be at least `lNameLength + 1` in size.
- plBytesRead (PLONG) - output
- A pointer to a LONG variable that receives the actual number of bytes written to pszFormatName, representing the length of the string.
- ulReserved (ULONG) - input
- Reserved for future use. This value must be set to 0.
- ulFlags (ULONG) - input
- Reserved for future use. This value 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 failure occurred.
- MMIOERR_INVALID_PARAMETER: One or more parameters were invalid.
Remarks
Applications typically use this function after identifying a file via mmioIdentifyFile. If an application needs to display the format of a file to the user (for example, in a "File Information" dialog), mmioGetFormatName provides the specific string registered for that IOProc in the system's INI file.
Example Code
The following example demonstrates how to retrieve the name of the format associated with the bundle (BND) I/O procedure:
MMFORMATINFO mmFormatInfo;
CHAR szNameBuffer[41];
LONG lActualLength;
ULONG rc;
/* Initialize the format info structure */
memset(&mmFormatInfo, '\0', sizeof(MMFORMATINFO));
mmFormatInfo.ulStructLen = sizeof(MMFORMATINFO);
mmFormatInfo.fccIOProc = FOURCC_BND; /* Bundle file IOProc */
mmFormatInfo.lNameLength = 40; /* Max length to copy */
rc = mmioGetFormatName(&mmFormatInfo,
szNameBuffer,
&lActualLength,
0, 0);
if (rc == MMIO_SUCCESS) {
/* szNameBuffer now contains "IBM Multimedia Bundle File" */
/* lActualLength contains the length of the string */
} else {
/* Handle error */
}