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

Artículo
08/07/2023

La función ProtocolClOpenAfCompleteEx completa la apertura de una familia de direcciones (AF) que se inició cuando un cliente de CoNDIS llamó a la función NdisClOpenAddressFamilyEx .

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

Sintaxis

PROTOCOL_CL_OPEN_AF_COMPLETE_EX ProtocolClOpenAfCompleteEx;

void ProtocolClOpenAfCompleteEx(
  [in] NDIS_HANDLE ProtocolAfContext,
  [in] NDIS_HANDLE NdisAfHandle,
  [in] NDIS_STATUS Status
)
{...}

Parámetros

[in] ProtocolAfContext

Identificador proporcionado por el cliente a su área de contexto para un AF de dirección. El cliente asignó este área de contexto y pasó este identificador a NDIS en su llamada a . Función NdisClOpenAddressFamilyEx .

[in] NdisAfHandle

Un identificador proporcionado por NDIS a un AF, si Status es NDIS_STATUS_SUCCESS. De lo contrario, este parámetro es NULL. Este identificador representa una asociación que NDIS estableció entre el cliente y un administrador de llamadas enlazado a un adaptador de miniporte de CoNDIS. Si el identificador no es NULL, el cliente debe guardar el identificador para su uso en llamadas posteriores a las funciones NdisClXxx y NdisCoXxx .

[in] Status

El estado final de la llamada del cliente a NdisClOpenAddressFamilyEx, que puede ser cualquiera de los siguientes:

NDIS_STATUS_SUCCESS

Se ha abierto el AF, por lo que el cliente puede inicializar su estado en ProtocolAfContext y usar el identificador devuelto de NdisAfHandle en llamadas posteriores a las funciones NdisClXxx y NdisCoXxx , como NdisCoOidRequest.

NDIS_STATUS_RESOURCES

Error en la operación solicitada porque NDIS o el administrador de llamadas no pudieron asignar memoria suficiente ni inicializar el estado que uno de ellos usa para realizar el seguimiento de la apertura del cliente del AF que especifica ProtocolAfContext .

NDIS_STATUS_FAILURE

NDIS produjo un error en la llamada, posiblemente por uno de los siguientes motivos:

El AF especificado no coincide con ningún AF registrado para el controlador de miniport subyacente al que está enlazado el autor de la llamada.
El enlace del adaptador del autor de la llamada se está cerrando.
El administrador de llamadas que registró el AF especificado está cerrando su enlace al adaptador de miniporte subyacente.

Valor devuelto

None

Observaciones

La función ProtocolClOpenAfCompleteEx es necesaria para los clientes de CoNDIS. Los clientes de CoNDIS deben proporcionar ProtocolClOpenAfCompleteEx para completar las operaciones asincrónicas que inician los clientes mediante una llamada a . Función NdisClOpenAddressFamilyEx .

NDIS llama a ProtocolClOpenAfCompleteEx para indicar que se han producido algunas o todas las siguientes:

Si todos los parámetros del cliente La función ProtocolCoAfRegisterNotify pasada a la función NdisClOpenAddressFamilyEx era válida, NDIS llamó a la función ProtocolCmOpenAf del administrador de llamadas que acaba de registrar el AF especificado con NDIS.
El administrador de llamadas ha examinado la especificación de que la función ProtocolCoAfRegisterNotify del cliente pasó a NdisClOpenAddressFamilyEx en el parámetro AddressFamily y devolvió si era válida para este administrador de llamadas a NDIS.

Si se produce un error en el intento del cliente de abrir un AF, NDIS limpia su estado guardado antes de llamar a ProtocolClOpenAfCompleteEx. En este caso, ProtocolClOpenAfCompleteEx puede liberar los recursos que el cliente asignó para su llamada a NdisClOpenAddressFamilyEx o prepararlos para su reutilización.

De lo contrario, ProtocolClOpenAfCompleteEx debe configurar el estado determinado por el cliente que necesite el cliente para las operaciones posteriores en el AF recién abierto. En concreto, el cliente debe guardar el identificador del parámetro NdisAfHandle , normalmente en el área de contexto ProtocolAfContext del cliente.

Si el cliente acepta llamadas entrantes, puede asignar un área de estado de punto de acceso por servicio (SAP) y llamar a la función NdisClRegisterSap . Si el cliente realiza llamadas salientes, puede asignar un área de estado de conexión por virtual (VC) y crear una credencial verificable con la función NdisCoCreateVc para preparar una solicitud entrante de uno de los propios clientes del cliente para realizar una llamada saliente a un nodo remoto.

NDIS llama a ProtocolClOpenAfCompleteEx en IRQL = PASSIVE_LEVEL.

Ejemplos

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

PROTOCOL_CL_OPEN_AF_COMPLETE_EX MyClOpenAfCompleteEx;

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

_Use_decl_annotations_
VOID
 MyClOpenAfCompleteEx(
    NDIS_HANDLE  ProtocolAfContext,
    NDIS_HANDLE  NdisAfHandle,
    NDIS_STATUS  Status
    )
  {...}

El tipo de función PROTOCOL_CL_OPEN_AF_COMPLETE_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_CL_OPEN_AF_COMPLETE_EX 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	PASSIVE_LEVEL