Installing an I/O Procedure

Certain factors must be considered when installing an IOProc; for example, the number of processes that use the IOProc might help you decide which method you use to install an IOProc. Depending on the requirements of your application, you can choose to install an IOProc on a temporary, semipermanent, or permanent basis.

The following MMIO functions allow you to install an IOProc:

┌──────────────────────────────┬──────────────────────────────┐
│Function                      │Description                   │
├──────────────────────────────┼──────────────────────────────┤
│mmioOpen                      │Temporarily installs an I/O   │
│                              │procedure.                    │
├──────────────────────────────┼──────────────────────────────┤
│mmioInstallIOProc             │Adds, replaces, finds, or     │
│                              │removes an entry in the MMIO  │
│                              │IOProc table.                 │
├──────────────────────────────┼──────────────────────────────┤
│mmioIniFileHandler            │Adds, replaces, finds, or     │
│                              │removes an entry in the       │
│                              │initialization file           │
│                              │(MMPMMMIO.INI).               │
└──────────────────────────────┴──────────────────────────────┘

Temporary Installation Using mmioOpen

You can temporarily install an I/O procedure using mmioOpen. In this case, the IOProc is only used when a file opened by the MMIO Manager does not install the IOProc in the I/O procedure table.

To specify an I/O procedure when you open a file using mmioOpen, use the pmmioinfo parameter to reference an MMIOINFO structure as follows:

Load the DLL using the DosLoadModule and DosQueryProcAddr functions to install and obtain the procedure address of the IOProc as shown in the following code fragment.

strcpy( acMMIOProcName,
        acStringBuffer[ IDS_MMIO_INSTALLPROC_NAME - 1 ] );

ldosAPIRc =
  DosLoadModule(
   &acFailureNameBuffer[ 0 ],    /* Object name if failure occurs.  */
   FILE_NAME_SIZE,               /* Size of the name buffer.        */
   acStringBuffer[ IDS_MMIO_INSTALLPROC_DLL_NAME - 1 ], /* DLL Name.*/
   &hmModHandle );               /* Handle to the module.           */
     .
     .
     .

ldosAPIRc =
  DosQueryProcAddr(
   hmModHandle,                /* Handle to the DLL module.         */
   (ULONG) NULL,               /* NULL gives the entry point.       */
   acMMIOProcName,             /* Name of the Installable procedure.*/
   (PFN *) &pmmioprocIoProc ); /* Pointer to the Installable proc.  */

In the MMIOINFO structure passed to mmioOpen, store the procedure address of the IOProc type in the pIOProc field. Set the fccIOProc field to NULL.
Call mmioOpen to use the IOProc with a file, passing the MMIOINFO structure in as the second parameter. This sends a MMIOM_OPEN message to the temporary IOProc. (Note that this does not make the IOProc available for use with other files.)
Set all other fields to 0 (unless you are opening a memory file, or directly reading or writing to the file I/O buffer).

This strategy allows a file format IOProc to replace a default IOProc (such as the DOS IOProc), simply by using the address of a replacement custom routine.

Semipermanent Installation Using mmioInstallIOProc

You can install an IOProc during run-time from your application. This method is semipermanent because the IOProc can only be called while the process is active. When the process terminates, it is removed from the IOProc table. Once the DLL is removed from memory, the next loading of the MMIO DLL does not load this IOProc. Because this IOProc is installed by specifically calling mmioInstallIOProc, as shown in the following figure, the IOProc is available for any files opened within that process.

PMMIOPROC  pmmioprocSpecialIOProc; /* Pointer once IOProc                                      is installed.       */


 pmmioprocSpecialIOProc =
   mmioInstallIOProc(
    fccIOProc,          /* The identifier (FOURCC) of the procedure.*/
    pmmioprocIoProc,    /* Pointer to the installable procedure.    */
    MMIO_INSTALLPROC ); /* Flag to install the procedure.           */

