The Installed Drivers list box displays the description strings of the installed drivers. The installed drivers are determined by examining the [drivers] and [mci] sections of the SYSTEM.INI file. The description strings are cached in the [drivers.description] section of the CONTROL.INI file to reduce delays in finding and loading them. If a description string does not match an installed driver, the application searches the MMSETUP.INF file and then the header of the driver file to obtain the description string. A scroll bar appears in the list box if there are more drivers than can be displayed.

(The following are excerpts from Windows DDK 2600 help)

Writing a MIDI Output Driver

Additional Entry-Point Functions for Audio Device Drivers

In addition to the installable-driver entry-point function, DriverProc, an audio device driver must have at least one of the following entry-point functions:

• The wodMessage function for waveform output drivers
• The widMessage function for waveform input drivers
• The modMessage function for MIDI output drivers and internal-synthesizer drivers
• The midMessage function for MIDI input drivers
• The auxMessage function for auxiliary audio drivers

Drivers that service more than one type of audio device must have one of these entry-point functions for each type of device serviced.

Note ACM compression and decompression drivers use only the DriverProc entry point.

These functions process messages sent by MMSYSTEM to the driver as the result of an application call to a low-level audio function. For example, when an application opens a waveform output device with the waveOutOpen function, MMSYSTEM sends the specified waveform-output device driver a WODM_OPEN message. The driver's wodMessage function receives and processes this message. For the exact syntax of each of these entry-point functions, see the sections about writing drivers for specific types of audio devices, later in this main topic.

Reference

This section lists the functions, messages, and structures provided by Windows for use by audio device drivers.

Windows communicates with audio device drivers through messages sent to the driver. The driver processes these messages with its wodMessage, widMessage, modMessage, midMessage, or auxMessage entry-point function. The function used depends on the type of device the driver supports. Drivers can also send messages to client applications with the DriverCallback function.

This section contains an alphabetical list of all messages that can be received and sent by audio device drivers. Each message name contains a prefix, identifying the type of the message. The following list identifies the prefixes used for audio device driver messages:

A message consists of three parts: a message number and two DWORD parameters. Message numbers are identified by predefined message names. The two DWORD parameters contain message-dependent values.

The stream buffer enhancement to the MIDI device architecture not only affects the MIDI SDK functions, data structures, and messages, but also reaches to the DDK level as driver messages. Many of the new MIDI driver messages documented in this section support the block data transfer of the stream buffer.

Module-Definition File

To build a device-driver DLL, you must have a module-definition (.DEF) file. In the module-definition file, you must export at least two of the following entry-point functions:

• DriverProc must be exported for all audio device drivers.
• wodMessage must be exported for waveform output drivers.
• widMessage must be exported for waveform input drivers.
• modMessage must be exported for MIDI output drivers.
• midMessage must be exported for MIDI input drivers.
• auxMessage must be exported for auxiliary audio drivers.
• mxdMessage must be exported for auxiliary audio drivers.

Functions are exported by ordinal, as shown in the following example MSSB16.DEF file:

LIBRARY     MSSB16

DESCRIPTION 'wave,aux,mixer:Creative Labs Sound Blaster 16 Driver'

EXETYPE     WINDOWS
PROTMODE

CODE        MOVEABLE DISCARDABLE LOADONCALL
DATA        FIXED SINGLE PRELOAD

SEGMENTS
    _TEXT       FIXED                          PRELOAD
    WEP_TEXT    FIXED                          PRELOAD
    INIT        MOVEABLE    DISCARDABLE        PRELOAD
    COMMON      MOVEABLE    DISCARDABLE        PRELOAD
    MIXER       MOVEABLE    DISCARDABLE        PRELOAD
    WAVE        MOVEABLE    DISCARDABLE        PRELOAD

HEAPSIZE    2048

EXPORTS
            WEP               @1       RESIDENTNAME
            DriverProc        @2       RESIDENTNAME
            wodMessage        @3       RESIDENTNAME
            widMessage        @4       RESIDENTNAME
            auxMessage        @5       RESIDENTNAME
            mxdMessage        @6       RESIDENTNAME
 

