Stream Pointers and IRP Cancellation
If a frame has a locked stream pointer referencing it, the IRP that corresponds to this frame cannot be canceled. See Locking and Unlocking Stream Pointers.
The following table lists techniques that your minidriver can use to support IRP cancellation. Your cancellation strategy should be based on the stream access requirements of your minidriver, as described in the leftmost column.
| If you need.. | Do this | Comments |
|---|---|---|
Brief access to stream data at a single access point |
Call KsPinGetLeadingEdgeStreamPointer with the State parameter set to KSSTREAM_POINTER_STATE_LOCKED. Then call KsStreamPointerUnlock or KsStreamPointerAdvanceOffsetsAndUnlock immediately after processing is complete. |
Provides fast responsiveness to cancellation unless the thread blocks between acquiring the pointer and unlocking it. |
Indefinite length of access time, but can relinquish the claim in the context of a cancellation callback |
Call KsStreamPointerClone to clone a locked stream pointer (usually the leading edge), unlock it, and respond to CancelCallback. The callback occurs with the queue's spin lock held, hence at DISPATCH_LEVEL. Accordingly, the vendor-supplied CancelCallback routine cannot perform queue manipulation or call functions that acquire a mutex. Instead, in the callback routine, the minidriver verifies that the associated data will not be accessed later, and then calls KsStreamPointerDelete. |
Can be more difficult to implement, but often provides the best balance between efficient access and quick response to cancellation. |
Periodic access to a frame and can tolerate the disappearance of the frame between accesses |
Maintain an unlocked clone and call KsStreamPointerLock to lock it at access time. If the frame is canceled, the next attempt to lock the stream pointer fails, and the minidriver can call KsStreamPointerDelete. |
As with the first option, responsiveness to cancellation is a function of how long the stream pointer is locked. |
Indefinite length of access time and cannot relinquish the claim in response to a callback |
Maintain a locked clone stream pointer for any length of time to prevent cancellation. To create a clone stream pointer, call KsStreamPointerClone. Then call KsStreamPointerLock and KsStreamPointerUnlock to lock or unlock the clone. |
Responsiveness to cancellation may be poor. Consider using stream pointer timeouts with this technique. |
If a frame has a stream pointer referencing it, the minidriver can call KsStreamPointerGetIrp to access the IRP corresponding to this frame. To retrieve the memory descriptor list (MDL) associated with a frame, call KsStreamPointerGetMdl.