PIBIO_ENGINE_CONTROL_UNIT_PRIVILEGED_FN コールバック関数 (winbio_adapter.h)

[アーティクル]
03/03/2024

管理者特権を必要とするベンダー定義の制御操作を実行するために、Windows 生体認証フレームワークによって呼び出されます。 EngineAdapterControlUnit 関数を呼び出して、管理者特権を必要としないベンダー定義の制御操作を実行します。

構文

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

パラメーター

[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 値を返してエラーを示す必要があります。

リターンコード	説明
E_POINTER	必須のポインター引数は NULL です。
E_INVALIDARG	SendBuffer パラメーターで指定されたバッファーのサイズまたは形式が正しくないか、ControlCode パラメーターで指定された値がアダプターによって認識されません。
E_NOT_SUFFICIENT_BUFFER	ReceiveBuffer パラメーターで指定されたバッファーが小さすぎます。
WINBIO_E_CANCELED	操作は取り消されました。
WINBIO_E_DEVICE_FAILURE	ハードウェア障害が発生しました。
WINBIO_E_INVALID_CONTROL_CODE	ControlCode パラメーターで指定された値は、アダプターによって認識されません。メモWindows 8以降は、E_INVALIDARGのみを使用してこの状態を通知します。

注釈

この関数の実装は、EngineAdapterControlUnit 関数の実装と同じである必要があります。ただし、 ControlCode パラメーターで指定された操作を実行するには昇格された特権が必要です。操作を定義し、昇格された特権が必要な操作を決定する必要があります。

この関数は、ReceiveBufferSize パラメーターの値をチェックして、ReceiveBuffer パラメーターで指定されたバッファーが、返されるデータを保持するのに十分な大きさであることを確認する必要があります。

例

次の擬似コードは、この関数の 1 つの可能な実装を示しています。この例はコンパイルされません。目的に合わせて調整する必要があります。

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

要件

要件	値
サポートされている最小のクライアント	Windows 7 [デスクトップアプリのみ]
サポートされている最小のサーバー	Windows Server 2008 R2 [デスクトップアプリのみ]
対象プラットフォーム	Windows
ヘッダー	winbio_adapter.h (Winbio_adapter.h を含む)

こちらもご覧ください

EngineAdapterControlUnit

プラグイン関数

次の方法で共有

PIBIO_ENGINE_CONTROL_UNIT_PRIVILEGED_FN コールバック関数 (winbio_adapter.h)

構文

パラメーター

戻り値

注釈

例

要件

こちらもご覧ください

フィードバック

その他のリソース