IPortEvents interface is used by miniport drivers to notify clients of hardware events. In Windows 98/Me and in Windows 2000 and later, all port drivers in portcls.sys implement this interface and expose it to miniport drivers. To determine whether a port driver supports the
IPortEvents interface, the miniport driver calls the IPortXxx object's QueryInterface method with REFIID IID_IPortEvents.
IPortEvents inherits from the IUnknown interface.
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 or mixer-line changes. For information about the mixer API, see the Microsoft Windows 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:
The filter that the miniport driver implements
Each pin that the filter exposes
Each node that the filter exposes
Each event entry in an automation table is a structure of type PCEVENT_ITEM that specifies the following:
An event set
An event within the set
Flags indicating support options
A function pointer to the handler for the event
Once the adapter driver is started and its port/miniport driver 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 driver 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
In addition to the methods that
IPortEvents inherits from the IUnknown interface,
IPortEvents supports the following two methods:
This section also describes the following routine for handling event requests: