Use waveInOpen to open a waveform input device for recording. This function opens the device associated with the specified device ID and returns a handle to the open device by writing the handle to a specified memory location. The syntax of the waveInOpen function is as follows:
WORD waveInOpen(lphWaveIn, wDeviceID, lpFormat, dwCallback, dwInstance, dwFlags)
The lphWaveIn parameter is an LPHWAVEIN and specifies a far pointer to a memory location the function fills with a handle to the open waveform input device. Use this handle to identify the device when calling other waveform input functions.
The wDeviceID parameter is a WORD and identifies the waveform input device to be opened. See “Getting the Number of Devices,” earlier in this chapter, for details on device IDs. If you specify the WAVE_MAPPER constant, the function will find a waveform input device capable of recording in the given format and attempt to open it.
The lpFormat parameter is an LPWAVEFORMAT and specifies a far pointer to a WAVEFORMAT data structure. This data structure contains information on the format of the recorded waveform data that will be sent back to the application. For details on using this data structure, see “Specifying Waveform Data Formats,” earlier in this chapter. You can free the WAVEFORMAT data structure immediately after passing it to waveInOpen.
The dwCallback parameter is a DWORD and specifies either a window handle or the address of a low-level callback function. The callback can be used to monitor the progress of waveform recording so an application can determine when data blocks have been filled with waveform data and when to send additional data blocks for recording. You must specify the appropriate flag in the dwFlags parameter to indicate which type of callback you want. If no callback is needed, this parameter is NULL.
The dwInstance parameter is a DWORD and specifies 32 bits of instance data sent to the callback function each time it is called.
The dwFlags parameter is a DWORD and specifies one or more flags for opening a waveform device. Use the WAVE_FORMAT_QUERY flag to specify that you don't want to actually open a device, but just query whether the device supports a given format. For information on using WAVE_FORMAT_QUERY, see “Determining Non-Standard Format Support,” earlier in this chapter. If you are specifying a window or low-level callback in the dwCallback parameter, you must specify either the CALLBACK_WINDOW or the CALLBACK_FUNCTION flag to indicate the type of callback used.
Some multimedia computers will have multiple waveform input devices. Unless you know you want to open a specific waveform input device in a system, you should use the WAVE_MAPPER constant for the device ID when you open a device. The waveOutOpen function will choose the device in the system best able to record in the given data format.