Bagikan melalui

fungsi panggilan balik PIBIO_ENGINE_CONTROL_UNIT_PRIVILEGED_FN (winbio_adapter.h)

  • Artikel

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

Sintaks

PIBIO_ENGINE_CONTROL_UNIT_PRIVILEGED_FN PibioEngineControlUnitPrivilegedFn;

HRESULT PibioEngineControlUnitPrivilegedFn(
  [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 EngineAdapterControlUnit Anda kecuali bahwa hak istimewa yang ditinggikan diperlukan untuk melakukan operasi yang ditentukan oleh parameter ControlCode . Anda bertanggung jawab untuk mendefinisikan operasi dan memutuskan mana yang 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 satu kemungkinan implementasi fungsi ini. Contoh tidak dikompilasi. Anda harus menyesuaikannya agar sesuai dengan tujuan Anda.

///////////////////////////////////////////////////////////////////////////////
//
// EngineAdapterControlUnitPrivileged
//
// 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 
//                            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
EngineAdapterControlUnitPrivileged(
    __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_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 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 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.
    if (FAILED(hr))
    {
        goto cleanup;
    }
    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

EngineAdapterControlUnit

Fungsi Plug-in