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

2023-08-07

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

Nota Debe declarar la función mediante el tipo de 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 NDIS para esta operación de enlace.

[in] BindParameters

Puntero a una estructura 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 completado correctamente el enlace al adaptador de miniport 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 al función NdisCompleteBindAdapterEx cuando se completa la operación.
NDIS_STATUS_RESOURCES	ProtocolBindAdapterEx no pudo asignar los recursos que requiere el controlador para realizar 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 de Ndisfunción xxx o una rutina de compatibilidad en modo kernel.

Observaciones

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

ProtocolBindAdapterEx asigna suficiente memoria para mantener la información del contexto de enlace y llama a la función NdisOpenAdapterEx para enlazarse a sí misma al 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 BindParameters como el miembro AdapterNamedel 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 el adaptador de miniporte correctamente, el controlador puede pasar el identificador de parámetro NdisHandle de NdisOpenAdapterEx a NdisOpenConfigurationEx para obtener un identificador en 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 puede admitir el controlador de protocolo. 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 por 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 de protocolo. función ProtocolOpenAdapterCompleteEx una vez completada la operación de apertura. ProtocolOpenAdapterCompleteEx puede completar las operaciones de enlace. ProtocolBindAdapterEx puede almacenar el identificador de 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 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 en ProtocolBindingContext(o cualquier ubicación válida hasta que NDIS llame a ProtocolOpenAdapterCompleteEx).

Un controlador de protocolo no puede realizar solicitudes 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 de NDIS_BIND_PARAMETERS para determinar las funcionalidades del adaptador de miniport subyacente. Una vez completada la operación de apertura, en función del medio subyacente, el controlador de protocolo puede llamar a la función NdisOidRequest para consultar el controlador de miniport 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, se habilitan las indicaciones de recepción una vez completada la operación de apertura. Los controladores de protocolo pueden recibir indicaciones de estado en 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 posteriores de E/S de red, 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 desde un adaptador de miniport subyacente.

Si el controlador de protocolo abre correctamente el adaptador de miniport, 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 miniport 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 de ProtocolBindAdapterEx, el controlador puede llamar a la función NdisUnbindAdapter y llamar a NdisCloseAdapterEx en la función ProtocolUnbindAdapterEx de.

NDIS llama a ProtocolBindAdapterEx en IRQL = PASSIVE_LEVEL.

Ejemplos de

Para definir una función ProtocolBindAdapterEx, 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 análisis de código para controladores, comprobador de controladores estáticos (SDV) y otras herramientas de comprobación encuentran 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 PROTOCOL_BIND_ADAPTER_EX tal 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, vea 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, vea Anotación del comportamiento de la función.

Requisitos

Requisito	Valor
cliente mínimo admitido	Se admite en NDIS 6.0 y versiones posteriores.
de la plataforma de destino de	Windows
encabezado de	ndis.h (incluya Ndis.h)
irQL	PASSIVE_LEVEL