waveInOpen(3mms) — Subroutines
Name
waveInOpen --- Open the specified waveform audio input device for recording
Syntax
#include <mme/mme_api.h>
MMRESULT waveInOpen(LPHWAVEIN lphWaveIn,
UINT uDeviceID,
LPWAVEFORMAT lpFormat,
VOID (∗dwCallback) (),
DWORD dwCallbackInstance,
DWORD dwFlags);
Arguments
LPHWAVEIN lphWaveIn
Specifies a pointer to an HWAVEIN handle. This location is filled with a handle identifying the opened waveform audio input device. Use this handle to identify the device when calling other waveform audio input functions. This argument may be NULL if the WAVE_FORMAT_QUERY flag is specified for the dwFlags argument.
UINT uDeviceID
Identifies the waveform audio input device to open. Use a valid waveform audio input device ID (see the Comments section) or the WAVE_MAPPER flag. The WAVE_MAPPER flag causes the system to select the waveform audio input device that is best capable of recording audio data in the specified format and attempt to open it.
LPWAVEFORMAT lpFormat
Specifies a pointer to a WAVEFORMAT data structure that identifies the desired format for recording waveform audio data.
Note that for certain format types (as specified by the wFormatTag field) the WAVEFORMAT data structure must be extended. See the Description section of this function for more information.
The WAVEFORMAT data structure must be allocated using the mmeAllocMem function before being passed to the waveInOpen function.
See the mmeAllocMem(3mms) reference page for more information about allocating memory for data structures.
VOID ∗(dwCallback) ()
Specifies the address of a callback function during waveform audio recording to process messages related to the progress of the audio recording. This argument may not be NULL unless the WAVE_FORMAT_QUERY flag is specified in the dwFlags argument.
DWORD dwCallbackInstance
Specifies user instance data passed to the callback function.
DWORD dwFlags
Specifies flags for opening the device. The following flags are defined:
WAVE_FORMAT_QUERY
If this flag is specified, the device is queried to determine if it supports the given format but is not actually opened.
WAVE_ALLOWSYNC
If this flag is specified, it allows a synchronous (blocking) waveform driver to be opened. If this flag is not set while opening a synchronous driver, the open operation fails.
CALLBACK_FUNCTION
If this flag is specified, the value of the dwCallback argument is assumed to be a callback procedure address.
WAVE_OPEN_SHAREABLE
If this flag is specified, the device is opened as a shareable device.
Description
The waveInOpen function opens the specified waveform audio input device for recording. The device ID specified by uDeviceID varies from zero to one fewer than the number of devices present. Use the waveInGetNumDevs function to determine the number of waveform input devices present in the system.
Depending upon the specific waveform format (as specified by the wFormatTag field) being specified with the lpFormat argument, it may be required to extend the WAVEFORMAT data structure referenced by the lpFormat argument. For example, for pulse code modulation (PCM) data, an extra word is added to specify the number of bits per sample. Use the PCMWAVEFORMAT data structure in this case.
Multimedia Services for DEC OSF/1 AXP does not support the use of a callback window. Only callback functions are supported. If an application specifies a callback window, the MMSYSERR_INVALPARAM error code is returned to the calling application.
Callback
void CALLBACK waveInCallbackFunction(HWAVEIN hWaveIn,
UINT uMsg,
DWORD dwInstance,
LPARAM lParam1,
LPARAM lParam2);
The waveInCallbackFunction function name is a placeholder for the callback function name supplied by the application. If a waveInOpen function is chosen to receive callback information, the messages listed under the uMsg argument are sent to the function to indicate the progress of waveform audio recording.
Callback Arguments
HWAVEIN hWaveIn
Specifies a handle to a waveform audio device associated with the callback function.
UINT uMsg
Specifies a waveform audio input message. The following messages are defined:
WIM_CLOSE
Sent when the device is closed using the waveInClose function.
WIM_OPEN
Sent when the device is opened using the waveInOpen function.
WIM_DATA
Sent when the device driver is finished processing a data block that was sent using the waveInAddBuffer function.
DWORD dwInstance
Specifies the user instance data specified as dwCallbackInstance with the waveInOpen function call.
LPARAM lParam1
Specifies an argument for the message. For the WIM_OPEN and WIM_CLOSE messages, this argument is not used.
For the WIM_DATA message, this argument specifies a pointer to a WAVEHDR data structure identifying the completed data block. The WAVEHDR data structure address is only valid while the callback function is executing; the address of the WAVEHDR data structure will not be the same as the address of the WAVEHDR data structure passed into the waveInAddBuffer function. The contents of the WAVEHDR data structure will be modified to reflect the result of the operation.
LPARAM lParam2
Specifies an argument for the message. This argument is not used.
After the driver is finished processing a data block, clean up and free the data block. See the mmeFreeMem(3mms) and mmeFreeBuffer(3mms) reference pages for more information about freeing data structures and data blocks. This work must be done outside the callback function. The Multimedia Services for DEC OSF/1 AXP API functions cannot be called from a callback function.
Extensions
The WAVE_OPEN_SHAREABLE flag, which allows a waveform audio output device to be opened as a shareable device, and the WAVERR_DEVICENOTSHAREABLE and WAVERR_DEVICESHAREABLE error codes are Digital extensions to the API specification.
Return Values
Returns MMSYSERR_NOERROR if the function is successful; otherwise, it returns one of the following error codes:
MMSYSERR_ALLOCATED@T{ The specified resource is allocated. T} MMSYSERR_BADDEVICEID@T{ The specified device ID is out of range. T} MMSYSERR_INVALHANDLE@T{ The specified device handle is invalid. T} MMSYSERR_INVALPARAM@T{ The lphWaveIn argument is passed as NULL and the dwFlags argument is set to WAVE_FORMAT. T} MMSYSERR_NOMEM@T{ Unable to allocate or lock memory. T} WAVERR_BADFORMAT@T{ Attempted to open with an unsupported wave format. T} WAVERR_DEVICENOTSHAREABLE@T{ The specified device is already opened as an exclusive device. T} WAVERR_DEVICESHAREABLE@T{ The specified device is already opened as a shareable device. T}