MB 操作セマンティクス

非同期トランザクション

MB ドライバー モデルでは、NDIS 6.x で提供される非同期通知メカニズムを使用して、MB サービスとミニポート ドライバーの間の非ブロッキング操作セマンティクスを想定しています。 このメカニズムを使用すると、MB サービスは、現在の操作が完了するのを待たずに、処理のために OID 要求をミニポート ドライバーに送信し続けます。

非同期トランザクションは、最初の要求で始まり、その後に要求状態の応答が続き、最後のトランザクション指示で完了する 3 方向ハンドシェイクです。 要求の状態の応答は、ミニポート ドライバーが要求を受信したことを確認するだけという点で暫定的です。 フォローアップの非同期通知は、トランザクションを完了したことを通知するという点でトランザクション的です。 ミニポート ドライバーは、状態コードと結果のデータをトランザクション表示で返します。

非同期 セット要求と クエリ要求

MB サービスによって使用される セット および クエリ OID 要求の多くは非同期的に処理されます。 OID 要求 の設定 と クエリ の詳細については、「 NDIS_OID_REQUEST」を参照してください。 MB データ モデル トピックの 「WWAN 固有 OID」テーブルは、非同期的に処理される OID を識別します。

次の図は、MB サービスとミニポート ドライバーの間の非同期 クエリ トランザクションの相互作用シーケンスを表しています。 太字のラベルは OID 識別子またはトランザクション フロー制御を表し、標準テキストのラベルは OID 構造体内の重要なフラグを表します。

三者間ハンドシェイクは、クエリ要求とセット要求の両方で同じです。

OID_WWAN_DRIVER_CAPSを除き、他のすべての MB 固有の OID 要求は、ミニポート ドライバーと MB サービス間の情報交換の非同期トランザクション メカニズムに従います。次の注意事項があります。

• ミニポート ドライバーは、無効な OID 要求などのエラー状態で OID 要求をすぐに失敗させる必要があります。

• ミニポート ドライバーは、イベント通知構造体の uStatus メンバーで指定された正しいエラー コード (たとえば、WWAN_STATUS_XXX) を持つ WWAN 固有のエラー条件を返す必要があります。 ミニポート ドライバーは、必要に応じて uStatus メンバーに続く他のメンバーを適切に入力する必要があります。 たとえば、ミニポート ドライバーは、使用可能な場合は、NDIS_WWAN_CONTEXT_STATE構造体の ContextState.uNwError メンバーを入力する必要があります。 ただし、PIN に関連する OID を処理するときにエラーが発生した場合、ミニポート ドライバーは、NDIS_WWAN_PIN_INFOの PinInfo.PinState メンバーで指定する 現在の PIN 状態情報を必ずしも持っていない場合があります。

• ミニポート ドライバーは、すべての非同期 OID 要求の暫定的な応答としてNDIS_STATUS_INDICATION_REQUIREDを返す必要があります。

• ミニポート ドライバーは、他の原因から OID 要求によって引き起こされるデバイスの状態の変更を区別できる必要があります。 ミニポート ドライバーは、OID 要求に起因する状態の変更のトランザクション通知を送信する必要があり、他の原因からの状態の変更に関する要請されていないイベント通知を送信する必要があります。

• ミニポート ドライバーは、カーネル モード メモリを管理する役割を担いますが、MB サービスは最初に要求のメモリを割り当てます。 MB サービスは、ミニポート ドライバーから応答を受信した後、OID 要求に割り当てられたユーザー モード メモリを解放できます。

次の図は、MB サービスとミニポート ドライバーの間の非同期 セット トランザクションの相互作用シーケンスを表します。 太字のラベルは OID 識別子またはトランザクション フロー制御を表し、標準テキストのラベルは OID 構造体内の重要なフラグを表します。

非同期応答

NDIS 6.0 仕様 (Windows Vista でリリース) では、ミニポート ドライバーが OID 要求にミニポート ドライバーの暫定的な応答で MB サービスにトランザクションの非同期の性質を伝えるために、新しい状態コード、NDIS_STATUS_INDICATION_REQUIREDが導入されました。