The actual ordinal values you assign to each exported function are not significant, though each must be unique within the DLL.

Handling Errors

For a description of the error return values from DriverProc, see the discussion of installable drivers in the documentation for the Microsoft Windows Software Development Kit. The following table lists the general error return values from auxMessage, mxdMessage, wodMessage, widMessage, midMessage, and midMessage.

In addition to the general error return values, there are error return values unique to each type of audio device. The following list identifies these device-specific error return values.

Entry-Point Functions

Following is an example of a DriverProc function. Regardless of how many types of audio devices a driver supports, the driver always has a single DriverProc function. The following example is the DriverProc function from the DRVPROC.C file, which supports four types of audio devices. While this example focuses heavily on ACM examples, the concepts are similar to those used for other types of drivers as well.

//  DWORD DriverProc
//  
//  Description:
//      The entry point for an installable driver.
//  
//  Parameters:
//      DWORD dwDriverID
//
//      For most messages, dwDriverId is the DWORD
//      value that the driver returns in response to a DRV_OPEN message.
//      Each time that the driver is opened, through the DrvOpen API,
//      the driver receives a DRV_OPEN message and can return an
//      arbitrary, nonzero value. The installable driver interface
//      saves this value and returns a unique driver handle to the
//      application. Whenever the application sends a message to the
//      driver using the driver handle, the interface routes the message
//      to this entry point and passes the corresponding dwDriverId.
//      This mechanism allows the driver to use the same or different
//      identifiers for multiple opens but ensures that driver handles
//      are unique at the application interface layer.
//
//      The following messages are not related to a particular open
//      instance of the driver. For these messages, the dwDriverId
//      will always be zero.
//
//         DRV_LOAD, DRV_FREE, DRV_ENABLE, DRV_DISABLE, DRV_OPEN
//  
//      HANDLE hDriver
//
//      This is the handle returned to the application by the driver
//      interface.
//
//      WORD wMessage
//
//      The requested action to be performed. Message values 
//      below DRV_RESERVED are used for globally defined messages.
//      Message values from DRV_RESERVED to DRV_USER are used for
//      defined driver protocols. Messages above DRV_USER are used
//      for driver specific messages.
//  
//      DWORD dwParam1
//
//      Data for this message.  Defined separately for each message
//
//      DWORD dwParam2
//
//      Data for this message.  Defined separately for each message
//  
//  Return (DWORD):
//      Defined separately for each message.

