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

Artículo
08/07/2023

La función ProtocolCoOidRequestComplete completa el procesamiento de una solicitud OID coNDIS asincrónica.

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

Sintaxis

PROTOCOL_CO_OID_REQUEST_COMPLETE ProtocolCoOidRequestComplete;

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

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 o un administrador de llamadas de minipuerto (MCM), proporcionó este identificador desde su función ProtocolCmOpenAf .

[in] ProtocolVcContext

Identificador que identifica la conexión virtual activa (VC) para la que el controlador solicitó o estableció información, si la solicitud era 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 para la que el controlador solicitó o establece información, si la solicitud es específica de la entidad. De lo contrario, este parámetro es NULL.

[in, out] OidRequest

Puntero a la estructura de NDIS_OID_REQUEST proporcionada por el controlador que se pasó anteriormente a la función NdisCoOidRequest o NdisMCmOidRequest .

[in] Status

Estado final de la solicitud. El controlador de destino o NDIS determina este estado final. Este parámetro determina qué hace ProtocolCoOidRequestComplete con la información de OidRequest.

Valor devuelto

None

Observaciones

NDIS llama a la función ProtocolCoOidRequestComplete para completar el procesamiento del cliente de CoNDIS, el administrador de llamadas o la solicitud OID de MCM para la que la función NdisCoOidRequest o la función NdisMCmOidRequest devolvieron NDIS_STATUS_PENDING.

Para registrar ProtocolCoOidRequestComplete 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 ProtocolCoOidRequestComplete como administrador de llamadas, un controlador inicializa un NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS estructura y la pasa en el parámetro OptionalHandlers de NdisSetOptionalHandlers.

El controlador de destino es el controlador que atuvo la solicitud de información de OID. Llamada del controlador de destino a NdisMCoOidRequestComplete, NdisCoOidRequestComplete o La función NdisMCmOidRequestComplete provocó que NDIS llamara a la función ProtocolCoOidRequestComplete . NDIS reenvía el valor del parámetro Status que se pasó a estas funciones como parámetro status de entrada a ProtocolCoOidRequestComplete.

ProtocolCoOidRequestComplete usa el valor de entrada de Status como se indica a continuación:

Si Status es NDIS_STATUS_SUCCESS, el miembro BytesRead o BytesWritten de la estructura NDIS_OID_REQUEST que apunta el parámetro OidRequest para especifica la cantidad de información que se transfirió desde el búfer en el miembro InformationBuffer de NDIS_OID_REQUEST al controlador de destino o la cantidad de información que se devolvió en InformationBuffer, respectivamente.
Si el controlador realizó una solicitud de consulta, ProtocolCoOidRequestComplete puede usar los datos que se devuelven en InformationBuffer según corresponda para el valor especificado en el miembro Oid de NDIS_OID_REQUEST.
Si Status es NDIS_STATUS_INVALID_LENGTH o NDIS_STATUS_BUFFER_TOO_SHORT, el miembro BytesNeeded de la estructura NDIS_OID_REQUEST que OidRequest apunta a especifica el valor específico del OID del miembro InformationBufferLength de NDIS_OID_REQUEST necesario para llevar a cabo la operación solicitada.
En estas circunstancias, ProtocolCoOidRequestComplete puede asignar suficiente espacio de búfer para la solicitud, configurar otra estructura de NDIS_OID_REQUEST con el valor necesario para InformationBufferLength y volver a intentar la solicitud de OID.
Si Status es un valor NDIS_STATUS_ XXX que es un error irrecuperable, ProtocolCoOidRequestComplete debe liberar la memoria de la estructura NDIS_OID_REQUEST. ProtocolCoOidRequestComplete también debe determinar si el controlador debe cerrar el enlace o ajustar su información de estado específica del enlace para controlar las operaciones continuas de E/S de red en el enlace.

Para obtener más información sobre los OID definidos por el sistema, consulte NDIS OIDs.

Se puede llamar a ProtocolCoOidRequestComplete antes de que el controlador tenga tiempo de inspeccionar el código de estado que devuelve NdisCoOidRequest o NdisMCmOidRequest.

NDIS llama a ProtocolCoOidRequestComplete en IRQL <= DISPATCH_LEVEL.

Ejemplos

Para definir una función ProtocolCoOidRequestComplete , primero debe proporcionar una declaración de función que identifique el tipo de función que está definiendo. 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 ProtocolCoOidRequestComplete denominada "MyCoOidRequestComplete", use el tipo de PROTOCOL_CO_OID_REQUEST_COMPLETE como se muestra en este ejemplo de código:

PROTOCOL_CO_OID_REQUEST_COMPLETE MyCoOidRequestComplete;

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

_Use_decl_annotations_
VOID
 MyCoOidRequestComplete(
    NDIS_HANDLE  ProtocolAfContext,
    NDIS_HANDLE  ProtocolVcContext,
    NDIS_HANDLE  ProtocolPartyContext,
    PNDIS_OID_REQUEST  OidRequest,
    NDIS_STATUS  Status
    )
  {...}

El tipo de función PROTOCOL_CO_OID_REQUEST_COMPLETE 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_COMPLETE en el archivo de encabezado. Para obtener más información sobre los requisitos de las declaraciones de función, consulte Declaración de funciones mediante el uso de 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	Se admite en NDIS 6.0 y versiones posteriores.
Plataforma de destino	Windows
Encabezado	ndis.h (incluya Ndis.h)
IRQL	<= DISPATCH_LEVEL (consulte la sección Comentarios)