MB インターフェイスの概要で説明したように、MB サービスは、MB ミニポート ドライバーによって割り当てられているカーネル モード メモリに直接アクセスできません。 カーネル モード メモリに格納された実行結果は、WMI や NDIS フィルター ドライバーなどの中継局によってコピーされ、MB サービスで使用できるようになると見なされます。 そのため、ミニポート ドライバーは、 NdisMIndicateStatusEx 関数呼び出しがトランザクションの指示で返された後に割り当てられたカーネル モード メモリを解放できます。

ミニポート ドライバーと MB サービスが従う必要があるハンドシェイク手順については、次の手順で説明します。

MB ミニポート ドライバーの手順

OID 要求を受信すると、ミニポート ドライバーは、次の手順を実行する必要があります。

1. カーネル モードでメモリを割り当てて、OID 要求に関連付けられている NDIS_OID_REQUEST データ構造の内容をコピーします。

2. 要求のパラメーターの中で、OID 要求構造体の RequestId メンバーと RequestHandle メンバーもコピーされていることを確認します。 これらのメンバーは、トランザクションのインディケーションで後で使用されます。

3. ミニポート ドライバーが非同期的に要求を完了することを MB サービスに通知する暫定的なNDIS_STATUS_INDICATION_REQUIRED状態応答を返します。

4. 操作が完了したら、必要に応じて、ローカルまたはドライバーによって割り当てられたメモリに結果を格納します。

5. NdisMIndicateStatusEx 関数を呼び出して、未処理の操作が完了したことを MB サービスに通知します。 ミニポート ドライバーは、次のように、NDIS_STATUS_INDICATION構造体のメンバーを入力する必要があります。

   1. StatusCode メンバーを状態通知の種類に設定します。 たとえば、NDIS_STATUS_WWAN_XXX。
   2. DestinationHandle メンバーを、ミニポート ドライバーが対応する OID 要求を受信したときに、NDIS_OID_REQUEST データ構造で受信した RequestHandle メンバーに設定します。
   3. ミニポート ドライバーが対応する OID 要求を受信したときに、NDIS_OID_REQUEST状態構造体の RequestId メンバーと一致するように RequestId メンバーを設定します。
   4. ミニポート ドライバーが割り当てたメモリとメモリ バッファーのサイズをそれぞれ指すように 、StatusBuffer メンバーと StatusBufferSize メンバーを設定します。 このメモリ バッファーには、完了した操作の結果が含まれます。
   5. 操作が正常に完了した場合は、 uStatus メンバーを WWAN_STATUS_SUCCESS に設定します。 それ以外の場合は、エラーの種類を示す適切なWWAN_STATUS_XXX値に uStatus メンバーを設定します。

6. 関数呼び出しが返されると、ミニポート ドライバーは、OID 要求に割り当てられたメモリを解放する必要があります。

MB サービス プロシージャ

MB サービスは、次の手順を使用して非同期トランザクションを処理します。

1. OID データ構造に基づいて、要求のバッファー メモリを割り当てます。 データ構造のメンバーに適切な値を入力します。

2. OID 要求の OID データ構造を指す InformationBuffer メンバーを使用して NdisOidRequest 関数を呼び出し、ミニポート ドライバーが応答するのを待ちます。

3. ミニポート ドライバーからNDIS_STATUS_INDICATION_REQUIRED暫定的な応答を受信すると、MB サービスは RequestId を保存し、割り当てられたメモリを解放し、トランザクションを開いているとしてマークします。 この時点で、MB サービスは後続の OID 要求と通知を自由に処理できます。

4. StatusCode 値としてNDIS_STATUS_WWAN_XXXの通知を受信したら、RequestId がオープンとしてマークされたトランザクションの通知と一致するかどうかを確認します。 一致するものがある場合、サービスはトランザクションを閉じます。 一致するものが見つからない場合は、通知を未承諾のイベント通知として扱います。

5. StatusBuffer メンバーで返されたデータを処理し、必要に応じて MB サービスに状態を変更します。

表示

ミニポート ドライバーが生成できる WWAN 固有の 表示には 、次の 2 種類があります。

• MB デバイスでのオブジェクトの状態の変化に起因するイベント通知。

