Funzione WdfRequestUnmarkCancelable (wdfrequest.h)

[Si applica a KMDF e UMDF]

Il metodo WdfRequestUnmarkCancelable disabilita l'annullamento di una richiesta di I/O specificata.

Sintassi

NTSTATUS WdfRequestUnmarkCancelable(
  [in] WDFREQUEST Request
);

Parametri

[in] Request

Handle per un oggetto richiesta del framework.

Valore restituito

WdfRequestUnmarkCancelable restituisce STATUS_SUCCESS se l'operazione ha esito positivo. In caso contrario, questo metodo potrebbe restituire uno dei valori seguenti:

Codice restituito	Descrizione
STATUS_INVALID_PARAMETER	Un parametro di input non è valido o la richiesta non è già annullabile.
STATUS_INVALID_DEVICE_REQUEST	Il driver non è proprietario della richiesta.
STATUS_CANCELLED	La richiesta è stata annullata.

 

Questo metodo potrebbe anche restituire altri valori NTSTATUS.

Se il driver fornisce un handle di oggetto non valido, si verifica un controllo di bug.

Commenti

Un driver può chiamare WdfRequestUnmarkCancelable per disabilitare l'annullamento di una richiesta di I/O, se il driver precedentemente chiamato WdfRequestMarkCancelable o WdfRequestMarkCancelableEx per abilitare l'annullamento della richiesta.

Se WdfRequestUnmarkCancelable restituisce un valore diverso da STATUS_CANCELLED, la funzione di callback EvtRequestCancel del driver non verrà chiamata per la richiesta.

Se il driver precedentemente denominato WdfRequestMarkCancelable o WdfRequestMarkCancelableEx, la funzione di callback EvtRequestCancel del driver può chiamare WdfRequestComplete con un parametro Status di STATUS_CANCELLED. La funzione di callback EvtRequestCancel non deve chiamare WdfRequestUnmarkCancelable. Se il driver chiama WdfRequestComplete all'esterno della relativa funzione di callback EvtRequestCancel , il driver deve prima chiamare WdfRequestUnmarkCancelable.

Tuttavia, il driver non deve chiamare WdfRequestUnmarkCancelable dopo che EvtRequestCancel chiama WdfRequestComplete. Nella sezione Esempio seguente l'esempio archivia una copia locale dell'handle della richiesta e la cancella quando la funzione di callback EvtRequestCancel chiama WdfRequestComplete. Il driver non chiama WdfRequestUnmarkCancelable se la copia locale dell'handle di richiesta è stata cancellata. In questo esempio viene usata la sincronizzazione automatica del framework per sincronizzare le funzioni di callback.

Si noti che la chiamata a WdfObjectReference per aggiungere un riferimento aggiuntivo all'oggetto richiesta non consente al driver di chiamare WdfRequestUnmarkCancelable dopo che la funzione di callback EvtRequestCancel del driver chiama WdfRequestComplete.

Se WdfRequestUnmarkCancelable restituisce STATUS_CANCELLED e quindi EvtRequestCancel completa la richiesta, il driver non deve successivamente utilizzare l'oggetto richiesta.

Se WdfRequestUnmarkCancelable restituisce STATUS_CANCELLED, il driver non deve completare la richiesta prima che il framework chiami EvtRequestCancel. In caso contrario, il framework potrebbe chiamare EvtRequestCancel del driver con una richiesta non valida. Per esempi di codice correlati, vedere IWDFIoRequest::UnmarkCancelable.

Per altre informazioni su WdfRequestUnmarkCancelable, vedere Annullamento delle richieste di I/O.

Esempio

L'esempio di codice seguente fornisce versioni semplificate delle funzioni di callback EvtIoRead, EvtRequestCancel e EvtTimerFunc contenute nel driver di esempio ECHO . Questo esempio illustra come chiamare WdfRequestMarkCancelable, WdfRequestUnmarkCancelable e WdfRequestComplete in un driver che usa la sincronizzazione automatica del framework. L'esempio ECHO usa la sincronizzazione a livello di dispositivo.

Se il driver non usa la sincronizzazione automatica del framework, vedere i due esempi in IWDFIoRequest::UnmarkCancelable. Durante la scrittura per un driver UMDF, questi esempi illustrano le tecniche che è possibile usare per gestire la sincronizzazione tra il callback di annullamento e un altro thread che chiama la routine Unmark .

VOID
  EchoEvtIoRead(
    IN WDFQUEUE  Queue,
    IN WDFREQUEST  Request,
    IN size_t  Length
    )
{
    PQUEUE_CONTEXT queueContext = QueueGetContext(Queue);

    // Prepare for read operation here.
    // (See the Echo sample driver for details.) 
 ...
    // Enable cancellation.
    WdfRequestMarkCancelable(
                             Request,
                             EchoEvtRequestCancel
                             );

    // Save the request handle. We'll clear it after
    // we call WdfRequestComplete.
    queueContext->CurrentRequest = Request;
    return
}


VOID
 EchoEvtRequestCancel(
    IN WDFREQUEST  Request
    )
{
    PQUEUE_CONTEXT queueContext = 
        QueueGetContext(WdfRequestGetIoQueue(Request));

    WdfRequestComplete(
                       Request,
                       STATUS_CANCELLED,
     );
    // Clear the request handle so EchEvtTimerFunc will
    // know that we called WdfRequestComplete.
    queueContext->CurrentRequest = NULL;

    return;
}


VOID
  EchoEvtTimerFunc(
    IN WDFTIMER  Timer
    )
{
    NTSTATUS  Status;
    WDFREQUEST  Request;
    WDFQUEUE  queue;
    PQUEUE_CONTEXT  queueContext;

    // Retrieve our saved copy of the request handle.
    queue = WdfTimerGetParentObject(Timer);
    queueContext = QueueGetContext(queue);
    Request = queueContext->CurrentRequest;

    // We cannot call WdfRequestUnmarkCancelable
    // after a request completes, so check here to see
    // if EchoEvtRequestCancel cleared our saved
    // request handle. 
    if( Request != NULL ) {
        Status = WdfRequestUnmarkCancelable(Request);
        if(Status != STATUS_CANCELLED) {
            queueContext->CurrentRequest = NULL;
            Status = queueContext->CurrentStatus;
            WdfRequestComplete(
                               Request,
                               Status
                               );
        }
    }

    return;
}

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Versione KMDF minima	1.0
Versione UMDF minima	2,0
Intestazione	wdfrequest.h (include Wdf.h)
Libreria	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
Regole di conformità DDI	CompleteCanceledReq(kmdf), DeferredRequestCompleted(kmdf), DriverCreate(kmdf), EvtIoStopCancel(kmdf), InvalidReqAccess(kmdf), InvalidReqAccessLocal(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), MarkCancOnCancReqLocal(kmdf), ReqIsCancOnCancReq(kmdf), ReqMarkCancelableSend(kmdf), ReqNotCanceledLocal(kmdf)

Vedi anche

EvtRequestCancel

WdfRequestComplete

WdfRequestMarkCancelable

WdfRequestMarkCancelableEx