MBBCx クライアントドライバーの記述

Warnung

このトピックのシーケンス図は、説明のみを目的としています。これらは公開契約ではなく、将来変更される可能性があります。

MBBCx クライアントドライバーの INF ファイル

MBBCx クライアントドライバーの INF ファイルは、他の NetAdapterCx クライアントドライバーと同じです。詳細については、 NetAdapterCx クライアントドライバーの INF ファイルを参照してください。

ユニバーサルガイダンスに従って、INF ファイルがユニバーサル要件を満たしていることを確認します。

デバイスを初期化する

NetAdapter デバイスの初期化に NetAdapterCx で必要なタスクに加えて、MBB クライアントドライバーは、EvtDriverDeviceAdd コールバック関数で次のタスクも実行する必要があります。

NetDeviceInitConfig を呼び出した後、WdfDeviceCreate を呼び出す前に、フレームワークによって渡されたのと同じ WDFDEVICE_INIT オブジェクトを参照して、MBB_DEVICE_CONFIG_INIT を呼び出します。
初期化されたMBB_DEVICE_CONFIG構造体と WdfDeviceCreate から取得した WDFDEVICE オブジェクトを使用して MBB デバイス固有のコールバック関数を登録するには、MbbDeviceInitialize を呼び出します。

次の例では、MBB デバイスを初期化する方法を示します。わかりやすくするために、エラー処理は省略されています。

    status = NetDeviceInitConfig(deviceInit);
    status = MbbDeviceInitConfig(deviceInit);

    // Set up other callbacks such as Pnp and Power policy

    status = WdfDeviceCreate(&deviceInit, &deviceAttributes, &wdfDevice);

    MBB_DEVICE_CONFIG mbbDeviceConfig;
    MBB_DEVICE_CONFIG_INIT(&mbbDeviceConfig,
                           EvtMbbDeviceSendMbimFragment,
                           EvtMbbDeviceReceiveMbimFragment,
                           EvtMbbDeviceSendServiceSessionData,
                           EvtMbbDeviceCreateAdapter);

    status = MbbDeviceInitialize(wdfDevice, &mbbDeviceConfig);

他の種類の NetAdapterCx ドライバーとは異なり、MBB クライアントドライバーは 、EvtDriverDeviceAdd コールバック関数内から NETADAPTER オブジェクトを作成することはできません。代わりに、後で行うよう MBBCx によって指示されます。

次に、クライアントドライバーは MbbDeviceSetMbimParameters を呼び出す必要があります。通常は、次の EvtDevicePrepareHardware コールバック関数で呼び出します。

このメッセージ・フロー図は、初期化プロセスを示しています。

MBBCx クライアントドライバーの初期化プロセスを示す図。

このメッセージ・フロー図は、初期化プロセスを示しています。

MBBCx クライアントドライバーの初期化プロセスを示す図。

MBIM 制御メッセージの処理

MBBCx は、MBIM 仕様 Rev 1.0、セクション 8、9、および 10 で定義されている標準の MBIM コントロールコマンドをコントロールプレーンに使用します。コマンドと応答は、クライアントドライバーによって提供される一連のコールバック関数と MBBCx によって提供される API を介して交換されます。 MBBCx は、MBIM 仕様 Rev 1.0、セクション 5.3 で定義されている MBIM デバイスの運用モデルを、次の関数呼び出しを使用して模倣します。

MBBCx は、 その EvtMbbDeviceSendMbimFragment コールバック関数を呼び出すことによって、クライアントドライバーに MBIM コマンドメッセージを送信します。クライアントドライバーは 、MbbRequestComplete を呼び出すことによって、この送信要求を非同期的に完了します。
クライアントドライバーは 、MbbDeviceResponseAvailable を呼び出すことによって、結果の可用性を通知します。
MBBCx は、 その EvtMbbDeviceReceiveMbimFragment コールバック関数を呼び出すことによって、クライアントドライバーから MBIM 応答メッセージをフェッチします。クライアントドライバーは、 MbbRequestCompleteWithInformation を呼び出すことによって、この get-response 要求を非同期的に完了します。
MBB クライアントドライバーは、 MbbDeviceResponseAvailable を呼び出すことによって、未承諾のデバイスイベントを MBBCx に通知できます。 MBBCx は、MBIM 応答メッセージをフェッチする方法と同様に、クライアントドライバーから情報を取得します。

次の図は、MBBCx-client ドライバーのメッセージ交換フローを示しています。

