5.2 Wave, MIDI, and Aux I/O Control Codes

5.2 Wave, MIDI, and Aux I/O Control Codes

The following summarizes the I/O control codes for sound device drivers. The Status field of the I/O status block also can be set to STATUS_CANCELLED for any asynchronous device I/O control request.

IOCTL_WAVE_GET_CAPABILITIES

Operation

Returns information about the capabilities of the device, such as how many channels the wave input or output device has, which formats it supports, and the driver’s version.

Input

Parameters.DeviceIoControl.OutputBufferLength indicates the size in bytes of the buffer.

Output

The driver returns as much WAVEOUTCAPSW or WAVEINCAPSW data as the buffer’s size permits to the buffer at Irp->AssociatedIrp.SystemBuffer.

I/O Status Block

Always returns STATUS_SUCCESS in the Status field and the size in bytes of the returned data in the Information field.

IOCTL_WAVE_QUERY_FORMAT

Operation

Determines whether the device supports the specified format.

Input

The buffer at Irp->AssociatedIrp.SystemBuffer contains the PCMWAVEFORMAT value to be tested. Parameters.DeviceIoControl.InputBufferLength indicates the size in bytes of the buffer.

Output

None

I/O Status Block

The Information field is set to zero. The Status field either is set to STATUS_SUCCESS or possibly to STATUS_NOT_SUPPORTED if the device does not support the specified wave format or if the input buffer is not sizeof(PCMWAVEFORMAT).

IOCTL_WAVE_SET_FORMAT

Operation

Sets the format for a subsequent IOCTL_WAVE_PLAY request to the device. If the wave output device is opened but this request has not been received, the driver plays the wave output data at a device-specific default rate. If wave output is currently being played when this request is received, the interval until the new format takes effect is undefined.

Input

The buffer at Irp->AssociatedIrp.SystemBuffer contains the PCMWAVEFORMAT value to be set. Parameters.DeviceIoControl.InputBufferLength indicates the size in bytes of the buffer.

Output

None

I/O Status Block

IOCTL_WAVE_GET_STATE

Operation

Determines the current state of the target device object.

Input

Parameters.DeviceIoControl.OutputBufferLength indicates the size in bytes (a ULONG) of the buffer.

Output

The driver returns a constant indicating the current state, one of WAVE_DD_IDLE (for the wave input device), WAVE_DD_STOPPED, WAVE_DD_PLAYING (for the wave output device), or WAVE_DD_RECORDING (for the wave input device) to the buffer at
Irp->AssociatedIrp.SystemBuffer.

I/O Status Block

When Status is set to STATUS_SUCCESS, the Information field is set to sizeof(ULONG). Otherwise, Status can be set to STATUS_BUFFER_TOO_SMALL.

IOCTL_WAVE_SET_STATE

Operation

Sets the target device to the specified state.

Input

The buffer at Irp->AssociatedIrp.SystemBuffer contains the state specification, one of the constants WAVE_DD_STOP (suspends input or output, but completes recording of at least one buffer from the wave input device), WAVE_DD_RESET (cancels all input or output and sets the position to zero, but may complete outstanding read/write requests for the wave input/output devices), WAVE_DD_PLAY (for the wave output device), or WAVE_DD_RECORD (for the wave input device). Parameters.DeviceIoControl.InputBufferLength indicates the size in bytes of the buffer, which must be >= sizeof(ULONG).

Output

None

I/O Status Block

When the Status field is set to STATUS_SUCCESS, the Information field is set to zero, as it is for every other possible Status value, which can be STATUS_BUFFER_TOO_SMALL, STATUS_PENDING if the wave output state cannot be set immediately, or STATUS_DEVICE_BUSY if a previously submitted request to set the wave output state is still pending.

IOCTL_WAVE_GET_POSITION

Operation

Determines the number of sound samples and bytes processed.

Input

Parameters.DeviceIoControl.OutputBufferLength indicates the size in bytes of the buffer, which must be >= sizeof(WAVE_DD_POSITION).

Output

The driver returns the position information to the buffer at
Irp->AssociatedIrp.SystemBuffer.

I/O Status Block

The Information field is set to the number of bytes returned when the Status field is set to STATUS_SUCCESS. Otherwise, the Information field is set to zero when the Status field is set to STATUS_BUFFER_TOO_SMALL.

