IPortEvents interface (portcls.h)

The 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 IPortEvents interface.

This section also describes the following routine for handling event requests:

EventHandler

Inheritance

The IPortEvents interface inherits from the IUnknown interface.

Methods

The IPortEvents interface has these methods.

IPortEvents::AddEventToEventList The AddEventToEventList method adds an event to the port driver's event list.
IPortEvents::GenerateEventList The GenerateEventList method notifies clients through the port driver's list of event entries that a particular event has occurred.

Requirements

Requirement	Value
Target Platform	Windows
Header	portcls.h