MB 操作語意

非同步交易

MB 驅動程式模型會使用 NDIS 6.x 中提供的非同步通知機制，假設 MB 服務與迷你埠驅動程式之間的非封鎖作業語意。 此機制可讓 MB 服務繼續將 OID 要求傳送至迷你埠驅動程式進行處理，而不需要等候目前的作業完成。

非同步交易是透過三向握手協議進行的，從初始請求開始，接著是請求狀態回應，最後由交易完成指示來結束。 要求狀態回應是暫時的，因為它只會確認迷你埠驅動程式已收到要求。 後續非同步指示是交易式的，因為它會發出交易完成的訊號。 迷你埠驅動程式會傳回狀態碼，以及交易指示中的結果數據。

非同步 集 和 查詢 請求

MB 服務所使用的許多 設定 和 查詢 OID 要求都會以非同步方式處理。 如需 設定 和 查詢 OID 要求的詳細資訊，請參閱 NDIS_OID_REQUEST。 MB 資料模型主題中的「WWAN 特定 OID」表格會識別非同步處理的 OID。

下圖代表 MB 服務與迷你埠驅動程式之間非同步 查詢 交易的互動順序。 粗體標籤代表 OID 識別碼或交易流程控制，而一般文字中的標籤代表 OID 結構內的重要旗標。

查詢和設定要求的三向握手相同。

除了 OID_WWAN_DRIVER_CAPS之外，所有其他 MB 特定的 OID 要求都會遵循非同步交易機制，以在迷你埠驅動程式與 MB 服務之間進行資訊交換，並附有下列其他附註：

• 迷你埠驅動程式在遇到任何錯誤狀況時，例如針對無效的 OID 要求，應立即拒絕該 OID 要求。

• 微型端口驅动程序必须传回任何特定于 WWAN 的错误状况，並在事件通知结构的 uStatus 成员中指定正確的錯誤码 (例如，WWAN_STATUS_XXX)。 迷你埠驅動程式也應該視需要適當地填入 uStatus 成員之後的成員。 例如，迷你埠驅動程式應該填入 NDIS_WWAN_CONTEXT_STATE 結構的 ContextState.uNwError 成員 （如果有的話）。 不過，當處理與 PIN 相關的 OID 發生失敗時，小端口驅動程式可能無法獲得目前的 PIN 狀態資訊，從而無法在 NDIS_WWAN_PIN_INFO 的 PinInfo.PinState 成員中指定。

• 迷你埠驅動程式應該傳回NDIS_STATUS_INDICATION_REQUIRED作為所有非同步 OID 要求的暫定回應。

• 迷你埠驅動程式應該能夠區分 OID 要求所造成的裝置狀態變更與其他原因。 迷你埠驅動程式應該傳送 OID 要求所產生狀態變更的交易式通知，而且應該傳送其他原因的狀態變更的未經請求的事件通知。

• 迷你埠驅動程式負責管理核心模式下的記憶體，不過，MB 服務一開始會分配用於請求的記憶體。 在 MB 服務收到來自迷你埠驅動程式的回應之後，服務可能會釋放它配置給 OID 要求的使用者模式記憶體。

下圖代表 MB 服務與迷你埠驅動程式之間非同步 集 交易的互動順序。 粗體標籤代表 OID 識別碼或交易流程控制，而一般文字中的標籤代表 OID 結構內的重要旗標。

非同步回應

NDIS 6.0 規格 （隨 Windows Vista 發行） 引進了新的狀態碼 NDIS_STATUS_INDICATION_REQUIRED，讓迷你埠驅動程式在迷你埠驅動程式對 OID 要求的臨時回應中，將交易的非同步本質傳達給 MB 服務。

如 MB 介面概觀中所述，MB 服務無法直接存取 MB 迷你埠驅動程式所配置的核心模式記憶體。 儲存在核心模式記憶體中的執行結果會假設會由某些中繼複製並提供給 MB 服務，例如 WMI 或 NDIS 篩選驅動程式。 因此，迷你埠驅動程式可以在 NdisMIndicateStatusEx 函式呼叫傳回交易指示之後釋放配置的核心模式記憶體。

下列程式說明迷你埠驅動程式和 MB 服務必須遵循的握手程式。

