DriverCallback

BOOL APIENTRY
    DriverCallback(
        DWORD dwCallBack,
        DWORD dwFlags,
        HDRVR hDriver,
        DWORD dwMsg,
        DWORD dwInstance,
        DWORD dwParam1,
        DWORD dwParam2
        );

The DriverCallback function is used by user-mode drivers to send a callback message to a client application.

Parameters

dwCallBack

The target for the callback message. Can be one of:

• An event handle

• A callback function address

• A thread identifier

• A window handle

The application specifies the type of callback target when opening a driver instance. The dwFlags parameter indicates the type of value stored in dwCallback.

dwFlags

One of the following flags, defined in mmddk.h, indicating the type of callback target:

DCB_EVENT	Equivalent to HIWORD(CALLBACK_EVENT). Indicates dwCallback contains an event handle. Code in winmm.dll calls the Win32 SetEvent function.
DCB_FUNCTION	Equivalent to HIWORD(CALLBACK_FUNCTION). Indicates dwCallback contains a function address. Code in winmm.dll calls the function.
DCB_TASK	Equivalent to HIWORD(CALLBACK_THREAD). Indicates dwCallback contains a thread identifer. Code in winmm.dll calls the Win32 PostThreadMessage function to post a WM_USER message.
DCB_WINDOW	Equivalent to HIWORD(CALLBACK_WINDOW). Indicates dwCallback contains a window handle. Code in winmm.dll calls the Win32 PostMessage function.

The CALLBACK_EVENT, CALLBACK_FUNCTION, CALLBACK_THREAD, and CALLBACK_WINDOW flags, referred to in the preceding table, are longword values used by applications when calling Win32 API functions that open multimedia drivers, such as midiOutOpen, waveOutOpen, or videoStreamInit.

hDriver

The driver handle that the driver received with the DRV_OPEN message.

dwMsg

A message to send to the application. Ignored if dwFlags is DCB_EVENT or DCB_TASK. The messages that can be sent are unique for each type of multimedia device and are listed in the chapters for each device type.

dwInstance

An application-supplied value to be passed to a callback function. Ignored if dwFlags is DCB_EVENT, DCB_TASK, or DCB_WINDOW. Applications specify this value when calling Win32 API functions that open multimedia drivers, such as midiOutOpen, waveOutOpen, or videoStreamInit.

dwParam1

A message-dependent parameter. Ignored if dwFlags is DCB_EVENT or DCB_TASK.

dwParam2

A message-dependent parameter. Ignored if dwFlags is DCB_EVENT, DCB_TASK, or DCB_WINDOW.

Return Value

Returns FALSE if dwCallback is NULL, if dwFlags is invalid, or if the message cannot be queued. Otherwise returns TRUE.

Comments

User-mode drivers call the DriverCallback function to deliver callback messages to applications that have requested them. Applications request delivery of callback messages by specifying a callback target when they open a driver instance. Win32 API functions that allow applications to specify a callback target include midiOutOpen, waveOutOpen, videoStreamInit, and others.