PROTOCOL_CO_OID_REQUEST回呼函式（ndis.h）

發行項
02/07/2025

ProtocolCoOidRequest 函式會處理 CoNDIS 用戶端或獨立呼叫管理員藉由呼叫 NdisCoOidRequest 函式或小型埠呼叫管理員（MCM）驅動程式藉由呼叫 NdisMCmOidRequest 函式起始的 OID 要求。

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

語法

PROTOCOL_CO_OID_REQUEST ProtocolCoOidRequest;

NDIS_STATUS ProtocolCoOidRequest(
  [in]      NDIS_HANDLE ProtocolAfContext,
  [in]      NDIS_HANDLE ProtocolVcContext,
  [in]      NDIS_HANDLE ProtocolPartyContext,
  [in, out] PNDIS_OID_REQUEST OidRequest
)
{...}

參數

[in] ProtocolAfContext

識別位址系列（AF）內容區域的句柄。如果驅動程式是用戶端，則會在呼叫時提供此句柄 NdisClOpenAddressFamilyEx 函式，以自行連線到呼叫管理員。如果驅動程式是呼叫管理員，則會從其 ProtocolCmOpenAf 函式中提供此句柄。

[in] ProtocolVcContext

識別虛擬連線（VC）以查詢或設定相關信息的句柄，如果要求是 VC 專用的。否則，此參數會 NULL。

[in] ProtocolPartyContext

識別多點 VC 上要查詢或設定資訊之多點 VC 上合作物件的句柄，如果要求是特定合作物件。否則，此參數會 NULL。

[in, out] OidRequest

NDIS_OID_REQUEST 結構的指標，其中包含要處理之目標驅動程式的緩衝區和要求封包。根據要求，驅動程式會傳回結構中 OidRequest 指向的要求資訊。

傳回值

ProtocolCoOidRequest 可以傳回下列其中一項：

傳回碼	描述
NDIS_STATUS_SUCCESS	用戶端或呼叫管理員執行要求的作業。
NDIS_STATUS_PENDING	用戶端或呼叫管理員會以異步方式處理此要求，而且會呼叫 NdisCoOidRequestComplete 函式或當要求的作業完成時， NdisMCmOidRequestComplete 函式。
NDIS_STATUS_INVALID_LENGTH 或NDIS_STATUS_BUFFER_TOO_SHORT	驅動程式失敗要求，因為 NdisCoOidRequest 或 NdisMCmOidReque st 函式的呼叫者未為指定要求 InformationBufferNDIS_OID_REQUEST 成員提供適當的值。驅動程式會將緩衝區中NDIS_OID_REQUEST的 BytesNeeded 成員 OidRequest 參數設定為執行要求作業所需的 InformationBufferLength 成員的 OID 特定值。
NDIS_STATUS_XXX	用戶端或呼叫管理員因某些驅動程序決定的原因而失敗，例如為集合指定的輸入數據無效。
NDIS_STATUS_NOT_SUPPORTED	用戶端或呼叫管理員失敗此要求，因為它無法辨識緩衝區中 Oid 成員中OID_GEN_CO_XXX 程式代碼，NdisRequest。

言論

CoNDIS 用戶端、呼叫管理員和 MCM 需要 ProtocolCoOidRequest 函式。 ProtocolCoOidRequest 類似於迷你埠驅動程式的 MiniportCoOidRequest 函式。

CoNDIS 用戶端和呼叫管理員會在呼叫 NdisCoOidRequest 函式時，在 NdisAfHandle 參數中指定非NULL 值，來彼此傳送資訊。同樣地，MCM 會呼叫 NdisMCmOidRequest，並使用 NdisAfHandle 的明確值，將資訊傳達給用戶端。 NdisCoOidRequest 或 NdisMCmOidRequest 這類呼叫會導致 NDIS 呼叫目標用戶端、呼叫管理員或與指定 AF 句柄相關聯的 ProtocolCoOidRequest 函式。

若要將 protocolCoOidRequest 註冊為客戶端，驅動程式會初始化 NDIS_CO_CLIENT_OPTIONAL_HANDLERS 結構，並將它傳遞至 NdisSetOptionalHandlers 函式的 OptionalHandlers 參數。若要將 ProtocolCoOidRequest 註冊為呼叫管理員，驅動程式會初始化 NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS 結構，並將它傳遞給 OptionalHandlers 參數。

如果 NdisVcHandle 和 NdisPartyHandleNdisCoOidRequest 或 NdisMCmOidRequestNULL，則要求本質上為全域。也就是說，NdisVcHandle 或 NdisPartyHandle 明確值表示 ProtocolCoOidRequest 應分別以每一 VC 或每一方為基礎滿足指定的要求。

OidRequest 參數的緩衝區是從非分頁集區配置，因此可從引發的 IRQL 存取。 NdisCoOidRequest（或 NdisMCmOidRequest）的呼叫者必須釋放這個緩衝區，且 InformationBuffer 的內部緩衝區OidRequest 指向的 NDIS_OID_REQUEST 結構成員。

如果 ProtocolCoOidRequest 傳回NDIS_STATUS_PENDING，驅動程式必須接著呼叫 NdisCoOidRequestComplete 函式或當驅動程式完成要求時， NdisMCmOidRequestComplete 函式。

範例

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

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

PROTOCOL_CO_OID_REQUEST MyCoOidRequest;

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

_Use_decl_annotations_
NDIS_STATUS
 MyCoOidRequest(
    NDIS_HANDLE  ProtocolAfContext,
    NDIS_HANDLE  ProtocolVcContext,
    NDIS_HANDLE  ProtocolPartyContext,
    PNDIS_OID_REQUEST  OidRequest
    )
  {...}

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

如需 Use_decl_annotations的相關信息，請參閱批注函式行為。