PIBIO_ENGINE_CONTROL_UNIT_FN Rückruffunktion (winbio_adapter.h)

Vom Windows-Biometrischen Framework aufgerufen, um einen vom Hersteller definierten Kontrollvorgang auszuführen, der keine erhöhten Berechtigungen erfordert. Rufen Sie die EngineAdapterControlUnitPrivileged-Funktion auf, um einen vom Anbieter definierten Steuerelementvorgang auszuführen, der erhöhte Berechtigungen erfordert.

Syntax

PIBIO_ENGINE_CONTROL_UNIT_FN PibioEngineControlUnitFn;

HRESULT PibioEngineControlUnitFn(
  [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
)
{...}

Die Parameter

[in, out] Pipeline

Zeigen Sie 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

Zeigen Sie auf einen Puffer, der die Steuerelementinformationen enthält, die an den Moduladapter gesendet werden. 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

Zeigen Sie auf einen Puffer, der informationen empfängt, die vom Moduladapter als Reaktion auf den Steuerungsvorgang zurückgegeben werden. Das Format des Puffers ist vom Anbieter definiert.

[in] ReceiveBufferSize

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

[out] ReceiveDataSize

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

[out] OperationStatus

Zeiger auf eine Variable, die einen vom Anbieter definierten Statuscode empfängt, der das Ergebnis des Steuerelementvorgangs 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.

Bemerkungen

Die Implementierung dieser Funktion sollte mit der Implementierung der EngineAdapterControlUnitPrivileged-Funktion identisch sein, mit der Ausnahme, dass erhöhte Berechtigungen nicht 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 keine erhöhten Berechtigungen erfordern.

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

Examples

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

//////////////////////////////////////////////////////////////////////////////////////////
//
// EngineAdapterControlUnit
//
// Purpose:
//      Performs a vendor-defined control operation that does not require 
//      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 
//                            engine adapter
//      SendBufferSize      - Size, in bytes, of the buffer specified by the 
//                            SendBuffer parameter
//      ReceiveBuffer       - Receives information returned by the engine 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
EngineAdapterControlUnit(
    __inout 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
    )
{
    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_ENGINE_CONTEXT engineContext = 
           (PWINBIO_ENGINE_CONTEXT)Pipeline->EngineContext;

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

    switch (ControlCode)
    {
    case MY_NONPRIVILEGED_CTRL_CODE_NP1:
        {
            CTRL_CODE_NP1_SEND_BUFFER *sendBuffer = (CTRL_CODE_NP1_SEND_BUFFER*)SendBuffer;

            // Verify the size of the send buffer.
            if (SendBufferSize < sizeof(CTRL_CODE_NP1_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_NP1_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_NONPRIVILEGED_CTRL_CODE_NP2:
        // Continue testing for other non-privileged control codes that your
        // adapter supports.
        {
            CTRL_CODE_NP2_SEND_BUFFER *sendBuffer = (CTRL_CODE_NP2_SEND_BUFFER*)SendBuffer;

            // Verify the size of the send buffer.
            if (SendBufferSize < sizeof(CTRL_CODE_NP2_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_NP2_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 your adapter context structure contains an open
    // handle to a hardware driver. It also assumes that the driver performs
    // overlapped I/O and that a properly initialized OVERLAPPED structure is
    // contained in the engine context.
    result = DeviceIoControl(
                Pipeline->EngineHandle,
                ControlCode,
                SendBuffer,
                (DWORD)SendBufferSize,
                ReceiveBuffer,
                (DWORD)ReceiveBufferSize,
                (LPDWORD)ReceiveDataSize,
                &Pipeline->EngineContext->Overlapped
                );
    if (result == FALSE && GetLastError() == ERROR_IO_PENDING)
    {
        SetLastError(ERROR_SUCCESS);

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

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

cleanup:

    return hr;
}

Anforderungen

Siehe auch

EngineAdapterControlUnitPrivileged

Plug-In-Funktionen