Bagikan melalui

fungsi panggilan balik PIBIO_STORAGE_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 StorageAdapterControlUnitPrivileged untuk melakukan operasi kontrol yang ditentukan vendor yang memerlukan hak istimewa yang ditinggikan.

Sintaks

PIBIO_STORAGE_CONTROL_UNIT_FN PibioStorageControlUnitFn;

HRESULT PibioStorageControlUnitFn(
  [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

Arahkan 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 penyimpanan. Format dan konten buffer ditentukan vendor.

[in] SendBufferSize

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

[in] ReceiveBuffer

Arahkan ke buffer yang menerima informasi yang dikirim oleh adaptor penyimpanan 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.

Nilai kembali

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 StorageAdapterControlUnitPrivileged Anda 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 satu kemungkinan implementasi fungsi ini. Contoh tidak dikompilasi. Anda harus menyesuaikannya agar sesuai dengan tujuan Anda.

/////////////////////////////////////////////////////////////////////////////////////////
//
// StorageAdapterControlUnit
//
// 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 
//                            storage adapter.
//      SendBufferSize      - Size, in bytes, of the buffer specified by the 
//                            SendBuffer parameter.
//      ReceiveBuffer       - Receives information returned by the storage 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
StorageAdapterControlUnit(
    __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_STORAGE_CONTEXT storageContext = 
           (PWINBIO_STORAGE_CONTEXT)Pipeline->StorageContext;

    // Verify the state of the pipeline.
    if (storageContext == NULL ||
        Pipeline->StorageHandle == 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 has put an open handle to a storage 
    // device in the Pipeline structure. It also assumes that the driver performs
    // overlapped I/O and that a properly initialized OVERLAPPED structure is
    // contained in the storage context.
    result = DeviceIoControl(
                Pipeline->StorageHandle,
                ControlCode,
                SendBuffer,
                (DWORD)SendBufferSize,
                ReceiveBuffer,
                (DWORD)ReceiveBufferSize,
                (LPDWORD)ReceiveDataSize,
                &storageContext->Overlapped
                );
    if (result == FALSE && GetLastError() == ERROR_IO_PENDING)
    {
        SetLastError(ERROR_SUCCESS);

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

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

cleanup:

    return hr;
}

Persyaratan

   
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

Fungsi Plug-in

StorageAdapterControlUnitPrivileged