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

Artículo
08/07/2023

NDIS llama a la función ProtocolBindAdapterEx de un controlador de protocolo para solicitar al controlador que se enlace a un adaptador de minipuerto.

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

Sintaxis

PROTOCOL_BIND_ADAPTER_EX ProtocolBindAdapterEx;

NDIS_STATUS ProtocolBindAdapterEx(
  [in] NDIS_HANDLE ProtocolDriverContext,
  [in] NDIS_HANDLE BindContext,
  [in] PNDIS_BIND_PARAMETERS BindParameters
)
{...}

Parámetros

[in] ProtocolDriverContext

Identificador de un área de contexto asignada por el controlador donde el controlador mantiene la información de estado y configuración. El controlador de protocolo pasó este área de contexto al Función NdisRegisterProtocolDriver .

[in] BindContext

Identificador que identifica el área de contexto de NDIS para esta operación de enlace.

[in] BindParameters

Puntero a una estructura de NDIS_BIND_PARAMETERS que creó NDIS.

Valor devuelto

ProtocolBindAdapterEx devuelve uno de los siguientes valores de estado:

Código devuelto	Descripción
NDIS_STATUS_SUCCESS	ProtocolBindAdapterEx completó correctamente el enlace al adaptador de minipuerto subyacente.
NDIS_STATUS_PENDING	ProtocolBindAdapterEx no completó la operación de enlace y la operación se completará de forma asincrónica. El controlador de protocolo debe llamar a . Función NdisCompleteBindAdapterEx cuando se completa la operación.
NDIS_STATUS_RESOURCES	ProtocolBindAdapterEx no pudo asignar los recursos que el controlador necesita para llevar a cabo operaciones de E/S de red.
NDIS_STATUS_XXX o NTSTATUS_XXX	Error en el intento del controlador de protocolo para configurar un enlace. Normalmente, este estado de error se propaga desde una función NdisXxx o una rutina de compatibilidad con modo kernel.

Comentarios

ProtocolBindAdapterEx es una función necesaria. NDIS llama a ProtocolBindAdapterEx para realizar operaciones de enlace cada vez que un adaptador de miniport subyacente, al que el controlador de protocolo puede enlazar, está disponible.

ProtocolBindAdapterEx asigna suficiente memoria para mantener la información de contexto de enlace y llama a la función NdisOpenAdapterEx para enlazarse a sí mismo con el adaptador de miniport subyacente. ProtocolBindAdapterEx pasa un puntero a la información de contexto de enlace en el parámetro ProtocolBindingContext de NdisOpenAdapterEx. ProtocolBindAdapterEx pasa el valor en el miembro AdapterName de su parámetro BindParameters como miembro AdapterName del parámetro OpenParameters de NdisOpenAdapterEx.

Antes de que el controlador llame a NdisOpenAdapterEx, el controlador puede pasar el puntero en BindParameters a la función NdisOpenConfigurationEx para leer los parámetros de configuración asociados a un adaptador de miniport.

Después de abrir correctamente el adaptador de minipuerto, el controlador puede pasar el identificador del parámetro NdisHandle de NdisOpenAdapterEx a NdisOpenConfigurationEx para obtener un identificador a la ubicación del Registro donde se almacenan los parámetros de configuración de un enlace de protocolo.

ProtocolBindAdapterEx pasa NdisOpenAdapterEx un puntero a una matriz de valores de tipo medio que enumera los tipos de medios que el controlador de protocolo puede admitir. Esta lista es un subconjunto de los tipos de NDIS_MEDIUM . NDIS indica el tipo medio seleccionado en el parámetro SelectedMediumIndex de la estructura en OpenParameters.

Si NdisOpenAdapterEx devuelve un estado de error, ProtocolBindAdapterEx devuelve ese estado de error, libera los recursos por enlace asignados al controlador de protocolo y devuelve el control inmediatamente.

Si NdisOpenAdapterEx devuelve NDIS_STATUS_SUCCESS, ProtocolBindAdapterEx puede asignar los recursos restantes que el controlador de protocolo necesita para llevar a cabo la E/S de red en el enlace. El controlador también puede configurar cualquier información de contexto específica del enlace que use el controlador para realizar un seguimiento de las operaciones de E/S de red.

Si NdisOpenAdapterEx devuelve NDIS_STATUS_PENDING, NDIS llama al controlador del protocolo. Función ProtocolOpenAdapterCompleteEx una vez completada la operación de apertura. ProtocolOpenAdapterCompleteEx puede completar las operaciones de enlace. ProtocolBindAdapterEx puede almacenar el identificador BindContext en el área de contexto de enlace. NDIS pasa ProtocolBindingContext como parámetro de entrada a la función ProtocolOpenAdapterCompleteEx del controlador.

