|
|
|
The IPortEvents interface is used by miniport drivers to notify clients of hardware events. This interface is implemented by the port driver and exposed to the miniport driver. To determine whether a port driver supports the IPortEvents interface, the miniport driver calls the port object's QueryInterface method with REFIID IID_IPortEvents. IPortEvents inherits from the IUnknown interface.
In Windows 98/Me and in Windows 2000 and later, the following port types support IPortEvents:
Drivers typically use the IPortEvents interface to notify the system of hardware-generated volume or mute changes, although IPortEvents can be used for any type of event notification. IPortEvents interface is an optional lower-edge port driver interface. It can be used, for example, to notify mixer applications of control and/or line changes. For information about the mixer API, see the Platform SDK documentation.
A miniport driver exposes an event in the same way that it exposes properties: through an automation table (see PCAUTOMATION_TABLE). The following objects, all of which are exposed by the miniport driver, can specify an automation table that contains properties and/or events:
Each event entry in an automation table is a structure of type PCEVENT_ITEM that specifies the following:
Once the adapter driver is started and its port/miniport pairs have been registered as filters with the system, the WDMAud system driver, which translates mixer API calls into KS commands to WDM audio drivers, will open each port/miniport pair and interrogate its capabilities. During this process, WDMAud will traverse the miniport driver's filter topology in search of a control node that supports a hardware event. The event is represented by the combination of event-set GUID KSEVENTSETID_AudioControlChange and event ID KSEVENT_CONTROL_CHANGE. When WdmAud finds these, it enables the event, effectively registering itself as a client of the event. Subsequently, each time the miniport driver signals the event, this notifies WDMAud, which generates the appropriate windows messages for its clients.
In addition to exposing the event in the automation table, a miniport driver that needs to expose events should query the port driver for its IPortEvents interface.
In addition to the methods that IPortEvents inherits from the IUnknown interface, IPortEvents supports the following two methods: