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

Artículo
08/07/2023

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

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

Sintaxis

PROTOCOL_OID_REQUEST_COMPLETE ProtocolOidRequestComplete;

void ProtocolOidRequestComplete(
  [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 NdisOidRequest .

[in] Status

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

Valor devuelto

None

Observaciones

ProtocolOidRequestComplete usa el valor de entrada de Status de la siguiente manera:

Si Status es NDIS_STATUS_SUCCESS, el miembro BytesRead o BytesWritten de la estructura de NDIS_OID_REQUEST se ha establecido mediante NDIS o el controlador subyacente para especificar 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, ProtocolOidRequestComplete puede usar los datos devueltos en InformationBuffer de cualquier manera determinado por 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, ProtocolOidRequestComplete 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 la 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, ProtocolOidRequestComplete puede asignar suficiente espacio en búfer para la solicitud, configurar otra estructura de NDIS_OID_REQUEST con la informationBufferLength necesaria y el mismo Oid, y volver a intentar la llamada a la función NdisOidRequest .

ProtocolOidRequestComplete puede reintentar solicitudes para otros argumentos NDIS_STATUS_ XXX , así como se describe en la referencia de la función NdisOidRequest .
Si Status es un valor NDIS_STATUS_ XXX que es un error irrecuperable, ProtocolOidRequestComplete 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.

En el caso de las consultas globales y los conjuntos, la llamada del controlador de miniporte sin conexión subyacente a la función NdisMOidRequestComplete hace que NDIS llame a la función ProtocolOidRequestComplete . NDIS reenvía el estado determinado por el controlador de miniporte pasado a NdisMOidRequestComplete como estado de entrada a ProtocolOidRequestComplete.

Para las consultas específicas del enlace, NDIS llama a la propia función ProtocolOidRequestComplete . Dado que la biblioteca NDIS mantiene enlaces para todos los controladores de minipuerto, NDIS puede devolver información específica del enlace solo sobre los controladores subyacentes que informan de su tipo medio como uno para el que el sistema proporciona una biblioteca de filtros. NDIS devuelve NDIS_STATUS_NOT_SUPPORTED para las consultas específicas del enlace iniciadas por el controlador de protocolo a otros controladores de miniporte.

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

Se puede llamar a ProtocolOidRequestComplete antes de que el controlador de protocolo tenga tiempo para inspeccionar el código de estado que devuelve NdisOidRequest en Estado.

NDIS llama a ProtocolOidRequestComplete en IRQL <= DISPATCH_LEVEL.

Ejemplos

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

PROTOCOL_OID_REQUEST_COMPLETE MyOidRequestComplete;

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

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

El tipo de función PROTOCOL_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_OID_REQUEST_COMPLETE 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