PROTOCOL_CO_OID_REQUEST回呼函式 (ndis.h)

發行項
02/26/2024

ProtocolCoOidRequest 函式會處理 CoNDIS 用戶端或獨立呼叫管理員藉由呼叫 NdisCoOidRequest 函式所起始的 OID 要求，或是迷你埠呼叫管理員 (MCM) 驅動程式會藉由呼叫 NdisMCmOidRequest 函式來起始。

注意您必須使用 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) 查詢或設定資訊的句柄。否則，此參數為 NULL。

[in] ProtocolPartyContext

句柄，識別多點 VC 上要查詢或設定相關信息的句柄，如果要求是特定合作物件。否則，此參數為 NULL。

[in, out] OidRequest

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

傳回值

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

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

備註

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

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

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

如果 NdisVcHandle 和 NdisPartyHandle 參數的 NdisCoOidRequest 或 NdisMCmOidRequest 為 NULL，則要求本質上為全域。也就是說，NdisVcHandle 或 NdisPartyHandle 的明確值表示 ProtocolCoOidRequest 應該分別滿足每個 VC 或每一方的特定要求。

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

如果 ProtocolCoOidRequest 傳回NDIS_STATUS_PENDING，驅動程式必須接著呼叫 NdisCoOidRequestComplete 函式或當驅動程式完成要求時，MCM 驅動程式的 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的詳細資訊，請參閱標註函式行為。