Freigeben über


PIBIO_SENSOR_CONTROL_UNIT_PRIVILEGED_FN Rückruffunktion (winbio_adapter.h)

Wird vom Windows Biometric Framework aufgerufen, um einen vom Hersteller definierten Steuerungsvorgang auszuführen, der erhöhte Berechtigungen erfordert. Rufen Sie die SensorAdapterControlUnit-Funktion auf, um einen vom Anbieter definierten Steuerungsvorgang auszuführen, der keine erhöhten Berechtigungen erfordert.

Syntax

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
)
{...}

Parameter

[in, out] Pipeline

Zeiger auf eine WINBIO_PIPELINE Struktur, die der biometrischen Einheit zugeordnet ist, die den Vorgang ausführt.

[in] ControlCode

Ein ULONG-Wert , der den vom Anbieter definierten Vorgang angibt, der ausgeführt werden soll.

[in] SendBuffer

Zeiger auf einen Puffer, der die an den Sensoradapter gesendeten Steuerinformationen enthält. Das Format und der Inhalt des Puffers sind vom Anbieter definiert.

[in] SendBufferSize

Größe des durch den SendBuffer-Parameter angegebenen Puffers in Bytes.

[in] ReceiveBuffer

Zeiger auf einen Puffer, der vom Sensoradapter als Reaktion auf den Steuerungsvorgang zurückgegebene Informationen empfängt. Das Format des Puffers ist vom Anbieter definiert.

[in] ReceiveBufferSize

Größe des durch den ReceiveBuffer-Parameter angegebenen Puffers in Byte.

[out] ReceiveDataSize

Zeiger auf eine Variable, die die Größe der Daten in Byte empfängt, die in den durch den ReceiveBuffer-Parameter angegebenen Puffer geschrieben werden.

[out] OperationStatus

Zeiger auf eine Variable, die einen vom Anbieter definierten status Code empfängt, der das Ergebnis des Steuerungsvorgangs angibt.

Rückgabewert

Wenn die Funktion erfolgreich ist, wird S_OK zurückgegeben. Wenn die Funktion fehlschlägt, muss sie einen der folgenden HRESULT-Werte zurückgeben, um den Fehler anzugeben.

Rückgabecode Beschreibung
E_POINTER
Ein obligatorisches Zeigerargument ist NULL.
E_INVALIDARG
Die Größe oder das Format des durch den SendBuffer-Parameter angegebenen Puffers ist nicht korrekt, oder der im ControlCode-Parameter angegebene Wert wird vom Adapter nicht erkannt.
E_NOT_SUFFICIENT_BUFFER
Der vom Parameter ReceiveBuffer angegebene Puffer ist zu klein.
WINBIO_E_CANCELED
Der Vorgang wurde abgebrochen.
WINBIO_E_DEVICE_FAILURE
Es ist ein Hardwarefehler aufgetreten.
WINBIO_E_INVALID_CONTROL_CODE
Der im ControlCode-Parameter angegebene Wert wird vom Adapter nicht erkannt.
Hinweis Verwenden Sie ab Windows 8 nur E_INVALIDARG, um diese Bedingung zu signalisieren.
 

Hinweise

Ihre Implementierung dieser Funktion sollte mit der Implementierung der SensorAdapterControlUnit-Funktion identisch sein, mit der Ausnahme, dass erhöhte Berechtigungen erforderlich sind, um die vom ControlCode-Parameter angegebenen Vorgänge auszuführen. Sie sind dafür verantwortlich, die Vorgänge zu definieren und zu entscheiden, welche erhöhte Berechtigungen erfordern.

Diese Funktion muss den Wert des Parameters ReceiveBufferSize überprüfen, um sicherzustellen, dass der vom ReceiveBuffer-Parameter angegebene Puffer groß genug ist, um die zurückgegebenen Daten aufzunehmen.

Beispiele

Der folgende Pseudocode zeigt eine mögliche Implementierung dieser Funktion. Das Beispiel wird nicht kompiliert. Sie müssen es an Ihren Zweck anpassen.

//////////////////////////////////////////////////////////////////////////////////////////
//
// 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;
}

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows 7 [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows Server 2008 R2 [nur Desktop-Apps]
Zielplattform Windows
Kopfzeile winbio_adapter.h (Winbio_adapter.h einschließen)

Weitere Informationen

Plug-In-Funktionen

SensorAdapterControlUnit

WinBioControlUnitPrivileged