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

Artículo
08/07/2023

La función ProtocolCmRegisterSap es una función necesaria a la que llama NDIS para solicitar que un administrador de llamadas registre un SAP (punto de acceso de servicio) en nombre de un cliente orientado a la conexión.

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

Sintaxis

PROTOCOL_CM_REG_SAP ProtocolCmRegSap;

NDIS_STATUS ProtocolCmRegSap(
  [in]  NDIS_HANDLE CallMgrAfContext,
  [in]  PCO_SAP Sap,
  [in]  NDIS_HANDLE NdisSapHandle,
  [out] PNDIS_HANDLE CallMgrSapContext
)
{...}

Parámetros

[in] CallMgrAfContext

Especifica el identificador de un área de contexto asignada por el administrador de llamadas en la que el administrador de llamadas mantiene su estado af por apertura. El administrador de llamadas proporcionó este identificador a NDIS desde su función ProtocolCmOpenAf .

[in] Sap

Puntero a una estructura de CO_SAP específica del medio que contiene el SAP específico que registra un cliente orientado a la conexión.

[in] NdisSapHandle

Especifica un identificador, proporcionado por NDIS, que identifica de forma única este SAP. Este identificador es opaco para el administrador de llamadas y está reservado para el uso de la biblioteca NDIS.

[out] CallMgrSapContext

Al devolver, 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 este SAP.

Valor devuelto

ProtocolCmRegisterSap 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 asignó correctamente o inicializó los recursos necesarios para registrar y mantener SAP. Además, también indica que SAP se registró correctamente según lo requiera el medio de red que admite el administrador de llamadas.
NDIS_STATUS_PENDING	Indica que el administrador de llamadas completará el procesamiento de esta solicitud de forma asincrónica. Los administradores de llamadas deben llamar NdisCmRegisterSapComplete cuando se ha completado todo el procesamiento para indicar a NDIS que el registro ha finalizado.
NDIS_STATUS_RESOURCES	Indica que el administrador de llamadas no pudo asignar o inicializar sus recursos necesarios para registrar SAP en nombre del cliente orientado a la conexión.
NDIS_STATUS_INVALID_DATA	Indica que la especificación proporcionada en Sap no es válida o no se puede admitir.
NDIS_STATUS_XXX	Indica que el administrador de llamadas encontró un error al intentar registrar SAP para el cliente orientado a la conexión. El código de retorno es adecuado para el error y podría ser un código de retorno propagado desde otra función de biblioteca NDIS.

Comentarios

ProtocolCmMakeCall se comunica con dispositivos de control de red u otros agentes específicos de medios, según sea necesario, para registrar sap, tal como se especifica en Sap, en la red para un cliente orientado a la conexión. Estas acciones pueden incluir, pero no se limitan a la comunicación con hardware de conmutación, la comunicación con una estación de control de red u otras acciones adecuadas para el medio de red.

Si se requiere un administrador de llamadas para comunicarse con agentes de control de red (es decir, un conmutador de red), debe usar una conexión virtual al agente de control de red que estableció en su función ProtocolBindAdapterEx . Los administradores de llamadas independientes se comunican a través del controlador de miniport subyacente llamando a NdisCoSendNetBufferLists. Los controladores miniport con compatibilidad integrada con la administración de llamadas nunca llaman a NdisCoSendNetBufferLists. En su lugar, transmiten los datos directamente a través de la red.

Además, ProtocolCmRegisterSap debe realizar las asignaciones necesarias de recursos dinámicos y estructuras que el administrador de llamadas necesita para mantener información de estado sobre SAP en nombre del cliente orientado a la conexión. Estos recursos incluyen, entre otros, los búferes de memoria, las estructuras de datos, los eventos y otros recursos similares. Un administrador de llamadas también debe inicializar los recursos que asigne antes de devolver el control a NDIS. Los administradores de llamadas deben almacenar el identificador proporcionado por NDIS que identifica sap, proporcionado en NdisSapHandle, en su área de contexto para su uso futuro.

Si ProtocolCmRegisterSap devolverá NDIS_STATUS_SUCCESS, debe, después de asignar el área de estado por SAP, establecer la dirección de este área de estado en CallMgrSapContext antes de devolver el control a NDIS. Para ello, desreferencia CallMgrSapContext y almacene un puntero al área de datos como valor del identificador. Por ejemplo:

*CallMgrSapContext = SomeBuffer ;

Si el SAP dado que ya está registrado por otro cliente orientado a la conexión, el administrador de llamadas debe producir un error en la solicitud y devolver NDIS_STATUS_INVALID_DATA.

Después de que un administrador de llamadas haya registrado un SAP en nombre de un cliente orientado a la conexión, notifica a ese cliente de una oferta de llamada entrante dirigida a ese SAP mediante una llamada a . NdisCmDispatchIncomingCall.

Ejemplos

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

PROTOCOL_CM_REG_SAP MyCmRegisterSap;

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

_Use_decl_annotations_
NDIS_STATUS
 MyCmRegisterSap(
    NDIS_HANDLE  CallMgrAfContext,
    PCO_SAP  Sap,
    NDIS_HANDLE  NdisSapHandle,
    PNDIS_HANDLE  CallMgrSapContext
    )
  {...}

El tipo de función PROTOCOL_CM_REG_SAP 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_REG_SAP en el archivo de encabezado. Para obtener más información sobre los requisitos de las declaraciones de función, vea Declarar funciones mediante 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 controladores NDIS 6.0 y NDIS 5.1 (consulte ProtocolCmRegisterSap (NDIS 5.1)) en Windows Vista. Compatible con controladores NDIS 5.1 (consulte ProtocolCmRegisterSap (NDIS 5.1)) en Windows XP.
Plataforma de destino	Windows
Encabezado	ndis.h (incluya Ndis.h)
IRQL	<= DISPATCH_LEVEL