DWORD FAR PASCAL _loadds DriverProc
(
    DWORD           dwDriverID,
    HANDLE          hDriver,
    WORD            wMessage,
    DWORD           dwParam1,
    DWORD           dwParam2
)
{
   switch (wMessage)
   {
      case DRV_LOAD:

         // Sent to the driver when it is loaded. Always the first
         // message received by a driver.
         //
         // dwDriverID is 0L.
         // lParam1 is 0L.
         // lParam2 is 0L.
         //
         // Return 0L to fail the load.
         //
         // DefDriverProc will return nonzero so we don't have to
         // handle DRV_LOAD
         //

         DPF( 1, "DRV_LOAD" ) ;

#if 0
         // Make sure we're running on Windows 95...

         if (GetWindowsVersionCorrectly() < 0x0400)
         {
            AlertBox( NULL, SR_ALERT_31 ) ;
            return 0L ;
         }
#endif

         return 1L ;

      case DRV_FREE:

         // 
         // Sent to the driver when it is about to be discarded. This
         // will always be the last message received by a driver before
         // it is freed.
         // 
         // dwDriverID is 0L.
         // lParam1 is 0L.
         // lParam2 is 0L.
         // 
         // Return value is ignored.
         // 

         DPF( 1, "DRV_FREE" ) ;

         return 1L ;

      case DRV_OPEN:

         // 
         // Sent to the driver when it is opened.
         // 
         // dwDriverID is 0L.
         // 
         // lParam1 is a far pointer to a zero-terminated string
         // containing the name used to open the driver.
         // 
         // lParam2 is passed through from the drvOpen call.
         // 
         // Return 0L to fail the open.
         // 
         // DefDriverProc will return ZERO so we do have to
         // handle the DRV_OPEN message.
         // 

         DPF( 1, "DRV_OPEN" ) ;

         // No longer in initialization

#pragma message( REMIND( "bJustStart used???" ) )

         // bJustStart = 0 ;
         return 1L ;

      case DRV_CLOSE:

         // 
         // Sent to the driver when it is closed. Drivers are unloaded
         // when the close count reaches zero.
         // 
         // dwDriverID is the driver identifier returned from the
         // corresponding DRV_OPEN.
         // 
         // lParam1 is passed through from the drvOpen call.
         // 
         // lParam2 is passed through from the drvOpen call.
         // 
         // Return 0L to fail the close.
         // 
         // DefDriverProc will return ZERO so we do have to
         // handle the DRV_CLOSE message.
         // 

         DPF( 1, "DRV_CLOSE" ) ;

         return 1L ;

      case DRV_ENABLE:

         // 
         // Sent to the driver when the driver is loaded or reloaded
         // and whenever Windows is enabled. Drivers should only
         // hook interrupts or expect any part of the driver to be in
         // memory between enable and disable messages
         // 
         // dwDriverID is 0L.
         // lParam1 is 0L.
         // lParam2 is 0L.
         // 
         // Return value is ignored.
         // 

         DPF( 1, "DRV_ENABLE" ) ;

         if (DrvInit())
            return 0L ; // error

         // Load the volume settings, etc.

#pragma message( REMIND( "Need to load settings from registry" ) )

//         DrvLoadVolumeFromIni();

         // No longer in initialization

#pragma message( REMIND( "bJustStart used???" ) )

         // bJustStart = 0 ;
         return 1L ;

      case DRV_DISABLE:

         // 
         // Sent to the driver before the driver is freed.
         // and whenever Windows is disabled
         // 
         // dwDriverID is 0L.
         // lParam1 is 0L.
         // lParam2 is 0L.
         // 
         // Return value is ignored.
         // 

         DPF( 1, "DRV_DISABLE" ) ;

#pragma message( REMIND( "Need to save settings to registry" ) )

//         DrvSaveVolumeToIni () ;

         DrvEnd() ;

         return 1L ;

      case DRV_QUERYCONFIGURE:

         //
         // Sent to the driver so that applications can
         // determine whether the driver supports custom
         // configuration. The driver should return a
         // nonzero value to indicate that configuration
         // is supported.
         // 
         // dwDriverID is the value returned from the DRV_OPEN
         // call that must have succeeded before this message
         // was sent.
         // 
         // lParam1 is passed from the app and is undefined.
         // lParam2 is passed from the app and is undefined.
         // 
         // Return 0L to indicate configuration NOT supported.
         // 

         DPF( 1, "DRV_QUERYCONFIGURE" ) ;

#pragma message ( REMIND( "configure if not operational???" ) )

#if 0
         return (fEnabled != 0) ;        // we do configuration
#endif
         return TRUE ;

      case DRV_CONFIGURE:

         //
         // Sent to the driver so that it can display a custom
         // configuration dialog box.
         //
         // lParam1 is passed from the app. and should contain
         // the parent window handle in the loword.
         // lParam2 is passed from the app and is undefined.
         // 
         // Return value is REBOOT, OK, RESTART.
         // 

         DPF( 1, "DRV_CONFIGURE" ) ;

#if 0
         if (fEnabled)
            return DrvConfig( LOWORD( dwParam1 ), ghModule ) ;
#endif
         // else, default */
            break;

      case DRV_INSTALL:
         DPF( 1, "DRV_INSTALL" ) ;
         return DRV_OK ;

      case DRV_REMOVE:
         DPF( 1, "DRV_REMOVE" ) ;
         return 0 ;
               

      case DRV_POWER:
         DPF( 1, "DRV_POWER" ) ;

         switch (dwParam1)
         {
            case PWR_SUSPENDREQUEST:

               // If we decided we wanted to try to cause the machine to
               // not suspend, we would return PWR_FAIL. However, the 
               // machine may still be suspended - (the APM BIOS may 
               // override the driver's wishes).

               break ;

            case PWR_SUSPENDRESUME:

               // This notification is just for information.  PWR_OK 
               // should be returned regardless of what the driver does 
               // to resume normal hardware operations.

               break ;

            case PWR_CRITICALRESUME:

               // This notification is just for information.  This 
               // message indicates that the APM BIOS suspended the 
               // system without prior notice.  PWR_OK should be 
               // returned regardless of what the driver does to resume 
               // normal hardware operations.
               break ;
         }
         return PWR_OK ;
   }

   return DefDriverProc( dwDriverID, hDriver, wMessage, 
                         dwParam1, dwParam2 ) ;

} // DriverProc()
 

