MB 操作のセマンティクス

非同期トランザクション

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

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

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

MB サービスで使用される set と query の OID 要求の多くは、非同期で処理されます。 set と query の OID 要求の詳細については、NDIS_OID_REQUEST を参照してください。 「MB データ モデル」トピックの "WWAN 固有の OID" 表で、非同期で処理される OID を確認できます。

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

query 要求と set 要求のどちらも、3 方向のハンドシェイクは同じです。

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 サービスとミニポート ドライバー間の非同期の set トランザクションに関する相互作用シーケンスを表しています。 太字のラベルは 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 の場合、それは要求されていないイベント通知であり、いつでも発生する可能性があります。

set または query の OID 要求について返された表示の uStatus メンバーが WWAN_STATUS_SUCCESS に等しくない場合は、関連付けられている NDIS_WWAN_XXX 構造体のメンバーは有効である必要はありません。

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

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

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

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

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

イベント通知の状態

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

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

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

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

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

状態変化の通知

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

1. ミニポート ドライバーは、MB サービスが PIN の有効化または無効化を要求したために、PIN の状態変化が発生した場合、NDIS_STATUS_WWAN_PIN_LIST イベント表示を送信する必要はありません。

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

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

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