PIBIO_STORAGE_CONTROL_UNIT_FN回呼函式 (winbio_adapter.h)
由 Windows 生物特徵辨識架構呼叫，以執行不需要提高許可權的廠商定義控制作業。 呼叫 StorageAdapterControlUnitPrivileged 函式，以執行需要提高許可權的廠商定義控制作業。
語法
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
)
{...}
參數
[in, out] Pipeline
與執行作業之生物特徵辨識單位相關聯的 WINBIO_PIPELINE 結構的指標。
[in] ControlCode
ULONG值，指定要執行的廠商定義作業。
[in] SendBuffer
緩衝區的指標，其中包含傳送至儲存配接器的控制項資訊。 緩衝區的格式和內容是廠商定義的。
[in] SendBufferSize
SendBuffer參數所指定的緩衝區大小，以位元組為單位。
[in] ReceiveBuffer
接收儲存體配接器所傳送資訊的緩衝區指標，以回應控制作業。 緩衝區的格式是廠商定義的。
[in] ReceiveBufferSize
ReceiveBuffer參數所指定的緩衝區大小，以位元組為單位。
[out] ReceiveDataSize
接收寫入 ReceiveBuffer 參數所指定緩衝區之資料大小之位元組之變數的指標。
[out] OperationStatus
接收廠商定義狀態碼的變數指標，指定控制作業的結果。
傳回值
如果函式成功，則會傳回S_OK。 如果函式失敗，它必須傳回下列其中一個 HRESULT 值，以指出錯誤。
| 傳回碼 | 描述 |
|---|---|
|
強制指標引數為 Null。 |
|
SendBuffer參數所指定的緩衝區大小或格式不正確，或配接器無法辨識ControlCode參數中指定的值。 |
|
ReceiveBuffer參數指定的緩衝區太小。 |
|
已取消作業。 |
|
硬體故障。 |
|
配接器無法辨識 ControlCode 參數中指定的值。
注意 從 Windows 8 開始，只使用 E_INVALIDARG 來發出此條件的訊號。
|
備註
此函式的實作應該與 StorageAdapterControlUnitPrivileged 函式的實作相同，不同之處在于執行 ControlCode 參數所指定的作業不需要提高的許可權。 您必須負責定義作業，並決定不需要提高的許可權。
此函式必須檢查 ReceiveBufferSize 參數的值，以確保 ReceiveBuffer 參數所指定的緩衝區夠大，足以保存所傳回的資料。
範例
下列虛擬程式碼顯示此函式的一個可能實作。 此範例不會編譯。 您必須調整它以符合您的用途。
/////////////////////////////////////////////////////////////////////////////////////////
//
// 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;
}
規格需求
| 最低支援的用戶端 | Windows 7 [僅限傳統型應用程式] |
| 最低支援的伺服器 | Windows Server 2008 R2 [僅限桌面應用程式] |
| 目標平台 | Windows |
| 標頭 | winbio_adapter.h (包含 Winbio_adapter.h) |