MB 迷你埠驅動程式程序

收到 OID 要求時，迷你埠驅動程式應該執行下列步驟：

1. 在核心模式中配置記憶體，以複製與 OID 要求相關聯的 NDIS_OID_REQUEST 資料結構的內容。

2. 在這些要求的參數中，請確保 OID 要求結構中的 RequestId 和 RequestHandle 成員也被複製。 這些成員稍後將在交易 指示中使用。

3. 傳回暫時NDIS_STATUS_INDICATION_REQUIRED狀態回應，以通知 MB 服務迷你埠驅動程式會以非同步方式完成要求。

4. 作業完成之後，視需要將結果儲存在本機或驅動程式配置的記憶體中。

5. 呼叫 NdisMIndicateStatusEx 函式，通知 MB 服務未完成的作業已完成。 迷你埠驅動程式應該填入NDIS_STATUS_INDICATION結構的成員，如下所示：

   1. 將 StatusCode 成員設定為狀態通知的類型。 例如，NDIS_STATUS_WWAN_XXX。
   2. 將 DestinationHandle 成員設定為迷你埠驅動程式收到對應 OID 要求時，在 NDIS_OID_REQUEST 資料結構中收到的 RequestHandle 成員。
   3. 當迷你埠驅動程式收到對應的 OID 要求時，將 RequestId 成員設定為符合 NDIS_OID_REQUEST 狀態結構的 RequestId 成員。
   4. 將 StatusBuffer 和 StatusBufferSize 成員分別指向迷你埠驅動程式配置的記憶體和記憶體緩衝區的大小。 此記憶體緩衝區包含已完成作業的結果。
   5. 如果作業順利完成，請將 uStatus 成員設為 WWAN_STATUS_SUCCESS。 否則，請將 uStatus 成員設定為適當的 WWAN_STATUS_XXX 值，以指出失敗的類型。

6. 當函式呼叫傳回時，迷你埠驅動程式應該釋放它配置給 OID 要求的記憶體。

MB 服務程序

MB 服務會使用下列程序來處理非同步交易：

1. 根據 OID 資料結構為請求分配緩衝區記憶體。 使用適當的值填入資料結構成員。

2. 呼叫 NdisOidRequest 函式，其中包含指向 OID 要求之 OID 資料結構的 InformationBuffer 成員，並等候迷你埠驅動程式回應。

3. 從迷你埠驅動程式收到NDIS_STATUS_INDICATION_REQUIRED暫定回應時，MB 服務會儲存 RequestId、釋放配置的記憶體，並將交易標示為開啟。 此時，MB 服務可以自由處理後續的 OID 要求和通知。

4. 收到 NDIS_STATUS_WWAN_XXX 作為 StatusCode 值的通知時，請檢查 RequestId 是否符合任何標示為開啟的交易。 如果有相符項，服務會關閉交易。 如果找不到匹配項目，視通知為未經請求的事件通知。

5. 處理 StatusBuffer 成員中傳回的數據，並視需要對 MB 服務進行狀態變更。

適應症

迷你埠驅動程式可以產生兩種類型的 WWAN 特定 指示 ：

• MB 裝置中物件狀態變更所產生的事件通知。

• 指示非同步作業完成的交易通知。

在這兩種情況下，迷你埠驅動程式都應該呼叫 NdisMIndicateStatusEx 函式。

事件通知

事件通知是未經請求的，因為迷你埠驅動程式會主動將指示傳送至 MB 服務，做為狀態變更事件。 狀態變更是由 MB 服務以外的某些實體的動作所造成。 MB 服務假設迷你埠驅動程式能夠偵測變更的原因。

針對任何 WWAN 特定的事件通知，迷你埠驅動程式必須將 NDIS_STATUS_INDICATION 結構的 RequestId 成員設定為零。 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 值設定為零的需求。

交易通知

迷你埠驅動程式會使用交易式通知來通知 MB 服務非同步交易已完成，而 MB 服務會使用交易式通知來關閉開啟的交易，並更新其狀態機。

MB 服務需要交易通知，以便完成並關閉已開啟的交易。 這是非同步交易中 MB 服務與迷你埠驅動程式之間三向交握的最終交換。 任何交易通知中NDIS_STATUS_INDICATION的 RequestId 成員值必須為非零，這是從相同交易中的對應要求複製。

