KS Properties, Events, and Methods

Kernel streaming architecture provides an extensible mechanism for minidrivers and user mode clients to interact. Each KS object supports intrinsic operations that allow clients to get and set object state, execute object methods, and register notification callbacks for events. Minidrivers support each of these categories of operations — properties, events, and methods — in a standardized manner. The client requests all three operations by providing the relevant alias structure of KSIDENTIFIER in a call to the Win32 routine DeviceIoControl. These structures include the following parameters:

• Set

  Functionally similar operations are grouped together in a set. Each property, event, or method set is identified by a GUID. Microsoft defines GUIDs for standard technology-specific operations. Minidrivers can define their own GUIDs for custom operations.

• Identifier

  Each operation is specified by an ID number within the set.

• Operation-specific identification data

  Certain operations require additional data. For example, pins on an audio device support the KSPROPSETID_Audio property set. An audio pin may support several different audio channels. Clients getting or setting certain KSPROPSETID_Audio properties must specify the audio channel to which the request applies. Currently, the only Microsoft-defined KS operations that require additional data are property sets.

Standard GUIDs and identifiers for general-purpose operations are found in the header ks.h. Standard GUIDs and identifiers for particular classes of multimedia technology are found in ksmedia.h.

For each operation, the user mode client passes two buffers:

• Instance Specification. The client specifies the operation instance to be the target of the I/O request. Every instance specification begins with a header (KSPROPERTY, KSEVENT, or KSMETHOD structure) that describes the operation set, operation ID, and operation flags, followed by any operation-specific identification data.

  To handle operations that require extended data structures, minidrivers use extended data structures that contain the instance header as the first member. For example, properties in the KSPROPSETID_Pin property set use the KSP_PIN structure to specify the property instance. The appropriate extended data structure is documented with each individual property set.

• Operation data. The client specifies a data buffer for the operation. Property requests use this buffer to either get or set the property. Method requests use this buffer for method input or output. Event notification requests use this property to determine the event notification type requested.

AVStream minidrivers support properties, events, and methods by providing a pointer to a KSAUTOMATION_TABLE structure in the relevant KSFILTER_DESCRIPTOR or KSPIN_DESCRIPTOR_EX. A KSAUTOMATION_TABLE contains a pointer to an array of KSPROPERTY_SET objects. To learn more, see Defining Automation Tables.

This section contains information on the following topics:

KS Properties

KS Events

KS Methods