IOCTL_WAVE_GET_VOLUME

Operation

Determines the current volume of the wave output device, or returns the maximum value possible (WAVE_DD_MAX_VOLUME) if the device does not support volume control.

Input

Parameters.DeviceIoControl.OutputBufferLength indicates the size in bytes of the buffer, which must be >= sizeof(WAVE_DD_VOLUME).

Output

The driver returns the volume information to the buffer at
Irp->AssociatedIrp.SystemBuffer.

I/O Status Block

The Information field is set to the number of bytes returned. The Status field either is set to STATUS_SUCCESS or possibly to STATUS_BUFFER_TOO_SMALL or STATUS_NOT_SUPPORTED if the target device object is not wave output.

IOCTL_WAVE_SET_VOLUME

Operation

Sets the volume of the wave output device if it supports volume control.

Input

The buffer at Irp->AssociatedIrp.SystemBuffer contains the volume to be set. Parameters.DeviceIoControl.InputBufferLength indicates the size in bytes of the buffer, which must be >= sizeof(WAVE_DD_VOLUME).

Output

None

I/O Status Block

The Information field is set to zero. The Status field either is set to STATUS_SUCCESS or possibly to STATUS_BUFFER_TOO_SMALL, STATUS_NOT_SUPPORTED if the device hardware does not support volume setting, or STATUS_INVALID_PARAMETER if the target device object is not wave output.

IOCTL_WAVE_GET_PITCH

Operation

Determines the current pitch setting of the wave output device if the device supports pitch control.

Input

Parameters.DeviceIoControl.OutputBufferLength indicates the size in bytes of the buffer, which must be >= sizeof(WAVE_DD_PITCH).

Output

The driver returns the current pitch setting to the buffer at
Irp->AssociatedIrp.SystemBuffer.

I/O Status Block

The Information field is set to the number of bytes returned. The Status field either is set to STATUS_SUCCESS or possibly to STATUS_BUFFER_TOO_SMALL, STATUS_NOT_SUPPORTED if the device does not support pitch control, or STATUS_INVALID_PARAMETER if the target device object is not wave output.

IOCTL_WAVE_SET_PITCH

Operation

Sets the pitch of the wave output device for a subsequent IOCTL_WAVE_PLAY request if the device supports pitch control.

Input

The buffer at Irp->AssociatedIrp.SystemBuffer contains the pitch to be set. Parameters.DeviceIoControl.InputBufferLength indicates the size in bytes of the buffer, which must be >= sizeof(WAVE_DD_PITCH).

Output

None

I/O Status Block

The Information field is set to zero. The Status field either is set to STATUS_SUCCESS or possibly to STATUS_BUFFER_TOO_SMALL, STATUS_NOT_SUPPORTED, or STATUS_INVALID_PARAMETER.

IOCTL_WAVE_GET_PLAYBACK_RATE

Operation

Determines the current playback rate of the wave output device if the device supports playback-rate control.

Input

Parameters.DeviceIoControl.OutputBufferLength indicates the size in bytes of the buffer, which must be >= sizeof(WAVE_DD_PLAYBACK_RATE).

Output

The driver returns the playback-rate information to the buffer at
Irp->AssociatedIrp.SystemBuffer.

I/O Status Block

The Information field is set to the number of bytes returned when the Status field is set to STATUS_SUCCESS. Otherwise, the Information field is set to zero, and the Status field can be set to STATUS_BUFFER_TOO_SMALL, STATUS_NOT_SUPPORTED if the device does not support playback-rate control, or STATUS_INVALID_PARAMETER if the target device object is not wave output.

IOCTL_WAVE_SET_PLAYBACK_RATE

Operation

Sets the playback rate of the wave output device if the device supports playback-rate control.

Input

The buffer at Irp->AssociatedIrp.SystemBuffer contains the playback rate to be set. Parameters.DeviceIoControl.InputBufferLength indicates the size in bytes of the buffer, which must be >= sizeof(WAVE_DD_PLAYBACK_RATE).

Output

None

I/O Status Block

The Information field is set to zero. The Status field either is set to STATUS_SUCCESS or possibly to STATUS_BUFFER_TOO_SMALL, STATUS_NOT_SUPPORTED, or STATUS_INVALID_PARAMETER.

IOCTL_WAVE_SET_LOW_PRIORITY

