PROTOCOL_CO_OID_REQUEST función de devolución de llamada (ndis.h)

Artículo
03/08/2023

La función ProtocolCoOidRequest controla las solicitudes de OID que los clientes de CoNDIS o los administradores de llamadas independientes inician mediante llamadas a la función NdisCoOidRequest o que un controlador de miniportador de llamadas (MCM) se inicia mediante llamadas a la función NdisMCmOidRequest .

Nota Debe declarar la función mediante el tipo PROTOCOL_CO_OID_REQUEST . Para obtener más información, consulte la sección Ejemplos siguientes.

Sintaxis

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
)
{...}

Parámetros

[in] ProtocolAfContext

Identificador que identifica un área de contexto de familia de direcciones (AF). Si el controlador es un cliente, proporcionó este identificador cuando llamó a . Función NdisClOpenAddressFamilyEx para conectarse al administrador de llamadas. Si el controlador es un administrador de llamadas, proporcionó este identificador desde su función ProtocolCmOpenAf .

[in] ProtocolVcContext

Identificador que identifica la conexión virtual (VC) en la que se va a consultar o establecer información, si la solicitud es específica de VC. De lo contrario, este parámetro es NULL.

[in] ProtocolPartyContext

Identificador que identifica a la entidad en una credencial verificable de varios puntos en la que consultar o establecer información, si la solicitud es específica de la entidad. De lo contrario, este parámetro es NULL.

[in, out] OidRequest

Puntero a una estructura de NDIS_OID_REQUEST que contiene el búfer y el paquete de solicitud para que el controlador de destino lo controle. Dependiendo de la solicitud, el controlador devuelve la información solicitada en la estructura a la que apunta OidRequest .

Valor devuelto

ProtocolCoOidRequest puede devolver una de las siguientes opciones:

Código devuelto	Descripción
NDIS_STATUS_SUCCESS	El cliente o el administrador de llamadas llevaron a cabo la operación solicitada.
NDIS_STATUS_PENDING	El cliente o el administrador de llamadas controla esta solicitud de forma asincrónica y llamará a . Función NdisCoOidRequestComplete o la Función NdisMCmOidRequestComplete cuando se completa la operación solicitada.
NDIS_STATUS_INVALID_LENGTH o NDIS_STATUS_BUFFER_TOO_SHORT	El controlador produce un error en la solicitud porque el autor de la llamada de la función NdisCoOidRequest o NdisMCmOidRequest no ha proporcionado un valor adecuado para el miembro InformationBuffer de la estructura de NDIS_OID_REQUEST para la solicitud especificada. El controlador establece el miembro BytesNeeded de NDIS_OID_REQUEST en el búfer en el parámetro OidRequest en el valor específico del OID del miembro InformationBufferLength necesario para llevar a cabo la operación solicitada.
NDIS_STATUS_XXX	El cliente o el administrador de llamadas no pudieron solicitar algún motivo determinado por el controlador, como datos de entrada no válidos especificados para un conjunto.
NDIS_STATUS_NOT_SUPPORTED	El cliente o el administrador de llamadas produjo un error en esta solicitud porque no reconoció el código OID_GEN_CO_XXX en el miembro Oid del búfer en NdisRequest.

Comentarios

La función ProtocolCoOidRequest es necesaria para clientes de CoNDIS, administradores de llamadas y MCM. ProtocolCoOidRequest es similar a la función MiniportCoOidRequest del controlador miniport .

Los clientes coNDIS y los administradores de llamadas envían información entre sí especificando un valor distinto de NULL en el parámetro NdisAfHandle cuando llaman a la función NdisCoOidRequest . Del mismo modo, los MCM llaman a NdisMCmOidRequest con valores explícitos para que NdisAfHandle comunique información a los clientes. Estas llamadas a NdisCoOidRequest o NdisMCmOidRequest hacen que NDIS llame a la función ProtocolCoOidRequest del cliente de destino, el administrador de llamadas o MCM asociado al identificador de AF especificado.

Para registrar ProtocolCoOidRequest como cliente, un controlador inicializa un NDIS_CO_CLIENT_OPTIONAL_HANDLERS estructura y la pasa en el parámetro OptionalHandlers de la función NdisSetOptionalHandlers . Para registrar ProtocolCoOidRequest como administrador de llamadas, un controlador inicializa un NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS estructura y la pasa en el parámetro OptionalHandlers .

Si los parámetros NdisVcHandle y NdisPartyHandle de NdisCoOidRequest o NdisMCmOidRequest son NULL, la solicitud es global por naturaleza. Es decir, un valor explícito para NdisVcHandle o NdisPartyHandle indica que ProtocolCoOidRequest debe satisfacer la solicitud dada por VC o por parte, respectivamente.

El búfer del parámetro OidRequest se asignó desde un grupo no paginado y es, por lo tanto, accesible en IRQL elevado. El autor de la llamada de NdisCoOidRequest(o NdisMCmOidRequest) debe liberar este búfer y el búfer interno en el miembro InformationBuffer de la estructura NDIS_OID_REQUEST a la que apunta OidRequest .

Si ProtocolCoOidRequest devuelve NDIS_STATUS_PENDING, el controlador debe llamar posteriormente al Función NdisCoOidRequestComplete o Función NdisMCmOidRequestComplete para un controlador MCM, cuando el controlador completa la solicitud.

Ejemplos

Para definir una función ProtocolCoOidRequest , primero debe proporcionar una declaración de función que identifique el tipo de función que va a definir. Windows proporciona un conjunto de tipos de función para controladores. Declarar una función mediante los tipos de función ayuda a Code Analysis for Drivers, Static Driver Verifier (SDV) y otras herramientas de comprobación a encontrar errores y es un requisito para escribir controladores para el sistema operativo Windows.

Por ejemplo, para definir una función ProtocolCoOidRequest denominada "MyCoOidRequest", use el tipo PROTOCOL_CO_OID_REQUEST como se muestra en este ejemplo de código:

PROTOCOL_CO_OID_REQUEST MyCoOidRequest;

A continuación, implemente la función de la siguiente manera:

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

El tipo de función PROTOCOL_CO_OID_REQUEST se define en el archivo de encabezado Ndis.h. Para identificar con más precisión los errores al ejecutar las herramientas de análisis de código, asegúrese de agregar la anotación Use_decl_annotations a la definición de función. La anotación Use_decl_annotations garantiza que se usen las anotaciones que se aplican al tipo de función PROTOCOL_CO_OID_REQUEST en el archivo de encabezado. Para obtener más información sobre los requisitos de las declaraciones de función, vea Declarar funciones mediante tipos de roles de función para controladores NDIS.

Para obtener información sobre Use_decl_annotations, consulte Anotación del comportamiento de la función.

Requisitos

Requisito	Value
Cliente mínimo compatible	Compatible con NDIS 6.0 y versiones posteriores.
Plataforma de destino	Windows
Encabezado	ndis.h (incluya Ndis.h)
IRQL	<= DISPATCH_LEVEL