Funzione WdfRequestProbeAndLockUserBufferForRead (wdfrequest.h)
[Si applica solo a KMDF]
Il metodo WdfRequestProbeAndLockUserBufferForRead verifica che il buffer in modalità utente di una richiesta di I/O sia leggibile e quindi blocca le pagine di memoria fisica del buffer in modo che i driver nello stack di driver possano leggere il buffer.
Sintassi
NTSTATUS WdfRequestProbeAndLockUserBufferForRead(
[in] WDFREQUEST Request,
[in] PVOID Buffer,
[in] size_t Length,
[out] WDFMEMORY *MemoryObject
);
Parametri
[in] Request
Handle per un oggetto richiesta del framework.
[in] Buffer
Puntatore al buffer di input della richiesta. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.
[in] Length
Lunghezza, in byte, del buffer di input della richiesta.
[out] MemoryObject
Puntatore a una posizione che riceve un handle per un oggetto memoria del framework che rappresenta il buffer di input dell'utente.
Valore restituito
WdfRequestProbeAndLockUserBufferForRead restituisce STATUS_SUCCESS se l'operazione ha esito positivo. In caso contrario, questo metodo potrebbe restituire uno dei valori seguenti:
| Codice restituito | Descrizione |
|---|---|
|
Un parametro di input non è valido. |
|
Il parametro Length è zero. |
|
La richiesta è già stata completata o non è valida. |
|
Il thread corrente non è l'autore della richiesta di I/O. |
|
Memoria insufficiente per completare l'operazione. |
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
Solo un driver di primo livello può chiamare il metodo WdfRequestProbeAndLockUserBufferForRead , perché il metodo richiede il contesto del processo che ha creato la richiesta di I/O.
Il buffer di input dell'utente contiene in genere informazioni da scrivere nel dispositivo.
Il buffer in modalità utente specificato dal parametro Buffer può essere il buffer recuperato da WdfRequestRetrieveUnsafeUserInputBuffer oppure può essere un buffer di input in modalità utente diverso. Ad esempio, un codice di controllo di I/O che usa il metodo di accesso memorizzato nel buffer potrebbe passare una struttura che contiene un puntatore incorporato a un buffer in modalità utente. In questo caso, il driver può usareWdfRequestProbeAndLockUserBufferForRead per ottenere un oggetto memoria per il buffer.
La lunghezza del buffer specificata dal parametro Length non deve essere maggiore delle dimensioni effettive del buffer. In caso contrario, i driver possono accedere alla memoria all'esterno del buffer, che rappresenta un rischio per la sicurezza.
Se WdfRequestProbeAndLockUserBufferForRead restituisce STATUS_SUCCESS, il driver riceve un handle a un oggetto memoria framework che rappresenta il buffer in modalità utente. Per accedere al buffer, il driver deve chiamare WdfMemoryGetBuffer.
L'oggetto memoria del framework viene rilasciato automaticamente quando il driver chiama WdfRequestComplete.
Per altre informazioni su WdfRequestProbeAndLockUserBufferForRead, vedere Accesso ai buffer dei dati nei driver Framework-Based.
Esempio
L'esempio di codice seguente è una versione abbreviata della funzione di callback EvtIoInCallerContext contenuta nel driver di esempio NONPNP . Quando la funzione di callback riceve una richiesta di I/O, determina se la richiesta contiene un codice di controllo di I/O con un tipo di trasferimento di METHOD_NEITHER. Se la richiesta contiene un codice di controllo di I/O di questo tipo, la funzione :
- Chiama WdfRequestRetrieveUnsafeUserInputBuffer e WdfRequestRetrieveUnsafeUserOutputBuffer per ottenere gli indirizzi virtuali dei buffer di lettura e scrittura della richiesta.
- Chiama WdfRequestProbeAndLockUserBufferForRead e WdfRequestProbeAndLockUserBufferForWrite per eseguire il probe e bloccare i buffer e ottenere un handle a un oggetto memoria framework che rappresenta ogni buffer.
VOID
NonPnpEvtIoInCallerContext(
IN WDFDEVICE Device,
IN WDFREQUEST Request
)
{
NTSTATUS status = STATUS_SUCCESS;
PREQUEST_CONTEXT reqContext = NULL;
WDF_OBJECT_ATTRIBUTES attributes;
WDF_REQUEST_PARAMETERS params;
size_t inBufLen, outBufLen;
PVOID inBuf, outBuf;
WDF_REQUEST_PARAMETERS_INIT(¶ms);
WdfRequestGetParameters(
Request,
¶ms
);
//
// Check to see whether the driver received a METHOD_NEITHER I/O control code.
// If not, just send the request back to the framework.
//
if(!(params.Type == WdfRequestTypeDeviceControl &&
params.Parameters.DeviceIoControl.IoControlCode ==
IOCTL_NONPNP_METHOD_NEITHER)) {
status = WdfDeviceEnqueueRequest(
Device,
Request
);
if( !NT_SUCCESS(status) ) {
goto End;
}
return;
}
//
// The I/O control code is METHOD_NEITHER.
// First, retrieve the virtual addresses of
// the input and output buffers.
//
status = WdfRequestRetrieveUnsafeUserInputBuffer(
Request,
0,
&inBuf,
&inBufLen
);
if(!NT_SUCCESS(status)) {
goto End;
}
status = WdfRequestRetrieveUnsafeUserOutputBuffer(
Request,
0,
&outBuf,
&outBufLen
);
if(!NT_SUCCESS(status)) {
goto End;
}
//
// Next, allocate context space for the request, so that the
// driver can store handles to the memory objects that will
// be created for input and output buffers.
//
WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&attributes,
REQUEST_CONTEXT);
status = WdfObjectAllocateContext(
Request,
&attributes,
&reqContext
);
if(!NT_SUCCESS(status)) {
goto End;
}
//
// Next, probe and lock the read and write buffers.
//
status = WdfRequestProbeAndLockUserBufferForRead(
Request,
inBuf,
inBufLen,
&reqContext->InputMemoryBuffer
);
if(!NT_SUCCESS(status)) {
goto End;
}
status = WdfRequestProbeAndLockUserBufferForWrite(
Request,
outBuf,
outBufLen,
&reqContext->OutputMemoryBuffer
);
if(!NT_SUCCESS(status)) {
goto End;
}
//
// Finally, return the request to the framework.
//
status = WdfDeviceEnqueueRequest(
Device,
Request
);
if(!NT_SUCCESS(status)) {
goto End;
}
return;
End:
WdfRequestComplete(
Request,
status
);
return;
}
Requisiti
| Requisito | Valore |
|---|---|
| Piattaforma di destinazione | Universale |
| Versione KMDF minima | 1.0 |
| Intestazione | wdfrequest.h (include Wdf.h) |
| Libreria | Wdf01000.sys (vedere Controllo delle versioni della libreria framework). |
| IRQL | PASSIVE_LEVEL |
| Regole di conformità DDI | DriverCreate(kmdf), InvalidReqAccess(kmdf), InvalidReqAccessLocal(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf) |