MINIPORT_DIRECT_OID_REQUEST回呼函式 (ndis.h)

發行項
02/29/2024

NDIS 會呼叫迷你埠驅動程式的 MiniportDirectOidRequest 函式來處理直接 OID 要求，以查詢或設定驅動程式中的資訊。

注意您必須使用 MINIPORT_DIRECT_OID_REQUEST 類型來宣告函式。如需詳細資訊，請參閱下列範例一節。

語法

MINIPORT_DIRECT_OID_REQUEST MiniportDirectOidRequest;

NDIS_STATUS MiniportDirectOidRequest(
  [in] NDIS_HANDLE MiniportAdapterContext,
  [in] PNDIS_OID_REQUEST OidRequest
)
{...}

參數

[in] MiniportAdapterContext

迷你埠驅動程式在其 MiniportInitializeEx 函式中配置的內容區域句柄。迷你埠驅動程式會使用此內容區域來維護迷你埠適配卡的狀態資訊。

[in] OidRequest

包含要處理之迷你埠驅動程式之緩衝區和要求封包之 NDIS_OID_REQUEST 結構的指標。根據要求，驅動程式會傳回所提供結構中所要求的資訊。

傳回值

MiniportDirectOidRequest 可以傳回下列其中一個狀態值：

傳回碼	Description
NDIS_STATUS_SUCCESS	迷你埠驅動程式會依照要求來設定或取得數據。
NDIS_STATUS_PENDING	迷你埠驅動程式會以異步方式完成要求。在迷你埠驅動程式完成所有處理之後，它必須呼叫 NdisMDirectOidRequestComplete 函式，以通知 NDIS 要求已完成。
NDIS_STATUS_INVALID_OID	指定 OidRequest 的要求無效或無法辨識。
NDIS_STATUS_NOT_SUPPORTED	已辨識 OidRequest 指定的要求，但迷你埠驅動程序不支援它。
NDIS_STATUS_BUFFER_TOO_SHORT	OidRequest 提供的緩衝區太小，無法保存要求的數據。
NDIS_STATUS_INVALID_LENGTH	在 OidRequest 之 NDIS_OID_REQUEST 結構之 InformationBufferLength 成員中指定的值對於指定的OID_Xxx 程式代碼而言不正確。
NDIS_STATUS_INVALID_DATA	在 OidRequest 上為要求指定的一或多個參數無效。
NDIS_STATUS_NOT_ACCEPTED	呼叫之後 MiniportDevicePnPEventNotify 函式表示意外移除，NDIS 稱為驅動程式的 MiniportHaltEx 函式。如果驅動程式在 NDIS 呼叫 MiniportHaltEx 之前收到任何 OID 要求，它應該會立即完成狀態值為 NDIS_STATUS_NOT_ACCEPTED 的這類要求。
NDIS_STATUS_REQUEST_ABORTED	迷你埠驅動程式已停止處理要求。例如，NDIS 稱為 MiniportResetEx 函式。
NDIS_STATUS_INDICATION_REQUIRED	迷你埠驅動程式會提供具有後續狀態指示的 OID 完成狀態。除非特定的 OID 允許，否則迷你埠驅動程式無法傳回NDIS_STATUS_INDICATION_REQUIRED。若要判斷是否允許此狀態，請參閱 OID 參考頁面。如需NDIS_STATUS_INDICATION_REQUIRED的詳細資訊，請參閱 NDIS_OID_REQUEST 和 NDIS_STATUS_INDICATION。

備註

MiniportDirectOidRequest 是選擇性函式。如果迷你埠驅動程序處理直接 OID 要求，則會註冊此函式。驅動程式會在呼叫時指定 MiniportDirectOidRequest 進入點 NdisMRegisterMiniportDriver 函式。註冊的迷你埠驅動程式 MiniportCancelDirectOidRequest 函式也必須註冊 MiniportDirectOidRequest。

NDIS 代表自己呼叫 MiniportDirectOidRequest 函式，或代表呼叫 NdisDirectOidRequest 函式的系結通訊協定驅動程式。迷你埠驅動程序應該檢查 在 OidRequest 參數提供的要求，並採取所要求的動作。

請注意，NDIS 不會驗證 OidRequest 上的 OID 特定內容。因此，驅動程式本身必須驗證這些內容。如果驅動程式判斷要設定的值超出界限，它應該會失敗要求並傳回NDIS_STATUS_INVALID_DATA。

NDIS 不會串行化它與其他 OID 要求一起傳送至 MiniportDirectOidRequest 的要求。當傳送至 MiniportOidRequest 或 MiniportDirectOidRequest 的其他要求未處理時，迷你埠驅動程式必須能夠處理對 MiniportDirectOidRequest 的多個呼叫。

注意如果迷你埠驅動程式在 MiniportOidRequest 呼叫的內容中等候，NDIS檢查停止回應邏輯將不會重設未回應的迷你埠驅動程式。因此，迷你埠驅動程式不應等候硬體作業從 MiniportOidRequest 呼叫的內容中完成。相反地，驅動程式可以傳回NDIS_STATUS_PENDING並將工作專案排入佇列。

NDIS 會在 IRQL <= DISPATCH_LEVEL 呼叫 MiniportDirectOidRequest 。

例子

若要定義 MiniportDirectOidRequest 函式，您必須先提供函式宣告來識別您要定義的函式類型。 Windows 提供一組驅動程式的函式類型。使用函式類型宣告函式有助於驅動程式的程式代碼分析、靜態驅動程式驗證程式 (SDV) ，以及其他驗證工具尋找錯誤，而且是撰寫 Windows 作業系統驅動程式的需求。

例如，若要定義名為「 MyDirectOidRequest」的 MiniportDirectOidRequest 函式，請使用 MINIPORT_DIRECT_OID_REQUEST 類型，如下列程式代碼範例所示：

MINIPORT_DIRECT_OID_REQUEST MyDirectOidRequest;

然後，實作您的函式，如下所示：

_Use_decl_annotations_
NDIS_STATUS
 MyDirectOidRequest(
    NDIS_HANDLE  MiniportAdapterContext,
    PNDIS_OID_REQUEST  OidRequest
    )
  {...}

MINIPORT_DIRECT_OID_REQUEST函式類型定義於 Ndis.h 頭檔中。若要在執行程式代碼分析工具時更精確地識別錯誤，請務必將 Use_decl_annotations 批註新增至函式定義。 Use_decl_annotations批註可確保使用頭檔中套用至MINIPORT_DIRECT_OID_REQUEST函式類型的註釋。如需函數宣告需求的詳細資訊，請參閱使用 NDIS 驅動程式的函式角色類型來宣告函式。

如需 Use_decl_annotations的詳細資訊，請參閱標註函式行為。