The mmioInstallIOProc function maintains a separate list of installed I/O procedures for each OS/2 application that uses MMIO. This allows different applications to use the same I/O procedure identifier for different I/O procedures without causing conflict. When you install an I/O procedure using mmioInstallIOProc, the procedure remains installed until you remove it. The mmioInstallIOProc function does not prevent an application from installing two different I/O procedures with the same identifier, or installing an I/O procedure with the same identifier as a internal I/O procedure (DOS, MEM, or CF). When mmioInstallIOProc is called with the MMIO_REMOVEPROC flag set, as shown in the following code fragment, the most recently installed procedure is the first one to be removed.

PMMIOPROC  pmmioprocSpecialIOProc; /* Pointer once IOProc
                                      is installed.               */

 pmmioprocSpecialIOProc =
   mmioInstallIOProc(
     fccIOProc,               /* The identifier of the procedure. */
     pmmioprocIoProc,         /* Pointer to the Installable proc. */
     MMIO_REMOVEPROC );       /* Flag to deinstall the proc.      */

Permanent Installation Using mmioIniFileHandler

You can permanently install an IOProc in your system by identifying the IOProc in the initialization file (MMPMMMIO.INI) when you start your system. This method allows the IOProc to be used by any process because it is installed in the IOProc table for every process (like the internal I/O procedures). Therefore, a call to mmioInstallIOProc is not necessary every time the IOProc is needed.

The advantage of installing I/O procedures in the MMPMMMIO.INI file is to achieve application transparency; I/O procedures become built-in as soon as you restart your system. Note that the IOProc must be contained in a DLL file, although more than one IOProc can be contained in the DLL if necessary.

To permanently install an IOProc, an IOProc entry is added to the MMPMMMIO.INI file. This is accomplished by either writing an INI change control file or writing an application using the mmioIniFileHandler function with the MMIO_INSTALLPROC specified. The IOProc is installed in the IOProc table ahead of the MMIO default IOProcs (DOS, MEM, and CF).

The following code fragment is an example of how an application uses the mmioIniFileHandler function to permanently install the OS/2 1.3 PM bitmap image IOProc.

#define FOURCC_OS13   mmioFOURCC( 'O', 'S', '1', '3' )

#pragma linkage( mmioIniFileHandler, system )

void main ()
{
 ULONG   ul;
 MMINIFILEINFO  mminifileinfo;
 mminifileinfo.fccIOProc = FOURCC_OS13;
 strcpy (mminifileinfo.szDLLName, "OS13PROC");
 strcpy (mminifileinfo.szProcName, "OS13BITMAPIOPROC");
 mminifileinfo.ulExtendLen = 16L;
 mminifileinfo.ulFlags = 0L;
 mminifileinfo.ulMediaType = MMIO_MEDIA_IMAGE;
 mminifileinfo.ulIOProcType = MMIO_IOPROC_FILEFORMAT;
 strcpy (mmioinifileinfo.szDefExt, "");

 printf ("Installing OS/2 PM Bitmap (V1.3) IOProc\n");

 rc = mmioIniFileHandler (&mminifileinfo, MMIO_INSTALLPROC);
 switch (rc)
 {
 case MMIO_SUCCESS:
  printf ("Installing Complete\n");
  break;
 case MMIOERR_INVALID_PARAMETER:
  printf ("Error in this install program\n");
  break;
 case MMIOERR_INTERNAL_SYSTEM:
  printf ("OS/2 MPM System Error\n");
  break;
 case MMIOERR_NO_CORE:
  printf ("Memory unavailable for this IOProc\n");
  break;
 case MMIOERR_INI_OPEN:
  printf ("Unable to access the OS/2 MMPMMMIO.INI file\n");
  break;
 case MMIOERR_INVALID_FILENAME:
  printf ("Cannot find the file : OS13PROC.DLL\n");
  break;
 default:
  printf ("Unknown error attempting to install OS/2 Bitmap V(1.3)\n");
  break;
 }
}

[Back: File Format I/O Procedures Provided With OS/2 Multimedia]
[Next: CODEC Procedures]