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.