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:
-
Calls SoundCreateDevice to create a
device object and a LOCAL_DEVICE_INFO structure.
-
Sets default volume values for left and right channels in the Volume
member of the device’s LOCAL_DEVICE_INFO
structure.
-
Calls SoundReportResourceUsage
to obtain system resources.
-
Calls SoundMapPortAddress to map port
addresses.
-
Attempts to reference the synthesizer hardware to verify that it exists at the
specified address.
-
Calls SoundSaveDeviceName to write
the device name in the registry.
-
Stores the specified volume control ID in the device’s LOCAL_DEVICE_INFO
structure.
-
Determines if the synthesizer chip is OPL3-compatible.
-
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.