|
|
|
A miniport driver provides information about the properties that it supports in the form of an array of PCPROPERTY_ITEM structures. Each structure contains the following information about a property:
The property-item array is contained in the automation table within the PCFILTER_DESCRIPTOR structure that the filter factory outputs to the port driver through its IMiniport::GetDescription method. For more information, see Filter Factories.
A miniport driver can specify a unique property-handler routine for each property. In practice, if a driver handles several similar properties, these can often be consolidated into a single handler routine for convenience. Whether to provide a unique handler for each property or to consolidate several properties into a single handler is an implementation decision to be made by the driver writer and should be transparent to clients that submit property requests.
A client can send a get- or set-property request by calling the Win32 function DeviceIoControl with the dwIoControlCode call parameter set to IOCTL_KS_PROPERTY. The operating system converts this call to an IRP, which it dispatches to the class driver. For more information, see KS Properties.
When a client sends a property request to a miniport driver's handler for a filter or pin property, the KS system driver delivers the request to the port driver that the miniport driver is bound to. Before forwarding the request to the miniport driver's property handler, the port driver converts the information from the original property request into the format specified by the PCPROPERTY_REQUEST structure. This is the structure that the port driver passes as a call parameter to the property-handler routine.
The MajorTarget member of PCPROPERTY_REQUEST points to the primary miniport interface for the audio device. For a WavePci device, for example, this a pointer to the miniport object's IMiniportWavePci interface.
In the case of a filter property request, the MinorTarget member of PCPROPERTY_REQUEST is NULL. In the case of a pin property request, MinorTarget points to the stream interface for the pin. For a WavePci device, for example, this is a pointer to the stream object's IMiniportWavePciStream interface.
The Instance and Value members of PCPROPERTY_REQUEST point to the buffers that contain the property's descriptor (instance data) and value (operation data), respectively. The InstanceSize and ValueSize members specify the sizes of these two buffers.
The port driver simply copies the value pointer and value size from the original property request into the Value and ValueSize members. It modifies the instance pointer and instance size, however, before copying them into the Instance and InstanceSize members.
The instance pointer from the original property request points to a buffer that begins with either a KSPROPERTY or KSNODEPROPERTY structure, but might contain additional information. The KSPROPERTY_TYPE_TOPOLOGY bit in the property request's operation flags indicates which of these two structures is used:
The port driver adjusts the instance pointer to point to the additional information that follows the KSPROPERTY or KSNODEPROPERTY structure before loading it into the Instance member. It also decrements the instance size by the size of KSPROPERTY or KSNODEPROPERTY before loading it into the InstanceSize member. If the instance data contains no additional information, the port driver sets Instance and InstanceSize to NULL and zero, respectively.
For example, if the client specifies a KSNODEPROPERTY_AUDIO_CHANNEL structure as the instance data, the port driver passes the handler a PCPROPERTY_REQUEST structure whose Instance member points to the KSNODEPROPERTY_AUDIO_CHANNEL structure's Channel member, and whose InstanceSize member contains the value
sizeof(KSNODEPROPERTY_AUDIO_CHANNEL) – sizeof(KSNODEPROPERTY)
The port driver copies the information from the KSPROPERTY or KSNODEPROPERTY structure into the PCPROPERTY_REQUEST structure's Node, PropertyItem, and Verb members. In the case of KSPROPERTY, which contains no node information, the port driver sets Node to the null node-ID value, ULONG(-1).
Before submitting a get-property request, the client should allocate the buffer into which the miniport driver's property handler is to write the property value (operation data). For some properties, the size of the property value is device-dependent and the client must query the property handler for the required buffer size. In these cases, the client submits an initial property request with a zero-length output buffer. The handler responds by returning the required buffer size along with the status code STATUS_BUFFER_OVERFLOW. (The handler writes the required size into the ValueSize member of the PCPROPERTY_REQUEST structure.) The client then retrieves the property value by allocating a property-value buffer of the specified size and sending this buffer in a second get-property request.