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

Se requiere la función ProtocolCmOpenAf . Esta función asigna recursos por apertura para que un administrador de llamadas interactúe con un cliente NDIS orientado a la conexión que abre la familia de direcciones.

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

 

Sintaxis

PROTOCOL_CM_OPEN_AF ProtocolCmOpenAf;

NDIS_STATUS ProtocolCmOpenAf(
  [in]  NDIS_HANDLE CallMgrBindingContext,
  [in]  PCO_ADDRESS_FAMILY AddressFamily,
  [in]  NDIS_HANDLE NdisAfHandle,
  [out] PNDIS_HANDLE CallMgrAfContext
)
{...}

Parámetros

[in] CallMgrBindingContext

Para un administrador de llamadas no integrado, CallMgrBindingContext especifica el identificador de un área de contexto asignada por el administrador de llamadas en la que los administradores de llamadas mantienen su información de estado por enlace. El administrador de llamadas proporcionó este identificador cuando llamó a NdisOpenAdapterEx.

Para un administrador de llamadas integrado (MCM), CallMgrBindingContext especifica el identificador de un área de contexto asignada por miniporte en la que el miniporte mantiene su información de estado por adaptador. El miniporte proporcionó este controlador en su llamada NdisMSetAttributesEx (para controladores 5.x) o su llamada NdisMSetMiniportAttributes (para controladores 6.x).

[in] AddressFamily

Especifica la familia de direcciones que abre un cliente. El administrador de llamadas registró esta familia de direcciones cuando llamó NdisCmRegisterAddressFamilyEx.

[in] NdisAfHandle

Especifica un identificador, proporcionado por NDIS, que identifica de forma única esta instancia de familia de direcciones. Este identificador es opaco para el administrador de llamadas y está reservado para el uso del sistema.

[out] CallMgrAfContext

Especifica el identificador de un área de contexto proporcionada por el administrador de llamadas en la que el administrador de llamadas mantiene el estado sobre esta apertura de una familia de direcciones que proporciona.

Valor devuelto

ProtocolCmOpenAf 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 ha asignado e inicializado correctamente los recursos necesarios para aceptar las solicitudes del cliente a esta familia de direcciones.
NDIS_STATUS_PENDING	Indica que la operación solicitada se controla de forma asincrónica. El administrador de llamadas debe llamar a NdisCmOpenAddressFamilyComplete cuando haya completado todas sus operaciones de af abierta para indicar a NDIS (y al cliente) que se han completado las operaciones.
NDIS_STATUS_RESOURCES	Indica que el administrador de llamadas no pudo completar sus operaciones necesarias debido a la falta de recursos del sistema disponibles, como la memoria.
NDIS_STATUS_XXX	Indica que el administrador de llamadas no se pudo establecer en un estado en el que puede aceptar solicitudes del cliente para operar en esta familia de direcciones. Podría tratarse de un estado de error propagado desde otra función de biblioteca NDIS o cualquier estado de error determinado por el escritor de controladores.

Comentarios

ProtocolCmOpenAf realiza las asignaciones necesarias de recursos dinámicos y estructuras que el escritor del administrador de llamadas considera necesario para realizar operaciones en nombre del cliente que está abriendo una instancia de esta familia de direcciones. Estos recursos incluyen, entre otros, búferes de memoria, estructuras de datos, eventos y otros recursos similares. Un administrador de llamadas también debe inicializar los datos pertinentes por apertura antes de devolver el control a NDIS.

Cuando un administrador de llamadas ha asignado su área de estado por apertura, la dirección del área de estado debe establecerse en el identificador CallMgrAfContext antes de devolver el control a NDIS. Para ello, desreferencia CallMgrAfContext y almacene un puntero al área de datos como valor del identificador. Por ejemplo:

*CallMgrAfContext = SomeBuffer;

Si ProtocolCmOpenAf no puede asignar los recursos por apertura que necesita para llevar a cabo solicitudes posteriores en nombre del cliente que abren esta familia de direcciones, debe liberar todos los recursos asignados para el control abierto y devolver al NDIS con NDIS_STATUS_RESOURCES.

Si ProtocolCmOpenAf ha completado sus operaciones necesarias y cm está listo para aceptar solicitudes del cliente, ProtocolCmOpenAf debe devolver el control lo antes posible con un estado de NDIS_STATUS_SUCCESS.

Ejemplos

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

PROTOCOL_CM_OPEN_AF MyCmOpenAf;

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

_Use_decl_annotations_
NDIS_STATUS
 MyCmOpenAf(
    NDIS_HANDLE  CallMgrBindingContext,
    PCO_ADDRESS_FAMILY  AddressFamily,
    NDIS_HANDLE  NdisAfHandle,
    PNDIS_HANDLE  CallMgrAfContext
    )
  {...}

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

Consulte también

NdisClOpenAddressFamilyEx

NdisCmOpenAddressFamilyComplete NdisCmRegisterAddressFamilyEx

NdisOpenAdapterEx