次の方法で共有

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
    );

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

EVT_SERCX_APPLY_CONFIG MyEvtSerCxApplyConfig;

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

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

関数宣言の SDV 要件の詳細については、「宣言する関数を宣言する KMDF ドライバーのの関数の役割の種類を参照してください。

次のコード例は、UART の EvtSerCxApplyConfig 関数の部分的な実装を示しています。 
//
// 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 ヘッダー ファイルで定義されています。

必要条件

要件 価値
サポートされる最小クライアント Windows 8 以降で使用できます。
ターゲット プラットフォーム の デスクトップ
ヘッダー sercx.h
IRQL IRQL <= DISPATCH_LEVEL で呼び出されます

関連項目

IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION

SerCxGetConnectionParameters

SerCxInitialize