Operation

Sets the wave input device to “low priority mode,” that is, temporarily suspends recording if the adapter supports the operation. This request occurs when the wave input device object has already been opened (see the IRP_MJ_CREATE description in Section 5.1) and a second application gets a handle for the wave input device or for another device object that shares the same hardware. To satisfy this request, the driver suspends recording until the second application releases its handle (see the IRP_MJ_CLOSE description in Section 5.1). Supporting this I/O control request allows multimedia applications to use the hardware while voice input is being used to detect voice commands.

Input

None

Output

None

I/O Status Block

The Information field is set to zero. The Status field either is set to STATUS_SUCCESS or possibly to STATUS_INVALID_PARAMETER if the target device object is not wave input or to STATUS_DEVICE_BUSY if low priority mode is already in effect or the device is busy for some other reason.

IOCTL_WAVE_PLAY

Operation

None. This IOCTL is obsolete.

IOCTL_WAVE_RECORD

Operation

None. This IOCTL is obsolete.

IOCTL_WAVE_BREAK_LOOP

Operation

None. This IOCTL is obsolete.

IOCTL_MIDI_GET_CAPABILITIES

Operation

Returns information about the capabilities of the device, such as how many voices and notes the output device has and whether it has volume control, or the manufacture and product identification of a MIDI input device, as well as the driver version number.

Input

Parameters.DeviceIoControl.OutputBufferLength indicates the size in bytes of the buffer.

Output

The driver returns as much MIDIOUTCAPSW or MIDIINCAPSW data as the buffer’s size permits to the buffer at Irp->AssociatedIrp.SystemBuffer.

I/O Status Block

Always returns STATUS_SUCCESS in the Status field and the size in bytes of the returned data in the Information field.

IOCTL_MIDI_GET_STATE

Operation

Determines the current state of the target device object.

Input

Parameters.DeviceIoControl.OutputBufferLength indicates the size in bytes (a ULONG) of the buffer.

Output

The driver returns a constant indicating the current state, one of MIDI_DD_IDLE, MIDI_DD_STOPPED, MIDI_DD_PLAYING (for the MIDI output device), or MIDI_DD_RECORDING (for the MIDI input device) to the buffer at Irp->AssociatedIrp.SystemBuffer.

I/O Status Block

The Status field is set to STATUS_SUCCESS, and the Information field is set to sizeof(ULONG).

IOCTL_MIDI_SET_STATE

Operation

Sets the target device to the specified state.

Input

The buffer at Irp->AssociatedIrp.SystemBuffer contains the state specification, one of the constants MIDI_DD_STOP (suspend playing or recording), MIDI_DD_RESET (stop playing and cancel outstanding requests for the MIDI output device), MIDI_DD_PLAY (for the MIDI output device), or MIDI_DD_RECORD (for the MIDI input device). Parameters.DeviceIoControl.InputBufferLength indicates the size in bytes (a ULONG) of the buffer.

Output

None

I/O Status Block

When the Status field is set to STATUS_SUCCESS, the Information field is set to zero, as it is for every other possible Status value, which can be STATUS_PENDING or STATUS_DEVICE_BUSY if another state-change operation is not yet complete.

IOCTL_MIDI_GET_VOLUME

Operation

If the MIDI output device supports volume control, the driver returns the current volume setting of the device.

Input

Parameters.DeviceIoControl.OutputBufferLength indicates the size in bytes of the buffer, which must be >= sizeof(MIDI_DD_VOLUME).

Output

The driver returns the volume information in the buffer at
Irp->AssociatedIrp.SystemBuffer.

I/O Status Block

The Information field is set to the amount of returned data. The Status field either is set to STATUS_SUCCESS or possibly to STATUS_BUFFER_TOO_SMALL or STATUS_NOT_SUPPORTED.

IOCTL_MIDI_SET_VOLUME

Operation

If the MIDI output device supports volume control, the driver sets the volume of the device.

Input

Output

None

I/O Status Block

The Information field is set to zero. The Status field either is set to STATUS_SUCCESS or possibly to STATUS_BUFFER_TOO_SMALL or STATUS_NOT_SUPPORTED.

IOCTL_MIDI_CACHE_PATCHES

Operation

Preloads the specified bank of patches (zero for the default patch bank) if the device’s internal synthesizer cannot keep all patches loaded simultaneously.

