Condividi tramite


PIBIO_SENSOR_CONTROL_UNIT_PRIVILEGED_FN funzione di callback (winbio_adapter.h)

Chiamato da Windows Biometric Framework per eseguire un'operazione di controllo definita dal fornitore che richiede privilegi elevati. Chiamare la funzione SensorAdapterControlUnit per eseguire un'operazione di controllo definita dal fornitore che non richiede privilegi elevati.

Sintassi

PIBIO_SENSOR_CONTROL_UNIT_PRIVILEGED_FN PibioSensorControlUnitPrivilegedFn;

HRESULT PibioSensorControlUnitPrivilegedFn(
  [in, out] PWINBIO_PIPELINE Pipeline,
  [in]      ULONG ControlCode,
  [in]      PUCHAR SendBuffer,
  [in]      SIZE_T SendBufferSize,
  [in]      PUCHAR ReceiveBuffer,
  [in]      SIZE_T ReceiveBufferSize,
  [out]     PSIZE_T ReceiveDataSize,
  [out]     PULONG OperationStatus
)
{...}

Parametri

[in, out] Pipeline

Puntatore a una struttura WINBIO_PIPELINE associata all'unità biometrica che esegue l'operazione.

[in] ControlCode

Valore ULONG che specifica l'operazione definita dal fornitore da eseguire.

[in] SendBuffer

Puntatore a un buffer contenente le informazioni sul controllo inviate all'adattatore del sensore. Il formato e il contenuto del buffer sono definiti dal fornitore.

[in] SendBufferSize

Dimensioni, in byte, del buffer specificato dal parametro SendBuffer .

[in] ReceiveBuffer

Puntatore a un buffer che riceve le informazioni restituite dall'adattatore del sensore in risposta all'operazione di controllo. Il formato del buffer è definito dal fornitore.

[in] ReceiveBufferSize

Dimensioni, in byte, del buffer specificato dal parametro ReceiveBuffer .

[out] ReceiveDataSize

Puntatore a una variabile che riceve le dimensioni, in byte, dei dati scritti nel buffer specificato dal parametro ReceiveBuffer .

[out] OperationStatus

Puntatore a una variabile che riceve un codice di stato definito dal fornitore che specifica il risultato dell'operazione di controllo.

Valore restituito

Se la funzione ha esito positivo, restituisce S_OK. Se la funzione ha esito negativo, deve restituire uno dei valori HRESULT seguenti per indicare l'errore.

Codice restituito Descrizione
E_POINTER
Un argomento puntatore obbligatorio è NULL.
E_INVALIDARG
Le dimensioni o il formato del buffer specificato dal parametro SendBuffer non sono corretti oppure il valore specificato nel parametro ControlCode non viene riconosciuto dall'adattatore.
E_NOT_SUFFICIENT_BUFFER
Il buffer specificato dal parametro ReceiveBuffer è troppo piccolo.
WINBIO_E_CANCELED
L'operazione è stata annullata.
WINBIO_E_DEVICE_FAILURE
Si è verificato un errore hardware.
WINBIO_E_INVALID_CONTROL_CODE
Il valore specificato nel parametro ControlCode non viene riconosciuto dall'adapter.
Nota A partire da Windows 8, usare solo E_INVALIDARG per segnalare questa condizione.
 

Commenti

L'implementazione di questa funzione deve essere identica all'implementazione della funzione SensorAdapterControlUnit , ad eccezione del fatto che per eseguire le operazioni specificate dal parametro ControlCode sono necessari privilegi elevati. L'utente è responsabile della definizione delle operazioni e della scelta dei privilegi elevati.

Questa funzione deve controllare il valore del parametro ReceiveBufferSize per essere certi che il buffer specificato dal parametro ReceiveBuffer sia sufficientemente grande da contenere i dati restituiti.

Esempio

Lo pseudocodice seguente mostra una possibile implementazione di questa funzione. L'esempio non viene compilato. Devi adattarla al tuo scopo.

