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

Artículo
08/07/2023

Un cliente NDIS orientado a la conexión que acepte llamadas entrantes debe tener una función ProtocolClRegisterSapComplete para completar las operaciones asincrónicas que inicia con NdisClRegisterSap. De lo contrario, la función ProtocolClRegisterSapComplete registrada de un controlador de protocolo puede simplemente devolver el control.

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

Sintaxis

PROTOCOL_CL_REGISTER_SAP_COMPLETE ProtocolClRegisterSapComplete;

void ProtocolClRegisterSapComplete(
  [in] NDIS_STATUS Status,
  [in] NDIS_HANDLE ProtocolSapContext,
  [in] PCO_SAP Sap,
  [in] NDIS_HANDLE NdisSapHandle
)
{...}

Parámetros

[in] Status

Especifica el estado final de la llamada del cliente a NdisClRegisterSap, que puede ser uno de los siguientes:

NDIS_STATUS_SUCCESS

SAP se ha registrado tanto con NDIS como con el administrador de llamadas, que llamará posteriormente NdisCmDispatchIncomingCall cada vez que recibe una oferta de llamada entrante dirigida al SAP dado, lo que provoca que NDIS llame al cliente. Función ProtocolClIncomingCall .

NDIS_STATUS_RESOURCES

NDIS o el administrador de llamadas no pudieron asignar ni inicializar los recursos necesarios para registrar y mantener SAP.

NDIS_STATUS_INVALID_DATA

El cliente proporcionó una especificación no válida en Sap a NDIS, que reenviaba a la función ProtocolCmRegisterSap del administrador de llamadas para la validación.

NDIS_STATUS_XXX

El administrador de llamadas encontró un error al intentar registrar el sap y el NDIS especificados propagaron este estado de error determinado por CM al cliente.

[in] ProtocolSapContext

Especifica el identificador del área de contexto por SAP del cliente, que el cliente proporcionó originalmente a NDIS cuando llamó a NdisClRegisterSap. Si el registro se realiza correctamente, NDIS conserva este identificador de contexto y lo usa posteriormente en llamadas a la función ProtocolClIncomingCall del cliente relativa a esta SAP.

[in] Sap

Puntero al búfer asignado por el cliente que contiene la especificación para que sap se abra. El cliente pasó originalmente este puntero a NdisClRegisterSap.

[in] NdisSapHandle

Si status es NDIS_STATUS_SUCCESS, especifica un identificador válido proporcionado por NDIS para este SAP registrado, de hecho una asociación establecida con NDIS entre el cliente y un administrador de llamadas determinado para el SAP especificado por el cliente. De lo contrario, este parámetro es NULL. El cliente debe guardar un identificador válido, preferiblemente en su área ProtocolSapContext , para una llamada eventual a NdisClDeregisterSap.

Valor devuelto

None

Observaciones

NDIS llama a ProtocolClRegisterSapComplete para indicar que la llamada anterior del cliente a NdisClRegisterSap ha sido procesada por NDIS y, si NDIS no produjo un error en la llamada, por el administrador de llamadas con la que el cliente comparte el NdisAfHandle que pasó a NdisClRegisterSap.

Para recibir llamadas entrantes a través de una NIC orientada a la conexión, el de un cliente ProtocolCoAfRegisterNotify o La función ProtocolClOpenAfCompleteEx normalmente registra una o varias SAP con el administrador de llamadas.

Para registrar cada SAP, el cliente llama a NdisClRegisterSap, pasando el NdisAfHandle que identifica el administrador de llamadas desde el que el cliente quiere recibir notificaciones de llamadas entrantes y NDIS devuelve al cliente un NdisSapHandle al SAP registrado si la llamada del cliente a NdisClRegisterSap se realiza correctamente. ProtocolClRegisterSapComplete debe guardar cada NdisSapHandle válido, normalmente en el área protocolo por SAPSapContext del cliente para que pueda liberar SAP más adelante con NdisClDeregisterSap.

El formato de sap es específico del administrador de llamadas. Si el administrador de llamadas no reconoce a SAP que el cliente está intentando registrar o si el SAP especificado ya está en uso, el administrador de llamadas puede producir un error en el registro de SAP. ProtocolClRegisterSapComplete debe comprobar el estado de entrada de NDIS_STATUS_SUCCESS antes de continuar. Si se produjo un error en el intento de registrar SAP,
ProtocolClRegisterSapComplete puede liberar el área de contexto por SAP y el búfer en Sap que el cliente asignó o prepararlos para su reutilización en otra llamada a NdisClRegisterSap.

Un cliente puede recibir llamadas entrantes en sap incluso mientras el registro de SAP sigue pendiente, es decir, antes de llamar a su función ProtocolClRegisterSapComplete .

Ejemplos

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

PROTOCOL_CL_REGISTER_SAP_COMPLETE MyClRegisterSapComplete;

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

_Use_decl_annotations_
VOID
 MyClRegisterSapComplete(
    NDIS_STATUS  Status,
    NDIS_HANDLE  ProtocolSapContext,
    PCO_SAP  Sap,
    NDIS_HANDLE  NdisSapHandle
    )
  {...}

El tipo de función PROTOCOL_CL_REGISTER_SAP_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_CL_REGISTER_SAP_COMPLETE del 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	Compatible con los controladores NDIS 6.0 y NDIS 5.1 (consulta ProtocolClRegisterSapComplete (NDIS 5.1)) en Windows Vista. Compatible con los controladores NDIS 5.1 (consulta ProtocolClRegisterSapComplete (NDIS 5.1)) en Windows XP.
Plataforma de destino	Windows
Encabezado	ndis.h (incluya Ndis.h)
IRQL	<= DISPATCH_LEVEL