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

Artículo
08/07/2023

La función ProtocolClMakeCallComplete la usan los clientes NDIS orientados a la conexión que realizan llamadas salientes. Estos clientes deben tener funciones ProtocolClMakeCallComplete para completar las operaciones asincrónicas que inician con NdisClMakeCall. De lo contrario, la función ProtocolClMakeCallComplete registrada de un controlador de protocolo puede simplemente devolver el control.

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

Sintaxis

PROTOCOL_CL_MAKE_CALL_COMPLETE ProtocolClMakeCallComplete;

void ProtocolClMakeCallComplete(
  [in]           NDIS_STATUS Status,
  [in]           NDIS_HANDLE ProtocolVcContext,
  [in, optional] NDIS_HANDLE NdisPartyHandle,
  [in]           PCO_CALL_PARAMETERS CallParameters
)
{...}

Parámetros

[in] Status

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

NDIS_STATUS_SUCCESS

El intento del cliente de configurar una conexión virtual se realizó correctamente. Por lo tanto, el cliente puede continuar realizando transferencias en el vc activo mediante NdisVcHandle devuelto por NdisCoCreateVc, que el cliente ha almacenado en su área de contexto por VC en ProtocolVcContext .

NDIS_STATUS_RESOURCES

NDIS, el administrador de llamadas o un controlador subyacente no pudieron asignar recursos suficientes para configurar la conexión.

NDIS_STATUS_XXX

El administrador de llamadas o el controlador de miniport subyacente no pudieron establecer una conexión activa y NDIS propagó este estado de error determinado por el controlador al cliente.

[in] ProtocolVcContext

Especifica el identificador del área de contexto por VC del cliente, que el cliente proporcionó originalmente a NDIS cuando llamó a NdisCoCreateVc para configurar la credencial verificable para su llamada saliente.

[in, optional] NdisPartyHandle

Si Status es NDIS_STATUS_SUCCESS y el cliente creó un VC de varios puntos pasando un identificador ProtocolPartyContext explícito a NdisClMakeCall, se trata de un NdisPartyHandle válido. De lo contrario, este parámetro es NULL.

ProtocolClMakeCallComplete debe guardar cualquier entrada válida NdisPartyHandle, normalmente en el área de contexto por entidad del cliente. El cliente debe usar este identificador si (o cuándo) realiza una llamada posterior a NdisClDropParty o NdisClCloseCall que hace referencia a esta entidad.

[in] CallParameters

Puntero a una estructura de CO_CALL_PARAMETERS almacenada en búfer. El cliente asignó este búfer e inicializó esta estructura con datos determinados por el cliente antes de pasar este puntero a NdisClMakeCall. Al procesar la solicitud del cliente, el administrador de llamadas puede modificar estos datos para reflejar los resultados de su negociación con la red o con un par de señalización.

Valor devuelto

None

Observaciones

Una llamada a ProtocolClMakeCallComplete indica que el administrador de llamadas ha completado el procesamiento de la solicitud del cliente para establecer una conexión virtual con NdisClMakeCall.

Si el intento del cliente de establecer una llamada saliente no es correcta ( el estado de entrada es cualquier cosa excepto NDIS_STATUS_SUCCESS), ProtocolClMakeCallComplete debe hacer lo siguiente:

Libere o prepare para reutilizar el área ProtocolPartyContext , si existe, y el búfer en CallParameters que el cliente asignó.
Anula el VC creado por el cliente con una llamada a NdisCoDeleteVc y libera o prepara la reutilización del área ProtocolVcContext asignada por el cliente.

De lo contrario, ProtocolClMakeCallComplete debe hacer lo siguiente:

Compruebe el miembro Flags de la estructura en CallParameters para ver si se ha establecido CALL_PARAMETERS_CHANGED, lo que indica que el administrador de llamadas modificó los parámetros de llamada proporcionados por el cliente.
Si es así, examine los datos de CallParameters para determinar si son aceptables para esta conexión.
Por ejemplo, el cliente puede conservar los parámetros de llamada almacenados en búfer para la credencial verificable activa, guardar NdisPartyHandle si se trata de una credencial verificable de varios puntos y, por lo general, hacer que el cliente esté listo para transferencias posteriores y otras operaciones en la credencial verificable activa si encuentra satisfactorios los parámetros de llamada especificados.
Si no es así, el protocolo de señalización determina si el cliente puede intentar renegociar los parámetros de llamada aceptables con el administrador de llamadas.
Por ejemplo, un administrador de llamadas determinado podría permitir que sus clientes llamen a NdisClModifyCallQoS una o varias veces en estas circunstancias.
Si los parámetros de llamada modificados por CM son inaceptables y es imposible una renegociación adicional, ProtocolClMakeCallComplete debe anular la llamada con NdisClCloseCall.
En este caso, ProtocolClMakeCallCompleteno debe intentar liberar ningún recurso asignado por el cliente a cambio de NdisClCloseCall , pero simplemente puede devolver el control. En su lugar, el cliente debe liberar los recursos asignados (o prepararlos para su reutilización) dentro de su función ProtocolClCloseCallComplete .

Ejemplos

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

PROTOCOL_CL_MAKE_CALL_COMPLETE MyClMakeCallComplete;

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

_Use_decl_annotations_
VOID
 MyClMakeCallComplete(
    NDIS_STATUS  Status,
    NDIS_HANDLE  ProtocolVcContext,
    NDIS_HANDLE  NdisPartyHandle,
    PCO_CALL_PARAMETERS  CallParameters
    )
  {...}

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