MBBCx とクライアントドライバーの間の MBIM メッセージ交換を示す図。

MBIM 制御メッセージの同期

MBBCx フレームワークは、常にクライアントドライバーの EvtMbbDeviceSendMbimFragment および EvtMbbDeviceReceiveMbimFragment コールバック関数への呼び出しをシリアル化します。クライアントドライバーが MbbRequestComplete または MbbRequestCompleteWithInformation を呼び出すまで、フレームワークによって新しい呼び出しは行われません。

クライアントドライバーは、重複する EvtMbbDeviceSendMbimFragment コールバックまたは EvtMbbDeviceReceiveMbimFragment コールバックを受信しないことが保証されますが、デバイスから前のコマンドの応答を使用できるようになる前に、それらのコールバックに対する複数の呼び出しを連続して受け取ることがあります。

デバイスが D0 状態でない場合、MBBCx フレームワークは、EvtMbbDeviceSendMbimFragment または EvtMbbDeviceReceiveMbimFragment を呼び出す前に、まずデバイスを D0 に取り込みます (つまり、EvtDeviceD0Entry を呼び出します)。また、MBBCx フレームワークは、デバイスを D0 状態に保つことを保証します。つまり、クライアントが MbbRequestComplete または MbbRequestCompleteWithInformation を呼び出すまで、EvtDeviceD0Exit を呼び出しません。

PDP コンテキスト/EPS ベアラーの NetAdapter インターフェイスの作成

データセッションを確立する前に、MBBCx は NETADAPTER オブジェクトを作成するようにクライアントドライバーに指示し、アクティブ化されたデータセッションのネットワークインターフェイスを表すために MBBCx によって使用されます。これは、クライアントドライバーの EvtMbbDeviceCreateAdapter コールバック関数を呼び出す MBBCx によって実現されます。

EvtMbbDeviceCreateAdapter コールバック関数の実装では、MBBCx クライアントドライバーは、まず、NetAdapterCx クライアントドライバーと NETADAPTER オブジェクトを作成するために必要なのと同じタスクを実行する必要があります。さらに、次の追加タスクも実行する必要があります。

NetAdapterCreate によって作成された NETADAPTER オブジェクトで MbbAdapterInitialize を呼び出します。
MbbAdapterinitialize を呼び出した後、MbbAdapterGetSessionId を呼び出して、MBBCx がこの NETADAPTER オブジェクトを使用するデータセッション ID を取得します。たとえば、戻り値が 0 の場合、MBBCx はプライマリ PDP コンテキスト/既定の EPS ベアラーによって確立されたデータセッションにこの NETADAPTER インターフェイスを使用することを意味します。
MBBCx クライアントドライバーは、作成された NETADAPTER オブジェクトと返された SessionId の間に内部マッピングを保持することをお勧めします。これは、データセッションと NETADAPTER オブジェクトの関係を追跡するのに役立ちます。これは、複数の PDP コンテキスト/EPS ベアラーがアクティブ化されている場合に特に便利です。
EvtMbbDeviceCreateAdapter から戻る前に、クライアントドライバーは、NetAdapterStartを呼び出してアダプターを起動する必要があります。必要に応じて、NetAdapterStartへの呼び出しを する前に、これらの関数の 1 つ以上を 呼び出すことによって、アダプターの機能を設定することもできます。

MBBCx はこのコールバック関数を少なくとも 1 回呼び出します。そのため、プライマリ PDP コンテキスト/既定の EPS ベアラーには常に 1 つの NETADPATER オブジェクトがあります。複数の PDP コンテキスト/EPS ベアラーがアクティブ化されている場合、MBBCx は、確立されるすべてのデータセッションに対して 1 回、このコールバック関数を複数回呼び出す可能性があります。次の図に示すように、NETADAPTER オブジェクトによって表されるネットワークインターフェイスとデータセッションの間に 1 対 1 のリレーションシップが必要です。

さまざまなデータセッションに対する複数の NETADAPTER オブジェクトを示す図。

