Deallocating Memory Blocks

An application must be able to determine when a device driver is finished with the data block so that the application can unprepare and free the memory associated with the data block and header structure. The following list describes several ways to determine when a device driver is finished with a data block:

• By specifying a callback function to receive a message that is sent by the driver when it is finished with a data block
• By using an event callback
• By specifying a window or thread to receive a message sent by the driver when finished with a data block
• By polling the WHDR_DONE bit in the dwFlags member of the WAVEHDR structure sent with each data block

    To use a callback function for driver messages

1. Specify the CALLBACK_FUNCTION flag in the fdwOpen parameter of the waveInOpen or waveOutOpen function.
2. Specify the address of the callback in the dwCallback parameter of the waveInOpen or waveOutOpen function.

Messages sent to a callback function are similar to messages sent to a window, except that they have two DWORD parameters instead of one UINT and one DWORD parameter.

The following list describes techniques for passing instance data from an application to a callback function:

• Pass the instance data by using the dwInstance parameter of the function that opens the device driver
• Pass the instance data by using the dwUser member of the WAVEHDR structure that identifies an audio data block that was sent to a device driver

Note If you need more than 32 bits of instance data, pass a pointer to a structure containing the additional data.

    To use an event callback

1. Retrieve the handle of an event from CreateEvent.
2. Specify CALLBACK_EVENT for the fdwOpen parameter in your call to waveOutOpen.
3. Use waveOutPrepareHeader or waveInPrepareHeader to prepare the data block.
4. Call ResetEvent with the event handle retrieved by CreateEvent.

   This action creates a non-signaled event.

5. Send the waveform audio data block to the driver.
6. Call WaitForSingleObject, specifying as parameters the event handle and a time-out value of INFINITE.

   This call should be inside a loop that checks whether the WHDR_DONE bit is set in the dwFlags member of the WAVEHDR structure.

Because event callbacks do not receive specific close, done, or open notifications, an application might have to check the status of the process waiting for after the event occurs. It is possible for a number of tasks to be completed by the time WaitForSingleObject returns.

    To use a window callback function

• Call waveInOpen or waveOutOpen with the fdwOpen parameter set to CALLBACK_WINDOW and a window handle passed in the dwCallback parameter.

    To use a callback thread

• Call waveInOpen or waveOutOPen with the fdwOpen parameter set to CALLBACK_THREAD and a thread handle passed in the dwCallback parameter.

Note Messages sent to the window or thread callback are specific to the audio I/O device type used.

In addition to using a callback function, you can poll the dwFlags member of a WAVEHDR structure to determine when an audio I/O device is finished with a data block. Sometimes it is better to poll dwFlags than to wait for another mechanism to receive messages from the drivers. For example, after calling the waveOutReset or waveInReset function to release pending data blocks, you can immediately poll dwFlags for WHDR_DONE to be sure that the data blocks have been released.

Once you determine that the function has released the data block, call the waveInUnprepareHeader or waveOutUnprepareHeader function to unprepare the header file. After you have unprepared the header file, you can deallocate the memory normally.