EVT_SERCX_APPLY_CONFIG コールバック関数 (sercx.h)

EvtSerCxApplyConfig イベント コールバック関数は、シリアル コントローラー ハードウェアに構成設定の一覧を適用するようにシリアル コントローラー ドライバーに指示します。

構文

EVT_SERCX_APPLY_CONFIG EvtSercxApplyConfig;

NTSTATUS EvtSercxApplyConfig(
  [in] WDFDEVICE Device,
  [in] PVOID ConnectionParameters
)
{...}

パラメーター

[in] Device

シリアル コントローラーを表すフレームワーク デバイス オブジェクトへの WDFDEVICE ハンドル。

[in] ConnectionParameters

接続パラメーター構造体へのポインター。 この関数は、このパラメーターを適切なポインター型にキャストし、データ構造を解析して構成設定を取得し、これらの設定をシリアル コントローラー ハードウェアに適用する必要があります。 接続パラメーターの構造は、ハードウェア プラットフォーム ベンダーによって定義され、シリアル フレームワーク拡張機能 (SerCx) とオペレーティング システムの両方に不透明です。

戻り値

呼び出しが成功した場合 、EvtSerCxApplyConfig 関数はSTATUS_SUCCESSを返します。 それ以外の場合は、適切なエラー状態コードを返します。

注釈

SerCx は、シリアル コントローラーの初期化中にこの関数を呼び出して、ハードウェアが有効な初期状態であることを確認します。 さらに、この関数は、クライアントが IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION I/O 制御要求をコントローラーに送信するたびに呼び出されます。

SerCx は、シリアル コントローラー デバイスの ACPI リソース記述子からこれらの構成パラメーターを取得します。 ACPI ファームウェアがこれらの構成設定を格納するために使用するデータ形式は、シリアル コントローラー ドライバーで想定されるデータ形式と同じである必要があります。

クライアントが SerCx によって管理されているシリアル ポートに IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION 要求を送信すると、SerCx は、シリアル ポートのシリアル コントローラー ドライバーが EvtSerCxApplyConfig コールバックをサポートするかどうか、およびシリアル ポートの ACPI リソース記述子が既定の接続設定を提供するかどうかを判断します。 そうでない場合、SerCx はエラー状態コード STATUS_NOT_SUPPORTEDを使用して要求を完了します。 それ以外の場合、SerCx は接続パラメーターをドライバーの EvtSerCxApplyConfig コールバック関数に渡します。 このコールバックが返された後、SerCx は要求を完了し、コールバックからの戻り値を要求の状態コードとして使用します。

シリアル コントローラー ドライバーは、 EvtSerCxApplyConfig コールバック中以外の一度に既定の接続パラメーターを取得する必要がある場合、ドライバーは SerCxGetConnectionParameters メソッドを呼び出すことができます。

EvtSerCxApplyConfig コールバック関数を登録するには、ドライバーが SerCxInitialize メソッドを呼び出す必要があります。

例

このコールバックの関数型は、次のように Sercx.h で宣言されています。

typedef NTSTATUS
  EVT_SERCX_APPLY_CONFIG(
    __in WDFDEVICE Device
    );

という名前MyEvtSerCxApplyConfigの EvtSerCxApplyConfig コールバック関数を定義するには、まず、静的ドライバー検証ツール (SDV) やその他の検証ツールで必要な関数宣言を次のように指定する必要があります。

EVT_SERCX_APPLY_CONFIG MyEvtSerCxApplyConfig;

次に、次のようにコールバック関数を実装します。

NTSTATUS
  MyEvtSerCxApplyConfig(
    __in WDFDEVICE Device
    )
{ ... }

関数宣言の SDV 要件の詳細については、「 KMDF ドライバーの関数ロール型を使用した関数の宣言」を参照してください。

//
// Define the UART ACPI descriptor, plus any vendor-specific
// data that is needed by the serial controller (UART) driver.
//

#define ANYSIZE_ARRAY 1


//
// Common resource name descriptor
//
typedef struct _PNP_IO_DESCRIPTOR_RESOURCE_NAME {
    UCHAR ResourceIndex;
    UCHAR ResourceName[ANYSIZE_ARRAY];
} PNP_IO_DESCRIPTOR_RESOURCE_NAME, *PPNP_IO_DESCRIPTOR_RESOURCE_NAME;

//
// Bus descriptor for a UART
//
typedef struct _PNP_UART_SERIAL_BUS_DESCRIPTOR {
    PNP_SERIAL_BUS_DESCRIPTOR SerialBusDescriptor;
    ULONG BaudRate;
    USHORT RxBufferSize;
    USHORT TxBufferSize;
    UCHAR Parity;
    // Include any optional vendor data here:
    ...
    // Append the PNP_IO_DESCRIPTOR_RESOURCE_NAME here:
    ....
} PNP_UART_SERIAL_BUS_DESCRIPTOR, *PPNP_UART_SERIAL_BUS_DESCRIPTOR;

EVT_SERCX_APPLY_CONFIG UartEvtApplyConfig;

//
// Implementation of an EvtSerCxApplyConfig callback function
//
NTSTATUS
  UartEvtApplyConfig(
    __in WDFDEVICE Device,
    __in PVOID ConnectionParameters
    )
{
    NTSTATUS status = STATUS_SUCCESS; 
    PRH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFER connection;
    PPNP_SERIAL_BUS_DESCRIPTOR descriptor;
    PPNP_UART_SERIAL_BUS_DESCRIPTOR uartDescriptor;

    if (ConnectionParameters == NULL)
    {
        status = STATUS_INVALID_PARAMETER; 
    }

    if (NT_SUCCESS(status))
    {
        connection = (PRH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFER)ConnectionParameters;

        if (connection->PropertiesLength < sizeof(PNP_SERIAL_BUS_DESCRIPTOR))
        {
            status = STATUS_INVALID_PARAMETER;
        }
    }

    if (NT_SUCCESS(status))
    {
        descriptor = (PPNP_SERIAL_BUS_DESCRIPTOR)connection->ConnectionProperties;

        if (descriptor->SerialBusType != UART_SERIAL_BUS_TYPE)
        {
            status = STATUS_INVALID_PARAMETER;
        }
    }

    if (NT_SUCCESS(status))
    {
        uartDescriptor = (PPNP_UART_SERIAL_BUS_DESCRIPTOR)connection->ConnectionProperties; 

        // Apply the configuration settings from
        // the UART descriptor.
        ...
    }

    return status;
}

前のコード例のPRH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFERとPPNP_SERIAL_BUS_DESCRIPTOR ポインター型は、Reshub.h ヘッダー ファイルで定義されています。

要件

こちらもご覧ください

IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION

SerCxGetConnectionParameters

SerCxInitialize