The DriverCallback Function

Audio-device drivers need to notify clients when certain events occur, such as when a waveform data block has been played, or when a MIDI input event is received. Clients must be notified when the following conditions occur:

• When a device is opened.
• When a device is closed.
• When the driver is finished with a data block.
• When the driver receives data that should be passed directly back to the application, such as when a MIDI input driver receives a MIDI event from an input port.

When the client opens a device, the client specifies how it wants to be notified. There are three ways a driver can notify a client application:

• By calling a client-specified callback function.
• By sending a message to a client-specified window.
• By unblocking a client-specified task.

To make the job of notifying clients easier, MMSYSTEM provides the DriverCallback function. DriverCallback takes information supplied by the client when it opened a device and notifies the client accordingly. A MIDI driver can use the function as shown in the following example to call DriverCallback:

void FAR PASCAL midiCallback(
   NPPORTALLOC pPortalloc,
   WORD msg,
   DWORD dwParam1,
   DWORD dwParam2)
{
   if (pPortalloc->dwCallback)
      DriverCallback
      (  pPortalloc->dwCallback,       /* users callback DWORD */
         HIWORD(pPortalloc->dwFlags),  /* callback flags */
         pPortalloc->hMidi,            /* handle to the wave device */
        msg,                           /* message from the driver */
        Portalloc->dwInstance,         /* user's instance data */
        dwParam1,                      /* message-dependent parameter */
         dwParam2                      /* message-dependent parameter */
      );
}

The parameter pPortalloc points to a structure containing the MIDI device handle, callback flags, and user instance data passed to the driver with the MODM_OPEN message. For an example of how to handle the MODM_OPEN message, see . The parameters msg, dwParam1, and dwParam2 specify the message and message-dependent parameters the driver is sending to the client.