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
STATUS_INVALID_PARAMETER
Un parametro di input non è valido.
STATUS_INVALID_USER_BUFFER
Il parametro Length è zero.
STATUS_INVALID_DEVICE_REQUEST
La richiesta è già stata completata o non è valida.
STATUS_ACCESS_VIOLATION
Il thread corrente non è l'autore della richiesta di I/O.
STATUS_INSUFFICIENT_RESOURCES
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 :

  1. Chiama WdfRequestRetrieveUnsafeUserInputBuffer e WdfRequestRetrieveUnsafeUserOutputBuffer per ottenere gli indirizzi virtuali dei buffer di lettura e scrittura della richiesta.
  2. 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(&params);
    WdfRequestGetParameters(
                            Request,
                            &params
                            );

    //
    // 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)

Vedi anche

WdfMemoryGetBuffer

WdfRequestProbeAndLockUserBufferForWrite

WdfRequestRetrieveUnsafeUserInputBuffer