Edit

PFNKSPINSETDEVICESTATE callback function (ks.h)

  • Article

An AVStream minidriver's AVStrMiniPinSetDeviceState routine is called when the state of a KSPIN structure is changed due to the arrival of a connection state property 'set' IOCTL. Typically, this will be provided by minidrivers that need to change the state of hardware.

Syntax

PFNKSPINSETDEVICESTATE Pfnkspinsetdevicestate;

NTSTATUS Pfnkspinsetdevicestate(
  [in] PKSPIN Pin,
  [in] KSSTATE ToState,
  [in] KSSTATE FromState
)
{...}

Parameters

[in] Pin

Pointer to the KSPIN structure for which state is changing.

[in] ToState

The target KSSTATE after receipt of the IOCTL.

[in] FromState

The previous KSSTATE.

Return value

Return STATUS_SUCCESS or the error code that was returned from the attempt to set the state. Do not return STATUS_PENDING. The filter control mutex is held during this function. See Filter Control Mutex in AVStream.

Remarks

The minidriver specifies this routine's address in the SetDeviceState member of its KSPIN_DISPATCH structure.

Minidrivers will not receive a stop upon initial connection of the pin.

Pins that use the standard transport mechanism (standard interface/standard medium or an explicit use of KSPIN_FLAG_USE_STANDARD_TRANSPORT in KSPIN_DESCRIPTOR_EX) receive filtered state changes through the owning pipe through this routine. This means that no transition will be more than a single step. In other words, KSSTATE_STOP transitions to KSSTATE_ACQUIRE, KSSTATE_ACQUIRE transitions to KSSTATE_PAUSE, and so on. In addition, state changes received in this routine represent the state of the pipe as a whole, not the individual state of the pin as reported in the DeviceState member of the KSPIN structure.

Pins that do not use the standard transport mechanism (nonstandard interface, nonstandard medium, or an explicit use of KSPIN_FLAG_DO_NOT_USE_STANDARD_TRANSPORT in KSPIN_DESCRIPTOR_EX) receive nonfiltered state changes through this routine. As such, nonstandard transport pins must be prepared to deal with state changes that jump more than a single step. As an example, consider a jump from KSSTATE_RUN to KSSTATE_STOP without an intervening KSSTATE_PAUSE. In addition, the state reported to this routine will be identical to the state reported in the DeviceState member of the relevant KSPIN structure.

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

See also

KSPIN_DISPATCH