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 のみを使用してこの状態を通知します。
|
解説
この関数の実装は、ControlCode パラメーターで指定された操作を実行するために昇格された特権が必要ない点を除き、StorageAdapterControlUnitPrivileged 関数の実装と同じである必要があります。 操作を定義し、昇格された特権を必要としない操作を決定する責任があります。
この関数は、ReceiveBufferSize パラメーターの値をチェックして、ReceiveBuffer パラメーターで指定されたバッファーが、返されるデータを保持するのに十分な大きさであることを確認する必要があります。
例
次の擬似コードは、この関数の 1 つの可能な実装を示しています。 この例はコンパイルされません。 目的に合わせて調整する必要があります。
/////////////////////////////////////////////////////////////////////////////////////////
//
// 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 を含む) |
関連項目
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示