Multimedia Subsystem Driver Notification

After the VxD has successfully processed the CONFIG_START message, the multimedia device loader notifies the multimedia subsystem (MMSYSTEM.DLL) that a device node has successfully started. MMSYSTEM loads each of the associated ring-3 drivers and sends a device arrival notification. The ring-3 drivers query the supporting VxD for configuration information and complete the initialization necessary to support the device. The multimedia subsystem is designed to accommodate device nodes that have multiple function traits, such as music synthesis, digital sound support, hardware compression and/or decompression, and mixer support. When a device node is started, MMSYSTEM locates the registry entries for device node and loads the drivers for each supported class.

Note The changes and additions to the Window 3.1 multimedia device driver model as described below are specific to Windows 95 Plug and Play device drivers. Multimedia drivers loaded using the Windows 3.1 SYSTEM.INI entries will not experience these changes.

A device node might support four driver classes: wave, midi, aux and mixer. Each class may have multiple drivers. MMSYSTEM loads all drivers for all active classes when the device successfully starts. MMSYSTEM loads each module only once and increments reference counts as necessary (standard LoadLibrary() behavior); therefore, a multimedia ring-3 device driver's DriverProc() receives only one DRV_LOAD message when it is first loaded and only one DRV_FREE message when the last reference to the device is released.

A ring-3 device driver should maintain separate data structures for each device node and if the device driver supports multiple classes it should maintain reference counts for each active class. To assist in this task, Windows 95 introduces new parameters for the xxxx_INIT, xxxx_GETNUMDEVS, xxxx_GETDEVCAPS and xxxx_OPEN messages, and introduces new messages: DRVM_ENABLE, DRVM_DISABLE and DRVM_EXIT.

MMSYSTEM sends the xxxx_INIT, DRVM_ENABLE, DRVM_DISABLE and DRVM_EXIT message to each message procedure of each class of device when the corresponding activity has taken place for the device node.

Below is a description of these messages and the appropriate driver response:

• MMSYSTEM issues the xxxx_INIT message when the device is first started. Generally, a device driver allocates the instance structure or increments a usage reference count for this message.
• MMSYSTEM issues the DRVM_ENABLE message when the device node becomes active. The device driver should increment an enable count. The first time the device driver receives this notification it should perform hardware initialization as well as allocate other device support structures such as mixer structures, interrupt service thunks and so.
• MMSYSTEM issues the DRVM_DISABLE message when the device node becomes disabled. The device driver should decrement the enable count and when the enable count is zero, it should release hardware resources and free the structures allocated during the DRVM_ENABLE message processing. MMSYSTEM halts all application to driver message traffic is except xxxx_UNPREPARE, xxxx_RESET, xxxx_STOP and xxxx_CLOSE messages, allowing a driver to clean up remaining data associated with the device handle The Configuration Manager unloads the device node's VxD when the device enable count is zero and after the driver responds to this message.
• MMSYSTEM issues the DRVM_EXIT message after the device has been disabled and when there are no open handles to the device driver. The device driver should free the instance structure when the usage reference count is zero. Additionally, MMSYSTEM may dispatch another DRVM_ENABLE and DRVM_DISABLE pair before dispatching the DRVM_EXIT. This is particularly true for the case of device reconfiguration or PCMCIA removal and immediate re-insertion.

When the driver vendor follows the appropriate handling of these messages it is possible to accomplish any or all of the following:

• Change the configuration of software configurable hardware when a device handle remains open by a passive application (such as a mixer application).
• Seamlessly respond to portable docking and undocking situations.
• Handle PCMCIA hot-plugging events without additional code.

The code example below is the output wave device message handler from the Windows Sound System ring-3 driver. It demonstrates the appropriate handling of these new and modified messages.

DWORD FAR PASCAL _loadds wodMessage
(
    UINT            uDevId,
    WORD            msg,
    DWORD           dwUser,
    DWORD           dwParam1,
    DWORD           dwParam2
)
{
   NPWAVEALLOC         pClient ;
   PHARDWAREINSTANCE   phwi ;

   // take care of init time messages...

   switch (msg)
   {
      case WODM_INIT:
      {
         DPF( 3, "WODM_INIT" ) ;

         if (gwGlobalStatus)
         {
            DisplayConfigErrors() ;
            return 0L ;
         }
         else
         {
            // dwParam2 == PnP DevNode

            return (AddDevNode( dwParam2 )) ;
         }
      }
      break ;

      case DRVM_ENABLE:
      {
         DPF( 3, "WODM_ENABLE" ) ;

         // dwParam2 == PnP DevNode

         return (EnableDevNode( dwParam2 )) ;

      }
      break ;

      case DRVM_DISABLE:
      {
         DPF( 3, "WODM_DISABLE" ) ;

         // dwParam2 == PnP DevNode

         return (DisableDevNode( dwParam2 )) ;

      }
      break ;

      case DRVM_EXIT:
      {
         DPF( 3, "WODM_EXIT" ) ;

         // dwParam2 == PnP DevNode

         return (RemoveDevNode( dwParam2 )) ;

      }
      break ;

      case WODM_GETNUMDEVS:
      {
         DPF( 3, "WODM_GETNUMDEVS" ) ;

         if (NULL == (phwi = DevNodeToHardwareInstance( dwParam1 )))
            return MAKELONG( 0, MMSYSERR_INVALPARAM ) ;

         if (dwParam1)
         {
            if (phwi -> fEnabled)
               return 1L ;
            else
               return 0L ;
         }
         else
            return 0L ;
      }
      break ;

      case WODM_OPEN:
      {
         DWORD  dn ;

         DPF( 3, "WODM_OPEN" ) ;

         if (uDevId > 1)
            return MMSYSERR_BADDEVICEID ;

         dn = ((LPWAVEOPENDESC) dwParam1) -> dnDevNode ;

         if (NULL ==
               (phwi = DevNodeToHardwareInstance(dn)))
         {
            DPF( 1, "devnode not associated with hardware instance???" ) ;
            return MMSYSERR_BADDEVICEID ;
         }

         if (!phwi -> fEnabled)
            return MMSYSERR_NOTENABLED ;

         return (wodOpen(phwi,
                         dwUser,
                         (LPWAVEOPENDESC) dwParam1,
                         dwParam2 )) ;
      }
      break ;

      case WODM_GETDEVCAPS:
      {
         DPF( 3, "WODM_GETDEVCAPS" ) ;

         if (uDevId > 1)
            return MMSYSERR_BADDEVICEID ;

         if (NULL ==
               (phwi = DevNodeToHardwareInstance( dwParam2 )))
         {
            DPF( 1, "devnode not associated with hardware instance???" ) ;
            return MMSYSERR_BADDEVICEID ;
         }

         if (!phwi -> fEnabled)
            return MMSYSERR_NOTENABLED ;

         wodGetDevCaps( phwi, (MDEVICECAPSEX FAR *) dwParam1 ) ;
         return MMSYSERR_NOERROR ;
      }
      break ;
   }
}
   // Note that the remaining cases for this procedure have
   // been removed from this code example. Please see the 
   // MSSNDSYS.DRV example in the DDK for a complete sample.
 

The procedure of unloading the drivers for a device node is the inverse of the load procedure. That is, the ring-3 drivers are notified and unloaded and then MMDEVLDR issues the CONFIG_STOP message to the virtual device driver.