//////////////////////////////////////////////////////////////////////////////////////////
//
// SensorAdapterControlUnitPrivileged
//
// Purpose:
//      Performs a vendor-defined control operation that requires elevated 
//      privilege.
//
// Parameters:
//      Pipeline            - Pointer to a WINBIO_PIPELINE structure associated 
//                            with the biometric unit performing the operation
//      ControlCode         - Specifies the vendor-defined operation to perform
//      SendBuffer          - Contains the control information sent to the 
//                            sensor adapter
//      SendBufferSize      - Size, in bytes, of the buffer specified by the 
//                            SendBuffer parameter
//      ReceiveBuffer       - Receives information returned by the sensor adapter
//                            in response to the control operation
//      ReceiveBufferSize   - Size, in bytes, of the buffer specified by the 
//                            ReceiveBuffer parameter.
//      ReceiveDataSize     - Receives the size, in bytes, of the data written to 
//                            the buffer specified by the ReceiveBuffer parameter
//      OperationStatus     - Receives a vendor-defined status code that specifies 
//                            the outcome of the control operation.
//
static HRESULT
WINAPI
SensorAdapterControlUnitPrivileged(
    __inout PWINBIO_PIPELINE Pipeline,
    __in ULONG ControlCode,
    __in_bcount(SendBufferSize) PUCHAR SendBuffer,
    __in SIZE_T SendBufferSize,
    __in_bcount(ReceiveBufferSize) PUCHAR ReceiveBuffer,
    __in SIZE_T ReceiveBufferSize,
    __out SIZE_T *ReceiveDataSize,
    __out ULONG *OperationStatus
    )
{
    HRESULT hr = S_OK;
    BOOL result = TRUE;

    // Verify that pointer arguments are not NULL.
    if (!ARGUMENT_PRESENT(Pipeline) ||
        !ARGUMENT_PRESENT(SendBuffer) ||
        !ARGUMENT_PRESENT(ReceiveBuffer) ||
        !ARGUMENT_PRESENT(ReceiveDataSize) ||
        !ARGUMENT_PRESENT(OperationStatus))
    {
        hr = E_POINTER;
        goto cleanup;
    }

    // Retrieve the context from the pipeline.
    PWINBIO_SENSOR_CONTEXT sensorContext = 
                 (PWINBIO_SENSOR_CONTEXT)Pipeline->SensorContext;

    // Verify the state of the pipeline.
    if (sensorContext == NULL || 
        Pipeline->SensorHandle == INVALID_HANDLE_VALUE)
    {
        hr = WINBIO_E_INVALID_DEVICE_STATE;
        goto cleanup;
    }

    switch (ControlCode)
    {
    case MY_PRIVILEGED_CTRL_CODE_P1:
        {
            CTRL_CODE_P1_SEND_BUFFER *sendBuffer = (CTRL_CODE_P1_SEND_BUFFER*)SendBuffer;

            // Verify the size of the send buffer.
            if (SendBufferSize < sizeof(CTRL_CODE_P1_SEND_BUFFER))
            {
                hr = E_INVALIDARG;
                break;
            }

            // Perform any other checks that may be required on the buffer 
            // contents. Return E_INVALIDARG if any of the checks fail.
            if (sendBuffer->SomeField != SomeSpecialValue ||
                sendBuffer->SomeOtherField != SomeOtherSpecialValue)
            {
                hr = E_INVALIDARG;
                break;
            }

            if (ReceiveBufferSize < sizeof(CTRL_CODE_P1_RECEIVE_BUFFER))
            {
                hr = E_NOT_SUFFICIENT_BUFFER;
                break;
            }
        }

        // Fall through and perform the control operation after the switch
        // statement. Alternatively, depending on your requirements, you can 
        // perform the control operation here.
        break;

    case MY_PRIVILEGED_CTRL_CODE_P2:
        // Continue testing for other non-privileged control codes that your
        // adapter supports.
        {
            CTRL_CODE_P2_SEND_BUFFER *sendBuffer = (CTRL_CODE_P2_SEND_BUFFER*)SendBuffer;

            // Verify the size of the send buffer.
            if (SendBufferSize < sizeof(CTRL_CODE_P2_SEND_BUFFER))
            {
                hr = E_INVALIDARG;
                break;
            }

            // Perform any other checks that may be required on the buffer 
            // contents. Return E_INVALIDARG if any of the checks fail.
            if (sendBuffer->SomeField != SomeSpecialValue ||
                sendBuffer->SomeOtherField != SomeOtherSpecialValue)
            {
                hr = E_INVALIDARG;
                break;
            }

            if (ReceiveBufferSize < sizeof(CTRL_CODE_P2_RECEIVE_BUFFER))
            {
                hr = E_NOT_SUFFICIENT_BUFFER;
                break;
            }
        }
        break;

    default:
        // All unrecognized control code values should return an error.
        hr = WINBIO_E_INVALID_CONTROL_CODE;
        break;
    }
    if (FAILED(hr))
    {
        goto cleanup;
    }

    // If control code validation succeeds, perform the control operation. This
    // example assumes that the driver performs overlapped I/O and that a properly 
    // initialized OVERLAPPED structure is contained in the sensor context.
    result = DeviceIoControl(
                Pipeline->SensorHandle,
                ControlCode,
                SendBuffer,
                (DWORD)SendBufferSize,
                ReceiveBuffer,
                (DWORD)ReceiveBufferSize,
                (LPDWORD)ReceiveDataSize,
                &sensorContext->Overlapped
                );
    if (result == FALSE && GetLastError() == ERROR_IO_PENDING)
    {
        SetLastError(ERROR_SUCCESS);

        result = GetOverlappedResult(
                    Pipeline->SensorHandle,
                    &sensorContext->Overlapped,
                    (LPDWORD)ReceiveDataSize,
                    TRUE
                    );
    }
    *OperationStatus = GetLastError();

    if (!result)
    {
        hr = _AdapterGetHresultFromWin32(*OperationStatus);
    }

cleanup:

    return hr;
}

Requisiti

Requisito Valore
Client minimo supportato Windows 7 [solo app desktop]
Server minimo supportato Windows Server 2008 R2 [solo app desktop]
Piattaforma di destinazione Windows
Intestazione winbio_adapter.h (includere Winbio_adapter.h)

Vedi anche

Funzioni plug-in

SensorAdapterControlUnit

WinBioControlUnitPrivileged