Bagikan melalui

fungsi panggilan balik PIBIO_ENGINE_CONTROL_UNIT_FN (winbio_adapter.h)

  • Artikel

Dipanggil oleh Windows Biometric Framework untuk melakukan operasi kontrol yang ditentukan vendor yang tidak memerlukan hak istimewa yang ditingkatkan. Panggil fungsi EngineAdapterControlUnitPrivileged untuk melakukan operasi kontrol yang ditentukan vendor yang memerlukan hak istimewa yang ditinggikan.

Sintaks

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

Parameter

[in, out] Pipeline

Penunjuk ke struktur WINBIO_PIPELINE yang terkait dengan unit biometrik yang melakukan operasi.

[in] ControlCode

Nilai ULONG yang menentukan operasi yang ditentukan vendor untuk dilakukan.

[in] SendBuffer

Penunjuk ke buffer yang berisi informasi kontrol yang dikirim ke adaptor mesin. Format dan konten buffer ditentukan vendor.

[in] SendBufferSize

Ukuran, dalam byte, dari buffer yang ditentukan oleh parameter SendBuffer .

[in] ReceiveBuffer

Penunjuk ke buffer yang menerima informasi yang dikembalikan oleh adaptor mesin sebagai respons terhadap operasi kontrol. Format buffer ditentukan vendor.

[in] ReceiveBufferSize

Ukuran, dalam byte, dari buffer yang ditentukan oleh parameter ReceiveBuffer .

[out] ReceiveDataSize

Penunjuk ke variabel yang menerima ukuran, dalam byte, dari data yang ditulis ke buffer yang ditentukan oleh parameter ReceiveBuffer .

[out] OperationStatus

Penunjuk ke variabel yang menerima kode status yang ditentukan vendor yang menentukan hasil operasi kontrol.

Mengembalikan nilai

Jika fungsi berhasil, fungsi akan mengembalikan S_OK. Jika fungsi gagal, fungsi harus mengembalikan salah satu nilai HRESULT berikut untuk menunjukkan kesalahan.

Menampilkan kode Deskripsi
E_POINTER
 Argumen pointer wajib adalah NULL.
E_INVALIDARG
 Ukuran atau format buffer yang ditentukan oleh parameter SendBuffer tidak benar, atau nilai yang ditentukan dalam parameter ControlCode tidak dikenali oleh adaptor.
E_NOT_SUFFICIENT_BUFFER
 Buffer yang ditentukan oleh parameter ReceiveBuffer terlalu kecil.
WINBIO_E_CANCELED
 Operasi dibatalkan.
WINBIO_E_DEVICE_FAILURE
 Terjadi kegagalan perangkat keras.
WINBIO_E_INVALID_CONTROL_CODE
 Nilai yang ditentukan dalam parameter ControlCode tidak dikenali oleh adaptor.
Catatan Dimulai dengan Windows 8, gunakan hanya E_INVALIDARG untuk memberi sinyal kondisi ini.
 

Keterangan

Implementasi Anda dari fungsi ini harus identik dengan implementasi fungsi EngineAdapterControlUnitPrivileged Kecuali bahwa hak istimewa yang ditinggikan tidak diperlukan untuk melakukan operasi yang ditentukan oleh parameter ControlCode . Anda bertanggung jawab untuk mendefinisikan operasi dan memutuskan mana yang tidak akan memerlukan hak istimewa yang ditingkatkan.

Fungsi ini harus memeriksa nilai parameter ReceiveBufferSize untuk memastikan bahwa buffer yang ditentukan oleh parameter ReceiveBuffer cukup besar untuk menahan data yang dikembalikan.

Contoh

Pseudocode berikut menunjukkan salah satu kemungkinan implementasi fungsi ini. Contoh tidak dikompilasi. Kau harus menyesuaikannya sesuai dengan tujuanmu.

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

Persyaratan

Persyaratan Nilai
Klien minimum yang didukung Windows 7 [hanya aplikasi desktop]
Server minimum yang didukung Windows Server 2008 R2 [hanya aplikasi desktop]
Target Platform Windows
Header winbio_adapter.h (termasuk Winbio_adapter.h)

Lihat juga

EngineAdapterControlUnitPrivileged

Fungsi Plug-in