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

Artículo
08/07/2023

La función ProtocolCoCreateVc es una función necesaria que asigna los recursos necesarios para que un administrador de llamadas o un cliente activen y mantengan una conexión virtual (VC).

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

Sintaxis

PROTOCOL_CO_CREATE_VC ProtocolCoCreateVc;

NDIS_STATUS ProtocolCoCreateVc(
  [in]  NDIS_HANDLE ProtocolAfContext,
  [in]  NDIS_HANDLE NdisVcHandle,
  [out] PNDIS_HANDLE ProtocolVcContext
)
{...}

Parámetros

[in] ProtocolAfContext

Especifica el identificador de un área de contexto asignada por protocolo en la que el administrador de llamadas o el cliente mantiene su estado por apertura. El administrador de llamadas proporcionó este identificador desde su función ProtocolCmOpenAf . El cliente proporcionó este identificador cuando llamó a NdisClOpenAddressFamilyEx desde su función ProtocolCoAfRegisterNotify .

[in] NdisVcHandle

Especifica un identificador, proporcionado por NDIS, que identifica de forma única esta conexión virtual. Este identificador es opaco para el controlador de protocolo y está reservado para el uso de la biblioteca NDIS. Sin embargo, el administrador de llamadas y el cliente deben guardar este identificador para pasar llamadas posteriores a las funciones NdisCo/Cl/Cm/MCmXxx que se refieren a esta credencial verificable.

[out] ProtocolVcContext

Especifica el identificador de un área de contexto proporcionada por el protocolo en la que el administrador de llamadas o el cliente mantiene el estado sobre esta conexión virtual.

Valor devuelto

ProtocolCoCreateVc devuelve el estado de sus operaciones como uno de los valores siguientes:

Código devuelto	Descripción
NDIS_STATUS_SUCCESS	Indica que el administrador de llamadas o el cliente asignaron correctamente o inicializaron los recursos necesarios para establecer y mantener una conexión virtual.
NDIS_STATUS_RESOURCES	Indica que el administrador de llamadas o el cliente no pudieron asignar o inicializar sus recursos para establecer y mantener una conexión virtual.
NDIS_STATUS_XXX	Indica que el administrador de llamadas o el cliente no se pudieron establecer en un estado en el que podría establecer una conexión virtual. Esto puede ser un valor devuelto de error propagado desde otra rutina de biblioteca NDIS. Nota Los administradores de llamadas o los clientes no pueden devolver NDIS_STATUS_PENDING de sus funciones ProtocolCoCreateVc . Si se devuelve pendiente, esta conexión virtual no se puede usar y la biblioteca NDIS llamará al cliente o al administrador de llamadas para eliminarla.

Comentarios

Se llama a la función ProtocolCoCreateVc de un administrador de llamadas o cliente cada vez que el cliente o el administrador de llamadas correspondientes, respectivamente, llama a NdisCoCreateVc. Los clientes inician la creación de máquinas virtuales en el proceso de configuración de sus llamadas salientes antes de llamar a NdisClMakeCall. Un administrador de llamadas inicia la creación de una credencial verificable en el proceso de notificar a su cliente que el CM recibió una oferta de llamada entrante de un nodo remoto que se dirige a un SAP ya registrado con el CM por ese cliente antes de que el CM llame a . NdisCmDispatchIncomingCall.

ProtocolCoCreateVc realiza las asignaciones necesarias de recursos dinámicos y estructuras que el administrador de llamadas o el cliente requieren para realizar operaciones posteriores en una credencial verificable que se activará. Estos recursos incluyen, entre otros, búferes de memoria, estructuras de datos, eventos y otros recursos similares. Los administradores de llamadas y los clientes también deben inicializar las estructuras por vc pertinentes que necesitarán cuando se establezca una llamada.

Los controladores de protocolo orientados a la conexión deben almacenar el identificador de la credencial verificable, especificada en NdisVcHandle, en su área de estado por VC que se usará en futuras operaciones en esta conexión virtual. NdisVcHandle es el parámetro necesario para el NdisCoXxx, NdisCmXxx y/o NdisClXxx que este protocolo orientado a la conexión llama posteriormente.

Cuando un administrador de llamadas o un cliente ha asignado memoria para sus propios datos por vc e inicializó su estado, la dirección de esta estructura de datos debe establecerse en el identificador antes de devolver el control a NDIS. Para ello, desreferencia el identificador y almacena un puntero al área de datos asignada por protocolo como valor del identificador. Por ejemplo:

*ProtocolVcContext = SomeBuffer;

Si ProtocolCoCreateVc no puede asignar el recurso que necesita para llevar a cabo operaciones de E/S de red posteriores, debe liberar todos los recursos que se asignaron para esta credencial verificable y devolver el control con un estado de NDIS_STATUS_RESOURCES.

Si ProtocolCoCreateVc ha completado sus operaciones necesarias y ha hecho que el administrador de llamadas o el cliente estén listos para llevar a cabo la inicialización de llamadas para esta conexión virtual, ProtocolCoCreateVc debe devolver el control lo antes posible con un estado de NDIS_STATUS_SUCCESS.

Las llamadas a ProtocolCoCreateVc son intrínsecamente sincrónicas por naturaleza. Es decir, ProtocolCoCreateVcno puede devolver NDIS_STATUS_PENDING.

Después de que la función ProtocolCoCreateVc del administrador de llamadas devuelva el control, se llamará a la función ProtocolCmMakeCall del administrador de llamadas para establecer una conexión a un nodo remoto. Los administradores de llamadas no deben realizar ninguna acción en ProtocolCmMakeCall que establezca realmente una llamada porque es posible que se destruya la credencial verificable antes de que se establezca una llamada debido a una condición de error en otro componente del NDIS orientado a la conexión.

Después de que la función ProtocolCoCreateVc de un cliente devuelva el control, se notificará a la función ProtocolClIncomingCall del cliente cuando se conecte una solicitud iniciada remotamente para conectarse a un SAP registrado previamente por el cliente a través de la red.

Ejemplos

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

PROTOCOL_CO_CREATE_VC MyCoCreateVc;

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

_Use_decl_annotations_
NDIS_STATUS
 MyCoCreateVc(
    NDIS_HANDLE  ProtocolAfContext,
    NDIS_HANDLE  NdisVcHandle,
    PNDIS_HANDLE  ProtocolVcContext
    )
  {...}

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