IWDFIoRequest::MarkCancelable-Methode (wudfddi.h)

Artikel
02/27/2024

[Warnung: UMDF 2 ist die neueste Version von UMDF und ersetzt UMDF 1. Alle neuen UMDF-Treiber sollten mit UMDF 2 geschrieben werden. UMDF 1 werden keine neuen Features hinzugefügt, und die Unterstützung für UMDF 1 in neueren Versionen von Windows 10 ist eingeschränkt. Universelle Windows-Treiber müssen UMDF 2 verwenden. Weitere Informationen finden Sie unter Erste Schritte mit UMDF.]

Die MarkCancelable-Methode ermöglicht das Abbrechen der E/A-Anforderung.

Syntax

void MarkCancelable(
  [in] IRequestCallbackCancel *pCancelCallback
);

Parameter

[in] pCancelCallback

Ein Zeiger auf die IRequestCallbackCancel-Schnittstelle , deren Methode das Framework aufruft, nachdem die E/A-Anforderung abgebrochen wurde.

Rückgabewert

Keine

Bemerkungen

Nachdem ein Treiber eine E/A-Anforderung als Eingabe für eine IQueueCallbackRead::OnRead-, IQueueCallbackWrite::OnWrite- oder IQueueCallbackDeviceIoControl::OnDeviceIoControl-Ereignisrückruffunktion empfängt, kann der Treiber die MarkCancelable-Methode aufrufen, um das Abbrechen der Anforderung zu aktivieren. Später kann der Treiber die IWDFIoRequest::UnmarkCancelable-Methode aufrufen, um das Abbrechen der Anforderung zu deaktivieren.

Bevor ein Treiber MarkCancelable aufruft, muss der Treiber die IRequestCallbackCancel::OnCancel-Methode implementieren.

Das Benutzermodustreiberframework (UMDF) lässt nur eine IRequestCallbackCancel::OnCancel-Methode pro Warteschlange zu. Wenn also ein Treiber MarkCancelable für Anforderungen aufruft, die einer bestimmten Warteschlange zugeordnet sind, damit das Framework diese Anforderungen abbrechen kann, muss der Treiber einen Zeiger auf die IRequestCallbackCancel-Schnittstelle für dasselbe Request-Callback-Objekt übergeben. Später übergibt das Framework zum Abbrechen jeder Anforderung einen Zeiger auf die IWDFIoRequest-Schnittstelle für die Anforderung in einem Aufruf der IRequestCallbackCancel::OnCancel-Methode dieses Request-Callback-Objekts.

Der Treiber muss IWDFIoRequest::Complete aufrufen, entweder über die IRequestCallbackCancel::OnCancel-Methode oder über den regulären E/A-Abschlusspfad.

Nachdem ein Treiber MarkCancelable aufgerufen hat, um das Abbrechen zu aktivieren, bleibt die Anforderung abbruchfähig, solange der Treiber über das Anforderungsobjekt verfügt, es sei denn, der Treiber ruft UnmarkCancelable auf, um den Abbruch zu deaktivieren.

Wenn der Treiber die IWDFIoRequest::ForwardToIoQueue-Methode aufruft, um die Anforderung an eine andere Warteschlange weiterzuleiten, gelten die folgenden Regeln:

Das Abbrechen von E/A-Anforderungen kann nicht aktiviert werden, wenn der Treiber die Anforderungen an eine andere Warteschlange weiterleitet.
In der Regel sollte der Treiber MarkCancelable nicht aufrufen, um das Abbrechen einer Anforderung vor dem Aufrufen von IWDFIoRequest::ForwardToIoQueue zu aktivieren. Alternativ kann der Treiber die Anforderung abbrechen lassen. Der Treiber muss dann jedoch UnmarkCancelable aufrufen, um das Abbrechen der Anforderung vor dem Aufrufen von IWDFIoRequest::ForwardToIoQueue zu deaktivieren.
Während sich die Anforderung in einer zweiten Warteschlange befindet, besitzt das Framework sie und kann sie abbrechen, ohne den Treiber zu benachrichtigen.
Nachdem das Framework die Anforderung aus der zweiten Warteschlange entfernt und die Anforderung an den Treiber übermittelt hat, kann der Treiber MarkCancelable aufrufen, um das Abbrechen zu aktivieren.

Beispiele

Im folgenden Codebeispiel wird eine Anforderung eingerichtet, damit sie vom Framework abgebrochen werden kann.

    //
    // The QueryInteraface should not fail.
    //
    (VOID)this->QueryInterface(_uuidof(IRequestCallbackCancel),
                               (PVOID *)&cancelCallback);

    pWdfRequest->MarkCancelable(cancelCallback);

Anforderungen

Anforderung	Wert
Ende des Supports	In UMDF 2.0 und höher nicht verfügbar.
Zielplattform	Desktop
UMDF-Mindestversion	1.5
Kopfzeile	wudfddi.h (include Wudfddi.h)
DLL	WUDFx.dll