Si NdisOpenAdapterEx devuelve NDIS_STATUS_PENDING, NDIS establece el miembro SelectedMediumIndex de la estructura en el parámetro OpenParameters y el valor del parámetro NdisBindingHandle después de que se devuelva NdisOpenAdapterEx . NDIS establece estos valores antes de llamar a ProtocolOpenAdapterCompleteEx. Por lo tanto, el controlador de protocolo debe almacenar la estructura de parámetros abiertos y el identificador de enlace de protocolo en el área de contexto de ProtocolBindingContext(o cualquier ubicación válida hasta que NDIS llame a ProtocolOpenAdapterCompleteEx).

Un controlador de protocolo no puede realizar solicitudes de OID en un enlace hasta que se complete la operación de apertura. Dado que el enlace está en estado en pausa una vez completada la operación de apertura, el controlador de protocolo no puede realizar solicitudes de envío hasta después de que NDIS reinicie el enlace.

Una vez completada la operación de apertura, ProtocolBindAdapterEx puede devolver NDIS_STATUS_SUCCESS para completar la operación de enlace. ProtocolBindAdapterEx puede devolver NDIS_STATUS_PENDING para aplazar la finalización de las operaciones de enlace en un momento posterior. Si ProtocolBindAdapterEx devuelve NDIS_STATUS_PENDING, el controlador debe llamar al Función NdisCompleteBindAdapterEx una vez completada la operación de enlace.

Los controladores de protocolo deben usar la estructura NDIS_BIND_PARAMETERS para determinar las funcionalidades del adaptador de miniporte subyacente. Una vez completada la operación de apertura, según el medio subyacente, el controlador de protocolo puede llamar a la función NdisOidRequest para consultar al controlador de miniporte subyacente (o NDIS) sobre las funcionalidades adicionales del adaptador de miniport. Para obtener más información sobre las solicitudes de OID, consulte Solicitudes OID del controlador de protocolo.

NDIS puede llamar a un controlador de protocolo Función ProtocolReceiveNetBufferLists después de que el controlador configure un filtro de paquetes para el enlace con . OID_GEN_CURRENT_PACKET_FILTER OID. Si el adaptador de minipuerto subyacente no usa un filtro de paquetes para los paquetes entrantes, las indicaciones de recepción se habilitan una vez completada la operación de apertura. Los controladores de protocolo pueden recibir indicaciones de estado en la función ProtocolStatusEx una vez completada la operación de apertura.

Cada controlador de protocolo debe asignar suficientes NET_BUFFER y grupos de estructura NET_BUFFER_LIST . El controlador asigna descriptores de datos de red de estos grupos para las operaciones de envío posteriores.

Si ProtocolBindAdapterEx no puede asignar los recursos que necesita para llevar a cabo operaciones de E/S de red posteriores, debe liberar todos los recursos que ya ha asignado y devolver un valor de error adecuado.

NDIS llama a un controlador de protocolo Función ProtocolUnbindAdapterEx para solicitar al controlador que desenlace de un adaptador de miniport subyacente.

Si el controlador de protocolo abre correctamente el adaptador de minipuerto, pero se produce un error en la operación de enlace (por ejemplo, como resultado de una solicitud OID con error), el controlador debe cerrar el adaptador de minipuerto desde dentro del contexto de ProtocolBindAdapterEx o ProtocolUnbindAdapterEx. Por ejemplo, el controlador llama a NdisCloseAdapterEx desde ProtocolBindAdapterEx y espera a que se complete la operación de cierre antes de que el controlador vuelva de ProtocolBindAdapterEx. Como alternativa, si el controlador devolvió NDIS_STATUS_PENDING desde ProtocolBindAdapterEx, el controlador puede llamar a la función NdisUnbindAdapter y llamar a NdisCloseAdapterEx en la función ProtocolUnbindAdapterEx .

NDIS llama a ProtocolBindAdapterEx en IRQL = PASSIVE_LEVEL.

Ejemplos

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

PROTOCOL_BIND_ADAPTER_EX MyBindAdapterEx;

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

_Use_decl_annotations_
NDIS_STATUS
 MyBindAdapterEx(
    NDIS_HANDLE  ProtocolDriverContext,
    NDIS_HANDLE  BindContext,
    PNDIS_BIND_PARAMETERS  BindParameters
    )
  {...}

El tipo de función PROTOCOL_BIND_ADAPTER_EX 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_BIND_ADAPTER_EX 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	PASSIVE_LEVEL