PROTOCOL_CM_REG_SAP fonction de rappel (ndis.h)

Article
02/26/2024

La fonction ProtocolCmRegisterSap est une fonction obligatoire appelée par NDIS pour demander à un gestionnaire d’appels d’inscrire un sap (point d’accès de service) pour le compte d’un client orienté connexion.

Note Vous devez déclarer la fonction à l’aide du type PROTOCOL_CM_REG_SAP . Pour plus d’informations, consultez la section Exemples suivante.

Syntaxe

PROTOCOL_CM_REG_SAP ProtocolCmRegSap;

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

Paramètres

[in] CallMgrAfContext

Spécifie le handle d’une zone de contexte allouée par le gestionnaire d’appels dans laquelle le gestionnaire d’appels conserve son état AF par ouverture. Le gestionnaire d’appels a fourni ce handle à NDIS à partir de sa fonction ProtocolCmOpenAf .

[in] Sap

Pointeur vers une structure de CO_SAP spécifique au média qui contient le SAP spécifique inscrit par un client orienté connexion.

[in] NdisSapHandle

Spécifie un handle, fourni par NDIS, qui identifie de manière unique ce SAP. Ce handle est opaque pour le gestionnaire d’appels et réservé à l’utilisation de la bibliothèque NDIS.

[out] CallMgrSapContext

Au retour, spécifie le handle d’une zone de contexte fournie par le gestionnaire d’appels dans laquelle le gestionnaire d’appels conserve l’état de ce SAP.

Valeur retournée

ProtocolCmRegisterSap retourne le status de ses opérations comme suit :

Code de retour	Description
NDIS_STATUS_SUCCESS	Indique que le gestionnaire d’appels a correctement alloué et/ou initialisé les ressources nécessaires pour inscrire et gérer sap. En outre, il indique également que le SAP a été correctement inscrit comme requis par le média réseau pris en charge par le gestionnaire d’appels.
NDIS_STATUS_PENDING	Indique que le gestionnaire d’appels terminera le traitement de cette requête de manière asynchrone. Les gestionnaires d’appels doivent appeler NdisCmRegisterSapComplete lorsque tout le traitement a été terminé pour signaler à NDIS que l’inscription est terminée.
NDIS_STATUS_RESOURCES	Indique que le gestionnaire d’appels n’a pas pu allouer et/ou initialiser ses ressources nécessaires à l’inscription du sap pour le compte du client orienté connexion.
NDIS_STATUS_INVALID_DATA	Indique que la spécification fournie dans Sap n’est pas valide ou ne peut pas être prise en charge.
NDIS_STATUS_XXX	Indique que le gestionnaire d’appels a rencontré une erreur lors de la tentative d’inscription du sap pour le client orienté connexion. Le code de retour convient à l’erreur et peut être un code de retour propagé à partir d’une autre fonction de bibliothèque NDIS.

Remarques

ProtocolCmMakeCall communique avec les périphériques de contrôle réseau ou d’autres agents spécifiques aux médias, si nécessaire, pour inscrire le SAP, comme spécifié dans Sap, sur le réseau pour un client orienté connexion. Ces actions peuvent inclure, sans s’y limiter, la communication avec du matériel de commutation, la communication avec une station de contrôle réseau ou d’autres actions appropriées au support réseau.

Si un gestionnaire d’appels est requis pour communiquer avec les agents de contrôle réseau (en d’autres termes, un commutateur réseau), il doit utiliser une connexion virtuelle à l’agent de contrôle réseau qu’il a établi dans sa fonction ProtocolBindAdapterEx . Les gestionnaires d’appels autonomes communiquent via le pilote miniport sous-jacent en appelant NdisCoSendNetBufferLists. Les pilotes Miniport avec prise en charge intégrée de la gestion des appels n’appellent jamais NdisCoSendNetBufferLists. Au lieu de cela, ils transmettent les données directement sur le réseau.

En outre, ProtocolCmRegisterSap doit effectuer toutes les allocations nécessaires de ressources et de structures dynamiques dont le gestionnaire d’appels a besoin pour conserver les informations d’état sur le SAP pour le compte du client orienté connexion. Ces ressources incluent, sans s’y limiter, les mémoires tampons, les structures de données, les événements et d’autres ressources similaires. Un gestionnaire d’appels doit également initialiser toutes les ressources qu’il alloue avant de retourner le contrôle à NDIS. Les responsables d’appels doivent stocker le handle fourni par NDIS identifiant le SAP, fourni dans NdisSapHandle, dans leur zone de contexte pour une utilisation ultérieure.

Si ProtocolCmRegisterSap retourne NDIS_STATUS_SUCCESS, il doit, après avoir alloué la zone d’état par SAP, définir l’adresse de cette zone d’état dans CallMgrSapContext avant de renvoyer le contrôle à NDIS. Pour ce faire, déréférencez CallMgrSapContext et stockez un pointeur vers la zone de données comme valeur du handle. Par exemple :

*CallMgrSapContext = SomeBuffer ;

Si le SAP donné est déjà inscrit par un autre client orienté connexion, le gestionnaire d’appels doit faire échouer la demande et retourner NDIS_STATUS_INVALID_DATA.

Une fois qu’un gestionnaire d’appels a inscrit un SAP pour le compte d’un client orienté connexion, il informe ce client d’une offre d’appel entrante dirigée vers ce SAP en appelant NdisCmDispatchIncomingCall.

Exemples

Pour définir une fonction ProtocolCmRegisterSap , vous devez d’abord fournir une déclaration de fonction qui identifie le type de fonction que vous définissez. Windows fournit un ensemble de types de fonctions pour les pilotes. La déclaration d’une fonction à l’aide des types de fonction permet à l’analyse du code pour les pilotes, au vérificateur de pilotes statiques (SDV) et à d’autres outils de vérification de trouver des erreurs. Il s’agit d’une exigence pour l’écriture de pilotes pour le système d’exploitation Windows.

Par exemple, pour définir une fonction ProtocolCmRegisterSap nommée « MyCmRegisterSap », utilisez le type PROTOCOL_CM_REG_SAP comme indiqué dans cet exemple de code :

PROTOCOL_CM_REG_SAP MyCmRegisterSap;

Ensuite, implémentez votre fonction comme suit :

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

Le type de fonction PROTOCOL_CM_REG_SAP est défini dans le fichier d’en-tête Ndis.h. Pour identifier plus précisément les erreurs lors de l’exécution des outils d’analyse du code, veillez à ajouter l’annotation Use_decl_annotations à votre définition de fonction. L’annotation Use_decl_annotations garantit que les annotations appliquées au type de fonction PROTOCOL_CM_REG_SAP dans le fichier d’en-tête sont utilisées. Pour plus d’informations sur la configuration requise pour les déclarations de fonction, consultez Déclaration de fonctions à l’aide de types de rôles de fonction pour les pilotes NDIS.

Pour plus d’informations sur Use_decl_annotations, consultez Annotating Function Behavior.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Pris en charge pour les pilotes NDIS 6.0 et NDIS 5.1 (voir ProtocolCmRegisterSap (NDIS 5.1)) dans Windows Vista. Pris en charge pour les pilotes NDIS 5.1 (voir ProtocolCmRegisterSap (NDIS 5.1)) dans Windows XP.
Plateforme cible	Windows
En-tête	ndis.h (inclure Ndis.h)
IRQL	<= DISPATCH_LEVEL