撰寫 MBBCx 用戶端驅動程式

發行項
03/19/2025

警告

本主題中的循序圖僅供說明之用。它們不是公共合同，未來可能會改變。

MBBCx 用戶端驅動程式的 INF 檔案

MBBCx 用戶端驅動程式的 INF 檔案與其他 NetAdapterCx 用戶端驅動程式相同。如需詳細資訊，請參閱 NetAdapterCx 用戶端驅動程式的 INF 檔案。

請遵循通用指引，以確保 INF 檔案符合通用需求。

初始化裝置

除了 NetAdapterCx 針對 NetAdapter 裝置初始化所需的工作之外，MBB 用戶端驅動程式也必須在其 EvtDriverDeviceAdd 回呼函式中執行下列工作：

呼叫 NetDeviceInitConfig 之後呼叫 MBB_DEVICE_CONFIG_INIT，但在呼叫 WdfDeviceCreate之前，參考架構傳入的相同 WDFDEVICE_INIT 物件。
呼叫 MbbDeviceInitialize，以使用初始化的 MBB_DEVICE_CONFIG 結構和從 WdfDeviceCreate取得的 WDFDEVICE 對象來註冊 MBB 裝置特定回呼函式。

下列範例示範如何初始化 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 裝置的操作模型，如 MBIM 規格 Rev 1.0 第 5.3 節中所定義，並使用以下函式呼叫來達到目的：

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 架構會先將裝置帶到 D0 （換句話說，它會在呼叫 EvtDeviceD0Entry之前呼叫 EvtMbbDeviceSendMbimFragment 或 EvtMbbDeviceReceiveMbimFragment。 MBBCx 架構也保證它會讓裝置保持在 D0 狀態，這表示在用戶端呼叫 MbbRequestComplete 或 MbbRequestCompleteWithInformation之前，它不會呼叫 EvtDeviceD0Exit。

為 PDP 上下文/EPS 承載建立 NetAdapter 介面

建立數據會話之前，MBBCx 會指示用戶端驅動程式建立 NETADAPTER 物件，而且 MBBCx 會使用它來代表啟動之數據會話的網路介面。這是透過 MBBCx 呼叫用戶端驅動程式的 EvtMbbDeviceCreateAdapter 回呼函式來完成。

在 EvtMbbDeviceCreateAdapter 回呼函式的實作中，MBBCx 用戶端驅動程式必須先執行與任何 NetAdapterCx 用戶端驅動程式建立 NETADAPTER 物件所需的相同工作。此外，它也必須執行下列其他工作：

在由 NetAdapterCreate所建立的 NETADAPTER 物件上，呼叫 MbbAdapterInitialize。
呼叫 MbbAdapterinitialize之後，請呼叫 MbbAdapterGetSessionId 來重新擷取 MBBCx 想要使用此 NETADAPTER 物件的數據會話標識符。例如，如果傳回的值是 0，表示 MBBCx 會針對主要 PDP 內容/預設 EPS 持有人所建立的數據會話使用此 NETADAPTER 介面。
建議 MBBCx 用戶端驅動程式在建立的 NETADAPTER 對象與傳回 的 SessionId之間保留內部對應。這有助於追蹤數據會話與 NETADAPTER 對象的關聯性，這在啟用多個 PDP 上下文/EPS 承載時特別有用。
從 EvtMbbDeviceCreateAdapter傳回之前，客戶端驅動程式必須呼叫 NetAdapterStart來啟動配接器。或者，您也可以在呼叫 netAdapterStart 之前，先呼叫一或多個函式，再呼叫NetAdapterStart 來設定配接器的功能：

MBBCx 至少會叫用此回呼函式一次，因此主要 PDP 內容/預設 EPS 承載一律有一個 NETADAPTER 物件。如果啟動多個 PDP 上下文/EPS 負載，MBBCx 可能會多次調用此回呼函式，每個數據會話的建立都可能調用一次。 NETADAPTER 物件所代表的網路介面與數據會話之間必須有一對一關聯性，如下圖所示。

顯示不同數據會話之多個 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;
    }

如需設定 datapath 功能的程式代碼範例，請參閱網路數據緩衝區管理。

MBBCx 保證它會在要求具有相同會話標識符的 MBIM_CID_CONNECT 之前，先呼叫 EvtMbbDeviceCreateAdapter。下列流程圖顯示客戶端驅動程式與建立NETADAPTER物件時類別延伸模組之間的互動。

顯示 MBB 用戶端驅動程式的 NETADAPTER 建立和啟用的圖表。

MBBCx 在 EvtDevicePrepareHardware 成功完成後，初始化主要 PDP 內容/預設 EPS 承載的 NETADAPTER 物件過程。

每當應用程式要求隨需連線時，WwanSvc 就會觸發為次要 PDP 上下文/專用 EPS 承載建立 NETADAPTER 物件的流程。

NETADAPTER 物件的存留期

用戶端驅動程式所建立的 NETADAPTER 物件會在不再使用時由 MBBCx 自動終結。例如，這在停用其他 PDP 上下文/EPS 承載後會發生。 MBBCx 用戶端驅動程式不得在所建立的 NETADAPTER 物件上呼叫 WdfObjectDelete。

如果客戶端驅動程式需要清除系結至 NETADAPTER 物件的內容數據，它應該會在呼叫 netAdapterCreate 時，在物件屬性結構中提供 EvtDestroyCallback 函式。

MBB 裝置的電源管理

針對電源管理，用戶端驅動程序應該使用NETPOWERSETTINGS物件，就像其他類型的 NetAdapterCx 用戶端驅動程式一樣，。

處理裝置服務會話

當應用程式將 DSS 資料傳送至數據機裝置時，MBBCx 會叫用用戶端驅動程式的 EvtMbbDeviceSendServiceSessionData 回呼函式。然後，客戶端驅動程式應該以異步方式將數據傳送至裝置，並在傳送完成後呼叫 MbbDeviceSendDeviceServiceSessionDataComplete，因此 MBBCx 接著可以釋放配置給數據的記憶體。

相反地，用戶端驅動程式會呼叫 MbbDeviceReceiveDeviceServiceSessionData，以透過 MBBCx 將任何數據傳遞至應用程式。

Windows 驅動程式相容需求

遵守 DCH 設計原則
遵循驅動程式套件隔離原則
遵循 API 分層需求
使用 Hardware Lab Kit，通過 Windows 硬體相容性計劃認證流程進行認證。

共用方式為