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

See also

IRP_MJ_CREATE

KSDATAFORMAT

KSDATARANGE

KSMULTIPLE_ITEM

KSPIN

KSPIN_DISPATCH