PFNKSPINSETDATAFORMAT callback function (ks.h)
An AVStream minidriver's AVStrMiniPinSetDataFormat routine is called at pin creation time to verify that the previously agreed upon data format is acceptable for this KSPIN structure and a match for this KSDATARANGE structure. This routine is also called due to certain types of dynamic format changes, for example the acceptance of a KSPROPERTY_CONNECTION_PROPOSEDATAFORMAT property request.
Syntax
PFNKSPINSETDATAFORMAT Pfnkspinsetdataformat;
NTSTATUS Pfnkspinsetdataformat(
[in] PKSPIN Pin,
[in, optional] PKSDATAFORMAT OldFormat,
[in, optional] PKSMULTIPLE_ITEM OldAttributeList,
[in] const KSDATARANGE *DataRange,
[in, optional] const KSATTRIBUTE_LIST *AttributeRange
)
{...}
Parameters
[in] Pin
Pointer to the KSPIN structure for which the data format is changing.
[in, optional] OldFormat
Optional. Pointer to a KSDATAFORMAT structure. Minidrivers can use this field to determine the data format that the pin was using before this call. If NULL, indicates that no data format has been set for the pin and that Pin's create dispatch has not yet been made. A NULL value here indicates that this routine was called at initialization time for format verification.
[in, optional] OldAttributeList
Optional. Pointer to a KSMULTIPLE_ITEM structure that stores attributes for the previous format.
[in] DataRange
Pointer to a KSDATARANGE structure. The data range for the new format.
[in, optional] AttributeRange
Optional. The attribute range for the new format.
Return value
Return STATUS_SUCCESS if Pin's ConnectionFormat member matches the range that was passed to this routine. Return STATUS_NO_MATCH if ConnectionFormat does not match the passed range and the minidriver would like to continue to attempt to find a match with another range. Return an error code of choice if ConnectionFormat does not match the passed range and the minidriver does not want to continue to try to find a match with another range. Do not return STATUS_PENDING.
Remarks
In a ring 3 graph, the Kernel Streaming Proxy module (KsProxy) sets the data format based on the agreed upon connection format or a dynamic format change. KsProxy issues a KSPROPERTY_CONNECTION_DATAFORMAT request which, after some initial validation, is translated into this dispatch call to the minidriver. See Kernel Streaming Proxy. For more information, see KS Data Formats and Data Ranges and DataRange Intersections in AVStream.
The minidriver specifies the address for AVStrMiniPinSetDataFormat in the SetDataFormat member of its KSPIN_DISPATCH structure.
This routine can be called before the pin receives an IRP_MJ_CREATE, and minidrivers should be prepared to deal with this situation.
OldFormat, OldAttributeList, and AttributeRange are all optional parameters and can be NULL.
This routine is optional.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Available in Microsoft Windows XP and later operating systems and DirectX 8.0 and later DirectX versions. |
| Target Platform | Desktop |
| Header | ks.h (include Ks.h) |
| IRQL | PASSIVE_LEVEL |