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

Artículo
02/26/2024

La función ProtocolCmCloseCall es una función necesaria que finaliza una llamada existente y libera los recursos asignados por el administrador de llamadas para la llamada.

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

Sintaxis

PROTOCOL_CM_CLOSE_CALL ProtocolCmCloseCall;

NDIS_STATUS ProtocolCmCloseCall(
  [in]           NDIS_HANDLE CallMgrVcContext,
  [in, optional] NDIS_HANDLE CallMgrPartyContext,
  [in, optional] PVOID CloseData,
  [in, optional] UINT Size
)
{...}

Parámetros

[in] CallMgrVcContext

Especifica el identificador de un área de contexto asignada por el administrador de llamadas en la que el administrador de llamadas mantiene su estado por VC. Este identificador se proporcionó a NDIS desde la función ProtocolCmMakeCall de administradores de llamadas.

[in, optional] CallMgrPartyContext

Especifica el identificador, si existe, en un área de contexto asignada por el administrador de llamadas en la que el administrador de llamadas mantiene información sobre una entidad en una credencial verificable de varios puntos. Este identificador es NULL si la llamada que se cierra no es una llamada multipunto.

[in, optional] CloseData

Puntero a un búfer que contiene datos especificados por el cliente orientado a la conexión que se deben enviar a través de la conexión antes de que finalice la llamada. Este parámetro es NULL si el medio de red subyacente no admite transferencias de datos al cerrar una conexión.

[in, optional] Size

Especifica la longitud, en bytes, del búfer en CloseData, cero si CloseData es NULL.

Valor devuelto

ProtocolCmCloseCall devuelve el estado de sus operaciones como una de las siguientes:

Código devuelto	Descripción
NDIS_STATUS_SUCCESS	Indica que el administrador de llamadas finalizó correctamente la llamada.
NDIS_STATUS_PENDING	Indica que el administrador de llamadas completará la solicitud para finalizar la llamada de forma asincrónica. Cuando el administrador de llamadas haya completado todas las operaciones necesarias para finalizar la conexión, debe llamar a NdisCmCloseCallComplete para indicar a NDIS que se ha cerrado la llamada.
NDIS_STATUS_INVALID_DATA	Indica que se especificó CloseData , pero el medio de red subyacente no admite el envío de datos simultáneos con la finalización de una llamada.
NDIS_STATUS_XXX	Indica que el administrador de llamadas no pudo finalizar la llamada. El error real devuelto puede ser un estado propagado desde otra rutina de biblioteca NDIS.

Comentarios

ProtocolCmCloseCall se comunica con dispositivos de control de red u otros actores específicos de medios, según lo necesario por su medio, para finalizar una conexión entre el nodo local y un nodo remoto. Si el administrador de llamadas es necesario para comunicarse con dispositivos de control de red (como un conmutador de red), debe usar una conexión virtual al dispositivo de control de red que estableció en su función ProtocolBindAdapterEx . Los administradores de llamadas independientes se comunican con estos dispositivos de red mediante una llamada a NdisCoSendNetBufferLists. Los controladores de minipuerto con soporte integrado de administración de llamadas nunca llaman a NdisCoSendNetBufferLists. En su lugar, transmiten los datos directamente a través de la red.

Si CloseData no es NULL y el medio que controla este administrador de llamadas admite el envío de datos a la finalización de la conexión, el administrador de llamadas debe transmitir los datos especificados en CloseData al nodo remoto antes de completar la finalización de la llamada. Si no se admite el envío de datos simultáneos con una conexión terminada, los administradores de llamadas deben devolver NDIS_STATUS_INVALID_DATA.

Si ProtocolCmCloseCall se pasa a callMgrPartyContext explícito, la llamada que se finaliza es un VC de varios puntos y el administrador de llamadas debe realizar cualquier comunicación de red necesaria con su hardware de red, según corresponda a su tipo de medio, para finalizar la llamada como una llamada multipunto. El administrador de llamadas también debe liberar la memoria que asignó anteriormente, en ProtocolCmMakeCall, para su estado por parte al que apunta CallMgrPartyContext . Si no se liberan, desasignan correctamente o desactivan esos recursos, se produce una pérdida de memoria.

Una vez finalizada la llamada con la red, se han enviado todos los datos de cierre y se han liberado todos los recursos de CallMgrPartyContext , el administrador de llamadas debe llamar a NdisCmDeactivateVc. Esto notifica a NDIS y al controlador de miniporte subyacente, si existe, que no espere ninguna transferencia adicional en la credencial verificable especificada.

Ejemplos

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

PROTOCOL_CM_CLOSE_CALL MyCmCloseCall;

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

_Use_decl_annotations_
NDIS_STATUS
 MyCmCloseCall(
    NDIS_HANDLE  CallMgrVcContext,
    NDIS_HANDLE  CallMgrPartyContext,
    PVOID  CloseData,
    UINT  Size
    )
  {...}

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