Input

Parameters.DeviceIoControl.InputBufferLength indicates the size in bytes, which must be >= sizeof(MIDI_DD_CACHE_PATCHES), of the buffer at
Irp->AssociatedIrp.SystemBuffer.

Output

None

I/O Status Block

The Information field is set to zero. The Status field either is set to STATUS_SUCCESS or possibly to STATUS_BUFFER_TOO_SMALL or STATUS_NOT_SUPPORTED.

IOCTL_MIDI_CACHE_DRUM_PATCHES

Operation

Preloads the specified bank of key-based percussion patches (zero for the default drum patch bank) if the device’s internal synthesizer cannot keep all percussion patches loaded simultaneously.

Input

Parameters.DeviceIoControl.InputBufferLength indicates the size in bytes, which must be >= sizeof(MIDI_DD_CACHE_DRUM_PATCHES), of the buffer at Irp->AssociatedIrp.SystemBuffer.

Output

None

I/O Status Block

The Information field is set to zero. The Status field either is set to STATUS_SUCCESS or possibly to STATUS_BUFFER_TOO_SMALL or STATUS_NOT_SUPPORTED.

IOCTL_MIDI_PLAY

Operation

Transfers data from the calling user-mode thread’s buffer to the device.

Input

The driver’s I/O stack location in the IRP has a pointer to the user buffer at Parameters.DeviceIoControl.Type3InputBuffer. Parameters.DeviceIoControl.InputBufferLength indicates the size in bytes of the buffer.

Output

None

I/O Status Block

The Information field is set to zero. The Status field can be set to STATUS_SUCCESS or to STATUS_DEVICE_BUSY if the MIDI output device is currently playing.

IOCTL_MIDI_RECORD

Operation

None. This IOCTL is obsolete.

IOCTL_AUX_GET_CAPABILITIES

Operation

Returns information about the capabilities of the MMAux (sound) device.

Input

Parameters.DeviceIoControl.OutputBufferLength indicates the size in bytes of the buffer.

Output

The driver returns as much AUXCAPSW data as the buffer’s size permits to the buffer at Irp->AssociatedIrp.SystemBuffer.

I/O Status Block

Always returns STATUS_SUCCESS in the Status field and the size in bytes of the returned data in the Information field.

IOCTL_AUX_GET_VOLUME

Operation

Determines the current volume of the MMAux device, or returns the maximum value possible (AUX_DD_MAX_VOLUME) if the device does not support volume control.

Input

Parameters.DeviceIoControl.OutputBufferLength indicates the size in bytes of the buffer, which must be >= sizeof(AUX_DD_VOLUME).

Output

The driver returns the volume information to the buffer at
Irp->AssociatedIrp.SystemBuffer.

I/O Status Block

IOCTL_AUX_SET_VOLUME

Operation

Sets the volume of the MMAux device if it supports volume control.

Input

Output

None

I/O Status Block

IOCTL_MIX_GET_CONFIGURATION

Operation

Returns the configuration information defined by:

·MIXER_DD_CONFIGURATION_DATA, containing capabilities data, the NumberOfLines and the NumberOfControls.

·MIXER_DD_LINE_CONFIGURATION_DATA, containing the destination, source, and string ids which are resource strings in the DLL portion of the driver. There is one such structure for each destination/source combination.

·MIXER_DD_CONTROL_CONFIGURATION_DATA containing control information such as the maximum and minimum values for a control, and string ids which are resource strings in the DLL portion of the driver. There is one such structure for each control.

·MIXER_DD_CONTROL_LISTTEXT which describes a single entry for a mixer or mux. For each multiple select control (either a mixer or a mux) there are cMultipleItems entries where cMultipleItems is a member of the MIXER_DD_CONTROL_CONFIGURATION_DATA structure for that control.

The output will contain the following data in the order listed here:

·The data defined by the MIXER_DD_CONFIGURATION_DATA structure.

·NumberOfLines MIXER_DD_LINE_CONFIGURATION DATA structures ordered according to the destination line order.

·NumberOfControls MIXER_DD_CONTROL_CONFIGURATION structures ordered so that the line ids are in the same order as the line ids in the MIXER_DD_LINE_CONFIGURATION_DATA structure.

