Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

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 that is 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 a thread to receive a message that is sent by the driver when the driver is finished with a data block

  • By polling the WHDR_DONE flag in the dwFlagsmember of the WAVEHDRstructure that is sent with each data block

To use a callback function for driver messages

  1. Specify the CALLBACK_FUNCTION flag in the fdwOpenparameter of the waveInOpenfunction or the waveOutOpenfunction.

  2. Specify the address of the callback in the dwCallbackparameter of waveInOpenor waveOutOpen.

Messages that are sent to a callback function are similar to messages that are sent to a window, except that messages sent to a callback function have two DWORDparameters instead of one UINTand one DWORDparameter.

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

  • Pass the instance data by using the dwInstanceparameter of the function that opens the device driver.

  • Pass the instance data by using the dwUsermember of the WAVEHDRstructure 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 that contains the additional data.
To use an event callback

  1. Retrieve the handle of an event from the CreateEventfunction.

  2. Specify the CALLBACK_EVENT flag for the fdwOpenparameter in your call to waveOutOpen.

  3. Use the waveOutPrepareHeaderfunction or the waveInPrepareHeaderfunction to prepare the data block.

  4. Call the ResetEventfunction with the event handle that is retrieved by the CreateEventfunction.

    This action creates a nonsignaled event.

  5. Send the waveform audio data block to the driver.

  6. Call the WaitForSingleObjectfunction, 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 flag is set in the dwFlagsmember of the WAVEHDRstructure.

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

To use a window callback function

  • Call waveInOpenor waveOutOpenwith the fdwOpenparameter set to CALLBACK_WINDOW and a window handle that is passed in the dwCallbackparameter.
To use a callback thread

  • Call waveInOpenor waveOutOpenwith the fdwOpenparameter set to CALLBACK_THREAD and a thread handle that is passed in the dwCallbackparameter.

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

In addition to using a callback function, you can poll the dwFlagsmember of a WAVEHDRstructure to determine when an audio I/O device is finished with a data block. You should sometimes poll dwFlagsrather than wait for another mechanism to receive messages from the drivers. For example, after calling the waveOutResetfunction or waveInResetfunction to release pending data blocks, you immediately can poll dwFlagsfor the WHDR_DONE flag to be sure that the data blocks have been released.

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

See Also