SynthInit

NTSTATUS
    SynthInit(
        IN PDRIVER_OBJECT
pDriverObject,
        IN PWSTR
RegistryPathName,
        IN PGLOBAL_SYNTH_INFO
pGDI,
        IN ULONG
SynthPort,
        IN BOOLEAN
InterruptConnected,
        IN INTERFACE_TYPE
BusType,
        IN ULONG
BusNumber,
        IN PMIXER_DATA_ITEM
MidiOutItem,
        IN UCHAR
VolumeControlId,
        IN BOOLEAN
Multiple,
        IN SOUND_DISPATCH_ROUTINE
*DevCapsRoutine
);

The SynthInit function creates a device object for a MIDI synthesizer (AdLib or OPL3) and performs additional initialization tasks.

Parameters
pDriverObject
Address of a location to receive a pointer to a DEVICE_OBJECT structure, if the call succeeds.
RegistryPathName
Pointer to a string representing the registry path to the device subkey. Use the path name created by either SoundEnumSubkeys or SoundSaveRegistryPath.
pGDI
Pointer to a GLOBAL_SYNTH_INFO structure.
SynthPort
Port address.
InterruptConnected
TRUE if interrupt is connected, FALSE otherwise.
BusType
Bus type. INTERFACE_TYPE is defined in ntddk.h.
BusNumber
Bus number.
MidiOutItem
Not used. Should be set to NULL.
VolumeControlId
A driver-defined volume control ID value.
Multiple
TRUE if indexed device names are allowed, FALSE otherwise.
DevCapsRoutine
Pointer to a driver-defined function that returns device capabilities. The function type is SOUND_DISPATCH_ROUTINE. To read about functions that return device capabilities, refer to the description of the DevCapsRoutine member of the SOUND_DEVICE_INIT structure.
Return Value

Returns STATUS_SUCCESS if the operation succeeds. Otherwise returns an NTSTATUS error code.

Comments

You do not create a SOUND_DEVICE_INIT structure for a synthesizer device, because soundlib.lib creates one internally. It also provides an internal dispatch routine and exclusion routine.

The SynthInit function performs the following operations, in order:

  1. Calls SoundCreateDevice to create a device object and a LOCAL_DEVICE_INFO structure.

  2. Sets default volume values for left and right channels in the Volume member of the device’s LOCAL_DEVICE_INFO structure.

  3. Calls SoundReportResourceUsage to obtain system resources.

  4. Calls SoundMapPortAddress to map port addresses.

  5. Attempts to reference the synthesizer hardware to verify that it exists at the specified address.

  6. Calls SoundSaveDeviceName to write the device name in the registry.

  7. Stores the specified volume control ID in the device’s LOCAL_DEVICE_INFO structure.

  8. Determines if the synthesizer chip is OPL3-compatible.

  9. Initializes the synthesizer hardware to silence.

Setting Multiple to FALSE causes SoundCreateDevice to be called with the SOUND_CREATION_NO_NAME_RANGE flag set. Use FALSE if the port address is 0x388.

Synthesizer interrupts are not handled by soundlib.lib. If the device supports a hardware interrupt, the driver must provide ISR code to handle it.

Drivers calling SynthInit must include synthdrv.h.