您必須正確設定NDIS_STATUS_INDICATION結構的 RequestId 成員，非同步機制才能正常運作。 MB 服務可確保 RequestId 值在所有未完成的要求中是唯一的且非零。 迷你埠驅動程式必須在對應的指示中傳回相同的 RequestId 值，MB 服務才能將指示與開啟的交易相互關聯。

狀態指示結構

指定 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 成員中的值為零表示它是未經請求的事件通知，而且可以隨時發生。

如果任何集合或查詢 OID 要求傳回指示中的 uStatus 成員不等於 WWAN_STATUS_SUCCESS，則相關聯 NDIS_WWAN_XXX 結構的成員無需有效。

如果是以網路事件為基礎的未經請求的事件通知，迷你埠驅動程式必須視需要填入 uNwError 成員，如果適用。

下表顯示了GSM型網路的 3GPP TS 24.008 規範中定義的註冊、資料包連接和資料包分離原因代碼失敗值：

例如，如果網路發起停用上下文事件，因為所在地區不允許漫遊，miniport 驅動程式應該根據 3GPP TS 24.008 針對 GSM 型網路的原因碼，將 uNwError 成員設定為 13。

類似的邏輯也應應用於基於 CDMA 的網路。 但是，基於 CDMA 的網路錯誤代碼沒有標準。 CDMA 型裝置應該使用網路 -specific 或裝置特定的錯誤碼。

在迷你埠驅動程式對 OID 要求的非同步回應的情況下，NDIS_STATUS_INDICATION結構的 RequestId 成員是非零數字，作為 集合 或 查詢 要求的一部分傳遞至迷你埠驅動程式。 迷你埠驅動程式必須視需要填入 uStatus 成員。 例如，WWAN_STATUS_SUCCESS或下一節中列出的任何適當的錯誤值。 除此之外，迷你埠驅動程式必須在適當且可用的位置填入 uNwError 成員。

事件通知狀態

下表列出 MB 迷你埠驅動程式可以在 NDIS_WWAN_XXX 事件通知結構的 uStatus 成員中指定的 WWAN_STATUS 碼。

下表顯示 SMS 特定狀態值。

注意 這些 WWAN 特定的狀態碼僅用於 NDIS_WWAN_XXX 結構的 uStatus 成員中的非同步交易。

迷你埠驅動程式會使用事件通知來通知 MB 服務其 MB 裝置中的物件狀態變更，而不需要先收到 OID 要求。 MB 服務僅使用事件通知來更新其狀態機器。

請注意，雖然 NDIS 會序列化傳送至迷你埠驅動程式的所有要求，但迷你埠驅動程式可能不會以相同的順序傳回回應。 這是因為迷你埠驅動程式中的佇列要求可能會平行處理。 因此，MB 服務可確保如果兩個要求彼此相依，則在迷你埠驅動程式完成第一個要求之前，它不會傳送第二個要求。

狀態變更通知

一般而言，迷你埠驅動程式應該一律透過交易式通知或未經請求的事件通知，通知 MB 服務其 MB 裝置的更新狀態。 下列案例是一些例外狀況，其中迷你埠驅動程式不應該以更新的狀態資訊回應。 MB 服務可以從其他作業的完成狀態來判斷更新的狀態：

1. 迷你埠驅動程式不需要在發生 PIN 狀態變更時傳送NDIS_STATUS_WWAN_PIN_LIST事件指示，因為 MB 服務要求啟用或停用 PIN。

2. 迷你埠驅動程式不需要在交易回應中傳回布建內容的更新清單，以回應 OID_WWAN_PROVISIONED_CONTEXT set 作業。

3. 迷你埠驅動程式不需要在 OID_WWAN_PREFERRED_PROVIDERS設定 作業的交易回應中提交更新的慣用提供者清單。 MB 服務可以根據 設定 作業的初始清單和成功狀態來判斷此資訊。

4. 迷你埠驅動程式不需要回應針對 OID_WWAN_SMS_CONFIGURATION 設定 作業的當前 WWAN_SMS_CONFIGURATION 值。