次の例は、データセッションの NETADAPTER オブジェクトを作成する方法を示しています。簡潔でわかりやすくするために、アダプター機能の設定に必要なエラー処理とコードは省略されていることに注意してください。

    NTSTATUS
    EvtMbbDeviceCreateAdapter(
        WDFDEVICE  Device,
        PNETADAPTER_INIT AdapterInit
    )
    {
        // Get the client driver defined per-device context
        PMY_DEVICE_CONTEXT deviceContext = MyGetDeviceContext(Device);

        // Set up the client driver defined per-adapter context
        WDF_OBJECT_ATTRIBUTES adapterAttributes;
        WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&adapterAttributes,
                                                MY_NETADAPTER_CONTEXT);


        // Create the NETADAPTER object
        NETADAPTER netAdapter;
        NTSTATUS status = NetAdapterCreate(AdapterInit,
                                           &adapterAttributes,
                                           &netAdapter);

        // Initialize the adapter for MBB
        status = MbbAdapterInitialize(netAdapter);

        // Retrieve the Session ID and use an array to store
        // the session <-> NETADAPTER object mapping
        ULONG sessionId;
        PMY_NETADAPTER_CONTEXT netAdapterContext = MyGetNetAdapterContext(netAdapter);

        netAdapterContext->NetAdapter = netAdapter;

        sessionId = MbbAdapterGetSessionId(netAdapter);

        netAdapterContext->SessionId = sessionId;

        deviceContext->Sessions[sessionId].NetAdapterContext = netAdapterContext;

        //
        // Optional: set adapter capabilities
        //
        ...
        NetAdapterSetDatapathCapabilities(netAdapter,
                                          &txCapabilities,
                                          &rxCapabilities);

        ...
        NetAdapterSetLinkLayerCapabilities(netAdapter,
                                           &linkLayerCapabilities);

        ...
        NetAdapterSetLinkLayerMtuSize(netAdapter,
                                      MY_MAX_PACKET_SIZE - ETHERNET_HEADER_LENGTH);

        //
        // Required: start the adapter
        //
        status = NetAdapterStart(netAdapter);

        return status;
    }

データパス機能を設定するコード例については、「ネットワークデータバッファーの管理」を参照してください。

MBBCx は、同じセッション ID でMBIM_CID_CONNECTを要求する前に、EvtMbbDeviceCreateAdapter を呼び出していることを保証します。次のフロー図は、NETADAPTER オブジェクトの作成におけるクライアントドライバーとクラス拡張機能の間の相互作用を示しています。

MBB クライアントドライバーの NETADAPTER の作成とアクティブ化を示す図。

プライマリ PDP コンテキスト/既定の EPS ベアラーの NETADAPTER オブジェクトを作成するためのフローは、 EvtDevicePrepareHardware が正常に完了したときに MBBCx によって開始されます。

セカンダリ PDP コンテキスト/専用 EPS ベアラーの NETADAPTER オブジェクトを作成するためのフローは、アプリケーションによってオンデマンド接続が要求されるたびに WwanSvc によってトリガーされます。

NETADAPTER オブジェクトの有効期間

クライアントドライバーによって作成された NETADAPTER オブジェクトは、使用されなくなったときに MBBCx によって自動的に破棄されます。たとえば、これは追加の PDP コンテキスト/EPS ベアラーが非アクティブ化された後に発生します。 MBBCx クライアントドライバーは、作成する NETADAPTER オブジェクトで WdfObjectDelete を呼び出してはなりません。

クライアントドライバーは、NETADAPTER オブジェクトに関連付けられているコンテキストデータをクリーンアップする必要がある場合は、NetAdapterCreate を呼び出すときに、オブジェクト属性構造体に EvtDestroyCallback 関数を提供する必要があります。

MBB デバイスの電源管理

電源管理の場合、クライアントドライバーは、他の種類の NetAdapterCx クライアントドライバーと同様に NETPOWERSETTINGS オブジェクトを使用する必要があります。

デバイスサービスセッションの処理

アプリケーションが DSS データをモデムデバイスに送信すると、MBBCx はクライアントドライバーの EvtMbbDeviceSendServiceSessionData コールバック関数を呼び出します。クライアントドライバーは、デバイスに非同期的にデータを送信し、送信が完了したら MbbDeviceSendDeviceServiceSessionDataComplete を呼び出す必要があります。これにより、MBBCx はデータに割り当てられたメモリを解放できます。

逆に、クライアントドライバーは MbbDeviceReceiveDeviceServiceSessionData を呼び出して、MBBCx を介してアプリケーションにデータを渡します。

Windows ドライバー準拠の要件

DCH 設計原則に準拠する
ドライバーパッケージ分離の原則に従う
API レイヤー要件に従う
ハードウェアラボキットを使用した Windows ハードウェア互換性プログラム認定プロセスでの認定

フィードバック

このページはお役に立ちましたか?

Last updated on 2023-03-08