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

Artículo
08/07/2023

La función ProtocolDirectOidRequestComplete completa el procesamiento de una solicitud de OID directa iniciada por el controlador de protocolo para la que la función NdisDirectOidRequest devolvió NDIS_STATUS_PENDING.

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

Sintaxis

PROTOCOL_DIRECT_OID_REQUEST_COMPLETE ProtocolDirectOidRequestComplete;

void ProtocolDirectOidRequestComplete(
  [in] NDIS_HANDLE ProtocolBindingContext,
  [in] PNDIS_OID_REQUEST OidRequest,
  [in] NDIS_STATUS Status
)
{...}

Parámetros

[in] ProtocolBindingContext

Identificador de un área de contexto asignada por controlador de protocolo en la que el controlador de protocolo mantiene el estado en tiempo de ejecución por enlace. El controlador proporcionó este identificador cuando llamó a la función NdisOpenAdapterEx .

[in] OidRequest

Puntero a la estructura de NDIS_OID_REQUEST proporcionada por el controlador de protocolo que se pasó anteriormente a la función NdisDirectOidRequest .

[in] Status

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

Valor devuelto

None

Observaciones

ProtocolDirectOidRequestComplete es una función opcional. Si un controlador de protocolo no usa solicitudes OID directas, puede establecer el punto de entrada de esta función en NULL cuando llama a . Función NdisRegisterProtocolDriver .

ProtocolDirectOidRequestComplete usa el valor de entrada del parámetro Status de la siguiente manera:

Si Status es NDIS_STATUS_SUCCESS, el miembro BytesRead o BytesWritten de la estructura NDIS_OID_REQUEST se ha establecido mediante NDIS o el controlador subyacente. Estos valores especifican la cantidad de información proporcionada por el controlador de protocolo que se transfirió desde el búfer en InformationBuffer a la NIC en una operación de conjunto o la cantidad de información que se devolvió en InformationBuffer en respuesta a una operación de consulta.
Si el controlador de protocolo realizó una consulta, ProtocolDirectOidRequestComplete puede usar los datos que se devuelven en InformationBuffer de cualquier manera que determine el controlador de protocolo, según el valor del miembro Oid .

Por ejemplo, si el controlador de protocolo inició originalmente un OID_GEN_MAXIMUM_SEND_PACKETS consulta, ProtocolDirectOidRequestComplete puede configurar variables de estado en el área ProtocolBindingContext para limitar el número de envíos pendientes que el controlador configurará para las llamadas posteriores a . Función NdisSendNetBufferLists .
Si Status es NDIS_STATUS_INVALID_LENGTH o NDIS_STATUS_BUFFER_TOO_SHORT, el miembro BytesNeeded especifica el valor específico del OID del miembro InformationBufferLength necesario para llevar a cabo la operación solicitada.
En estas circunstancias, ProtocolDirectOidRequestComplete puede asignar suficiente espacio de búfer para la solicitud, configurar otra estructura de NDIS_OID_REQUEST con el valor InformationBufferLength necesario y el mismo valor Oid , y volver a intentar la llamada a la función NdisDirectOidRequest .

ProtocolDirectOidRequestComplete puede reintentar solicitudes para otros argumentos NDIS_STATUS_ Xxx , como se describe en NdisDirectOidRequest.
Si Status es un valor de NDIS_STATUS_ Xxx que es un error irrecuperable, ProtocolDirectOidRequestComplete debe liberar la memoria asignada para la estructura de NDIS_OID_REQUEST y determinar si el controlador debe cerrar el enlace o ajustar su información de estado específica del enlace para controlar las operaciones de E/S de red continuas en el enlace.

Se puede llamar a ProtocolDirectOidRequestComplete antes de que el controlador de protocolo tenga tiempo para inspeccionar el código de estado que devuelve NdisDirectOidRequest en Status.

NDIS llama a ProtocolDirectOidRequestComplete en IRQL <= DISPATCH_LEVEL.

Ejemplos

Para definir una función ProtocolDirectOidRequestComplete , 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 ProtocolDirectOidRequestComplete denominada "MyDirectOidRequestComplete", use el tipo de PROTOCOL_DIRECT_OID_REQUEST_COMPLETE como se muestra en este ejemplo de código:

PROTOCOL_DIRECT_OID_REQUEST_COMPLETE MyDirectOidRequestComplete;

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

_Use_decl_annotations_
VOID
 MyDirectOidRequestComplete(
    NDIS_HANDLE  ProtocolBindingContext,
    PNDIS_OID_REQUEST  OidRequest,
    NDIS_STATUS  Status
    )
  {...}

El tipo de función PROTOCOL_DIRECT_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_DIRECT_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.1 y versiones posteriores.
Plataforma de destino	Windows
Encabezado	ndis.h (incluya Ndis.h)
IRQL	<= DISPATCH_LEVEL