·A per control array of MIXER_DD_CONTROL_LISTTEXT structures for each multiple select control ordered by control id. Within each per control array, the elements are ordered so that the n’th element corresponds to the n’th selection in that control.

Input

None

Output

The driver returns the current configuration data to the buffer at Irp->AssociatedIrp.SystemBuffer. Note that if the buffer supplied by the caller is too small for the amount of available configuration data, the driver can return as much data as will fit and then indicate buffer overflow in the status block. The first member of the MIXER_DD_CONFIGURATION_DATA structure, cbSize, is the total configuration data available. This can be read in order to determine the correct amount of data to request.

Status Block

The driver returns the amount of configuration data in the output buffer in the Information field. The Status field is either set to STATUS_SUCCESS or possibly STATUS_BUFFER_OVERFLOW if the output buffer is smaller than the amount of available configuration data.

IOCTL_MIX_GET_CONTROL_DATA

Operation

Returns the control data for the control line whose id is specified in the MIXER_DD_READ_DATA structure supplied as input.

Input

The buffer at Irp->AssociatedIrp.SystemBuffer specifies the control id for which data is to be read. The Parameters.DeviceIoControl.InputLength indicates the size in bytes of the input buffer, which must be >= sizeof(MIXER_DD_READ_DATA).

Output

The driver returns the control data at Irp->AssociatedIrp.SystemBuffer.

Status Block

The Status field either is set to STATUS_SUCCESS or STATUS_BUFFER_TOO_SMALL. The Information field contains the number of bytes returned.

IOCTL_MIX_GET_LINE_DATA

Operation

Returns the line data for the line id specified in the MIXER_DD_READ_DATA structure supplied as input. The data is returned in the format described by the MIXER_DD_LINE_DATA structure. Only the MIXERLINE_LINEF_ACTIVE flag changes. If the driver sets the MIXERLINE_LINEF_DISCONNECTED flag, the line should be ignored by applications.

Input

The buffer at Irp->AssociatedIrp.SystemBuffer contains the line id for which data is to be read. The Parameters.DeviceIoControl.InputLength indicates the size in bytes of the input buffer, which must be >= sizeof(MIXER_DD_READ_DATA).

Output

The driver returns line data to the buffer at Irp->AssociatedIrp.SystemBuffer.

Status Block

The Status field is set to STATUS_SUCCESS or possibly to STATUS_BUFFER_TOO_SMALL. The Information field is set to the number of bytes of returned data.

IOCTL_MIX_REQUEST_NOTIFY

Operation

The caller should supply the same buffer for input and to receive the output. The driver will keep track of which changes have been reflected to the application by reading the CurrentLogicalTime member. The driver increments this member for each change.

Input

Parameters.DeviceIoControl.InputBufferLength indicates the size in bytes of the buffer, which must be >= sizeof(MIXER_DD_REQUEST_NOTIFY). The Irp->AssociatedIrp.SystemBuffer will be a buffer of type MIXER_DD_REQUEST_NOTIFY.

Output

The driver returns changes in the buffer at Irp->AssociatedIrp.SystemBuffer. This buffer should be the same buffer supplied as input and must be >= sizeof(MIXER_DD_REQUEST_NOTIFY).

Status Block

The Status field is set to STATUS_SUCCESS, or possibly one of the following: STATUS_BUFFER_TOO_SMALL if the supplied buffer is < sizeof(MIXER_DD_REQUEST_NOTIFY), to STATUS_PENDING, or to STATUS_INVALID_PARAMETER if the time field in the input buffer is invalid.

IOCTL_SOUND_GET_CHANGED_VOLUME

Operation

Returns the actual volume of the MMAux device when its current value does not match the requested setting, provided that the device supports volume control. This request is usually asynchronous. It is completed as soon as the volume of the Aux device differs from the values that were set.

Input

Parameters.DeviceIoControl.OutputBufferLength indicates the size in bytes of the buffer, which must be >= sizeof(AUX_DD_VOLUME).

Output

The driver returns the current volume setting to the buffer at
Irp->AssociatedIrp.SystemBuffer.

I/O Status Block

The Information field is set to the number of bytes returned. The Status field either is set to STATUS_SUCCESS or possibly to STATUS_BUFFER_TOO_SMALL, STATUS_INSUFFICIENT_RESOURCES, or STATUS_NOT_SUPPORTED if the hardware does not support volume setting.