• 非同期操作の完了を通知するトランザクション通知。

どちらの場合も、ミニポート ドライバーは NdisMIndicateStatusEx 関数を呼び出す必要があります。

イベント通知

イベント通知は、ミニポート ドライバーが状態変更イベントとして MB サービスに事前に通知を送信するという意味で未承諾です。 状態の変更は、MB サービス以外のエンティティからのアクションによって発生します。 MB サービスは、ミニポート ドライバーが変更の原因を検出できることを前提としています。

WWAN 固有のイベント通知の場合、ミニポート ドライバーは、NDIS_STATUS_INDICATION構造体の RequestId メンバーを 0 に設定する必要があります。 StatusCode メンバーは、MB デバイス内のどのオブジェクトが変更されたかを指定します。 ミニポート ドライバーは、次のいずれかの値にこのオブジェクトを設定できます。

NDIS_STATUS_WWAN_DEVICE_CAPS

NDIS_STATUS_WWAN_READY_INFO

NDIS_STATUS_WWAN_RADIO_STATE

NDIS_STATUS_WWAN_PIN_INFO

NDIS_STATUS_WWAN_PIN_LIST

NDIS_STATUS_WWAN_HOME_PROVIDER

NDIS_STATUS_WWAN_PREFERRED_PROVIDERS

NDIS_STATUS_WWAN_VISIBLE_PROVIDERS

NDIS_STATUS_WWAN_REGISTER_STATE

NDIS_STATUS_WWAN_PACKET_SERVICE

NDIS_STATUS_WWAN_SIGNAL_STATE

NDIS_STATUS_WWAN_CONTEXT_STATE

NDIS_STATUS_WWAN_PROVISIONED_CONTEXTS

NDIS_STATUS_WWAN_SERVICE_ACTIVATION

NDIS_STATUS_WWAN_SMS_CONFIGURATION

NDIS_STATUS_WWAN_SMS_RECEIVE

NDIS_STATUS_WWAN_SMS_SEND

NDIS_STATUS_WWAN_SMS_DELETE

NDIS_STATUS_WWAN_SMS_STATUS

NDIS_STATUS_WWAN_VENDOR_SPECIFIC

MB サービスは、NDIS からの他のイベント通知を処理することもできます。 これらの MB 以外のイベント通知は、必ずしも RequestId 値を 0 に設定するという要件の対象になるとは限りません。

トランザクション通知

ミニポート ドライバーは、トランザクション通知を使用して、非同期トランザクションが完了したことを MB サービスに通知し、MB サービスはトランザクション通知を使用して開いているトランザクションを閉じ、状態マシンを更新します。

MB サービスは、開いているトランザクションを閉じることができるように、トランザクション通知を受け取ります。 これは、非同期トランザクションでの MB サービスとミニポート ドライバーの間の 3 方向ハンドシェイクの最終的な交換です。 トランザクション通知のNDIS_STATUS_INDICATIONの RequestId メンバーの値は 0 以外である必要があります。この値は、同じトランザクション内の対応する要求からコピーされます。

非同期メカニズムが正常に機能するためには、NDIS_STATUS_INDICATION構造体の RequestId メンバーを正しく設定する必要があります。 MB サービスは、すべての未処理の要求の中で RequestId 値が一意であり、0 以外であることを保証します。 ミニポート ドライバーは、MB サービスが開いているトランザクションと表示を関連付けるために、対応する表示で同じ RequestId 値を返す必要があります。

状態表示の構造

特定の OID 要求の非同期応答と要請されていないイベント通知構造体の両方で、StatusIndication パラメーターの StatusBuffer メンバーが NdisMIndicateStatusEx を指す次の構造体メンバーを共有します。

typedef struct _NDIS_WWAN_XXX {
  NDIS_OBJECT_HEADER Header;
  WWAN_STATUS uStatus;
  ULONG uNwError;//Optional. Only used for network operations.
  WWAN_XXX XxxStruct;
} NDIS_WWAN_XXX, *PNDIS_WWAN_XXX;

NDIS_STATUS_INDICATION構造体の RequestId メンバーの値が 0 の場合は、要求されていないイベント通知であり、いつでも発生する可能性があります。

