MINIPORT_CO_OID_REQUEST回呼函式 (ndis.h)

發行項
02/26/2024

MiniportCoOidRequest 函式會處理 OID 要求，以查詢或設定 CoNDIS 迷你埠驅動程式中的資訊。

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

語法

MINIPORT_CO_OID_REQUEST MiniportCoOidRequest;

NDIS_STATUS MiniportCoOidRequest(
  [in] NDIS_HANDLE MiniportAdapterContext,
  [in] NDIS_HANDLE MiniportVcContext,
       PNDIS_OID_REQUEST NdisRequest
)
{...}

參數

[in] MiniportAdapterContext

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

[in] MiniportVcContext

迷你埠驅動程式配置的內容區域句柄，迷你埠驅動程序會維護其每個虛擬連線 (VC) 狀態。迷你埠驅動程式已從其 MiniportCoCreateVc 函式提供此句柄給NDIS。如果要求不是 VC 特定，則此參數為 NULL。

NdisRequest

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

傳回值

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

傳回碼	Description
NDIS_STATUS_SUCCESS	迷你埠驅動程式會依照要求設定或取得數據。
NDIS_STATUS_PENDING	迷你埠驅動程式會以異步方式完成要求。迷你埠驅動程式完成所有處理之後，它必須呼叫 NdisMCoOidRequestComplete 函式會通知 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 iwas 上為要求指定的一或多個參數無效。
NDIS_STATUS_NOT_ACCEPTED	在 NDIS 呼叫之後 MiniportDevicePnPEventNotify 函式表示意外移除，NDIS 會呼叫驅動程式的 MiniportHaltEx 函式。如果驅動程式在 NDIS 呼叫 MiniportHaltEx 之前收到任何 OID 要求，它應該會立即完成這類要求，且狀態值為 NDIS_STATUS_NOT_ACCEPTED。
NDIS_STATUS_REQUEST_ABORTED	迷你埠驅動程式已停止處理要求。例如，NDIS 稱為 MiniportResetEx 或 MiniportCancelOidRequest 函式。

備註

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

若要註冊 MiniportCoOidRequest，迷你埠驅動程式會從 MiniportSetOptions 函式呼叫 NdisSetOptionalHandlers 函式。在 MiniportSetOptions 中，迷你埠驅動程式會初始化 NDIS_MINIPORT_CO_CHARACTERISTICS 結構，並將它傳遞至 NdisSetOptionalHandlers 的 OptionalHandlers 參數。

NDIS 代表自己呼叫 MiniportCoOidRequest 函式，或代表呼叫 NdisCoOidRequest 函式的系結通訊協定驅動程式。迷你埠驅動程序應該檢查 OidRequest 所提供的要求，並採取所要求的動作。如需迷你埠驅動程序處理之 OID 的詳細資訊，請參閱 NDIS OID。

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

如果 MiniportCoOidRequest 傳回NDIS_STATUS_PENDING，NDIS 可以針對 MiniportAdapterContext 中指定的迷你埠配接器呼叫 MiniportCoOidRequest，然後再完成擱置的要求。 NDIS 不會串行化連線導向的 OID 要求。

例子

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

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

MINIPORT_CO_OID_REQUEST MyCoOidRequest;

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

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

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

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