SoundEnumSubkeys

NTSTATUS
    SoundEnumSubkeys(
        IN PUNICODE_STRING RegistryPathName,
        IN PWSTR Subkey,
        IN PSOUND_REGISTRY_CALLBACK_ROUTINE Callback,
        IN PVOID Context
        );

The SoundEnumSubkeys function enumerates the subkeys under the specified subkey, which is in the specified registry path. For each subkey found under the specified subkey, SoundEnumSubkeys calls the specified callback function.

Parameters

RegistryPathName

Pointer to a string representing the registry path to the driver subkey. Use the path name received as the RegistryPathName argument to DriverEntry.

SubKey

Pointer to a string representing the subkey at end of the path specified by RegistryPathName. SoundEnumSubkeys enumerates subkeys under this subkey.

Callback

Pointer to a function to call for each subkey found under Subkey. The function type is SOUND_REGISTRY_CALLBACK_ROUTINE.

Context

Pointer to a driver-specified context parameter. This parameter is passed to the function pointed to by Callback.

Return Value

If the function detects a failure, it returns an NTSTATUS error code. Otherwise it returns the value returned by the callback function. If the callback function succeeds, it should return STATUS_SUCCESS. Otherwise it should return an NTSTATUS error code.

Comments

Use the SoundEnumSubkeys function when performing device initialization operations, if your driver supports multiple hardware devices. If you specify “Parameters” for the Subkey parameter, the function calls the callback function for each “device” subkey under \Parameters. For an example, see Examining DriverEntry in sndblst.sys. (The device entries under the \Parameters subkey are created by user-mode drivers, typically by calling DrvCreateDeviceKey.)

SoundEnumSubkeys passes a registry path name to the callback function (see SOUND_REGISTRY_CALLBACK_ROUTINE).This path name is the path name received as the RegistryPathName argument, with \Parameters\DeviceNumber appended.

The callback function returns an NTSTATUS value. If, for any call to the callback function, the return value is not STATUS_SUCCESS, then SoundEnumSubkeys immediately returns to its caller, passing back the return value received from the callback function.

Drivers which do not support multiple hardware devices do not call SoundEnumSubkeys. Instead, they should call SoundSaveRegistryPath as part of their initialization operation, in order to create a registry path name that can be used as input to other soundlib.lib functions.