返されたセットまたはクエリ OID 要求の uStatus メンバーが WWAN_STATUS_SUCCESS でない場合、関連付けられているNDIS_WWAN_XXX構造体のメンバーは有効である必要はありません。

ネットワーク イベントに基づく未承諾のイベント通知の場合、ミニポート ドライバーは、必要に応じて uNwError メンバーを入力する必要があります (該当する場合)。

次の表は、GSM ベースネットワークの 3GPP TS 24.008 仕様 で定義されている登録、パケットアタッチ、パケットデタッチの原因コードエラー値を示しています。

たとえば、場所領域でローミングが許可されていないために、ネットワークが非アクティブ化コンテキスト イベントを開始する場合、ミニポート ドライバーは、GSM ベースのネットワークの 3GPP TS 24.008 原因コードに従って uNwError メンバーを 13 に設定する必要があります。

CDMA ベースのネットワークにも同様のロジックを適用する必要があります。 ただし、CDMA ベースのネットワーク エラー コードの標準はありません。 CDMA ベースのデバイスでは、ネットワーク -specific またはデバイス固有のエラー コードを使用する必要があります。

OID 要求に対するミニポート ドライバーの非同期応答の場合、NDIS_STATUS_INDICATION構造体の RequestId メンバーは、 セット または クエリ 要求の一部としてミニポート ドライバーに渡された 0 以外の数値です。 ミニポート ドライバーは、必要に応じて uStatus メンバーを入力する必要があります。 たとえば、WWAN_STATUS_SUCCESS、または次のセクションに示す適切なエラー値のいずれかです。 これに加えて、ミニポート ドライバーは、必要に応じて適切な条件で uNwError メンバーを入力する必要があります。

イベント通知の状態

次の表は、MB ミニポート ドライバーが指定できるWWAN_STATUS コードの一覧、 uStatus NDIS_WWAN_XXXイベント通知構造体のメンバーです。

次の表に、SMS 固有の状態値を示します。

手記 これらの WWAN 固有の状態コードは、NDIS_WWAN_XXX構造体の uStatus メンバー内の非同期トランザクションにのみ使用されます。

ミニポート ドライバーは、イベント通知を使用して、最初に OID 要求を受け取ることなく、MB デバイスのオブジェクト状態の変化について MB サービスに通知します。 MB サービスは、イベント通知を使用してステート マシンのみを更新します。

NDIS はミニポート ドライバーに送信されるすべての要求をシリアル化するが、ミニポート ドライバーが同じ順序で応答を返さない可能性があることに注意してください。 これは、ミニポート ドライバーのキューに登録された要求が並列で処理される可能性があるためです。 そのため、MB サービスは、2 つの要求が相互に依存している場合、ミニポート ドライバーが最初の要求を完了するまで、2 番目の要求を送信しないことを保証します。

状態変更通知

一般に、ミニポート ドライバーは常に、トランザクション通知または未承諾のイベント通知を通じて、MB デバイスの更新された状態について MB サービスに通知する必要があります。 次のシナリオは、ミニポート ドライバーが更新された状態情報で応答することが想定されていないいくつかの例外です。 MB サービスは、他の操作の完了状態から更新された状態を判断できます。

1. ミニポート ドライバーは、PIN を有効または無効にするように要求された MB サービスが原因で PIN 状態の変更が発生したときに、NDIS_STATUS_WWAN_PIN_LISTイベントの表示を送信する必要はありません。

2. ミニポート ドライバーは、 OID_WWAN_PROVISIONED_CONTEXTセット 操作へのトランザクション応答で、プロビジョニングされたコンテキストの更新された一覧を返す必要はありません。

3. ミニポート ドライバーは、 OID_WWAN_PREFERRED_PROVIDERSセット 操作へのトランザクション応答で優先プロバイダーの更新された一覧で応答する必要はありません。 MB サービスは、 設定 操作の最初の一覧と成功状態に基づいて、この情報を決定できます。

4. ミニポート ドライバーは、 OID_WWAN_SMS_CONFIGURATIONセット 操作の現在のWWAN_SMS_CONFIGURATION値で応答する必要はありません。