waveInPrepareHeader

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This function prepares a buffer for waveform input. This function allows both the audio driver and the operating system (OS) to do time consuming processing of the header and/or buffer once at initialization. The application can use the buffer repeatedly without additional processing by the driver or the OS.

Syntax

MMRESULT waveInPrepareHeader(
  HWAVEIN hwi, 
  LPWAVEHDR pwh, 
  UINT cbwh 
); 

Parameters

• hwi
  Handle to the waveform-audio input device.

• pwh
  Pointer to a WAVEHDR structure that identifies the buffer to be prepared. The buffer's base address must be aligned with the respect to the sample size.

• cbwh
  Size, in bytes, of the WAVEHDR structure.

Return Value

One of the values described in the following table is returned.

Remarks

The lpData, dwBufferLength, and dwFlags members of the WAVEHDR structure must be set before calling this function (dwFlags must be zero).

Once prepared, the application may not change the lpData field. The dwFlags, dwBufferLength, and dwLoops members of the WAVEHDR structure can change between calls to this function and the waveOutWrite function, but it should never be increased above the amount originally specified in the call to waveInPrepareHeader. For example, when playing from a file an application will typically pass the same amount of data to the driver on each call to waveOutWrite until it hits the end-of-file. At that point, it will pass the remaining file data in a partial buffer (with a smaller value in dwBufferLength).

The only flags in the dwFlags member that you can change during this interval are WHDR_BEGINLOOP and WHDR_ENDLOOP. You can only change these flags as a matched pair; therefore, if you add or remove one of these flags, you must add or remove the other. If you change the size specified by dwBufferLength before the call to waveOutWrite, the new value must be less than the prepared value.

Preparing a header that has already been prepared has no effect, and the function returns zero.

An application should not attempt to prepare the same header on two different wave devices at the same time. If you want to record from one wave device and play back the same data to another wave device, but don't want to copy data between buffers, you can allocate two wave headers, point them both to the same data buffer, and then call waveInPrepareHeader on one and waveOutPrepareHeader on the other as appropriate.

Requirements

See Also

Reference

Waveform Audio Functions
WAVEHDR