PROTOCOL_CM_MAKE_CALL fonction de rappel (ndis.h)

Article
03/05/2024

La fonction ProtocolCmMakeCall est une fonction obligatoire qui configure des paramètres spécifiques aux médias pour une connexion virtuelle (VC) et active la connexion virtuelle.

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

Syntaxe

PROTOCOL_CM_MAKE_CALL ProtocolCmMakeCall;

NDIS_STATUS ProtocolCmMakeCall(
  [in]            NDIS_HANDLE CallMgrVcContext,
  [in, out]       PCO_CALL_PARAMETERS CallParameters,
  [in, optional]  NDIS_HANDLE NdisPartyHandle,
  [out, optional] PNDIS_HANDLE CallMgrPartyContext
)
{...}

Paramètres

[in] CallMgrVcContext

Spécifie le handle d’une zone de contexte allouée par le gestionnaire d’appels dans laquelle les gestionnaires d’appels conservent leur état par vc. Le gestionnaire d’appels a fourni ce handle à NDIS à partir de sa fonction ProtocolCoCreateVc .

[in, out] CallParameters

Pointeur vers une structure CO_CALL_PARAMETERS qui contient les paramètres, spécifiés par un client orienté connexion, pour cet appel sortant.

[in, optional] NdisPartyHandle

Spécifie un handle, fourni par NDIS, qui identifie de manière unique la partie initiale sur la connexion virtuelle multipoint. Ce handle est opaque pour le gestionnaire d’appels et réservé à l’utilisation de la bibliothèque NDIS. Ce handle a la valeur NULL si le client ne configure pas d’appel multipoint sortant.

[out, optional] CallMgrPartyContext

Au retour, spécifie un handle à une zone de contexte fournie par le gestionnaire d’appels dans laquelle le gestionnaire d’appels conserve l’état de la partie initiale sur l’appel multipoint. Si NdisPartyHandle a la valeur NULL, ce handle doit être défini sur NULL.

Valeur retournée

ProtocolCmMakeCall retourne la status de ses opérations sous la forme d’une des valeurs suivantes :

Code de retour	Description
NDIS_STATUS_SUCCESS	Indique que le gestionnaire d’appels a correctement alloué les ressources nécessaires pour effectuer l’appel et a pu activer la connexion virtuelle avec le pilote miniport.
NDIS_STATUS_PENDING	Indique que le gestionnaire d’appels termine la demande d’appel de manière asynchrone. Lorsque le gestionnaire d’appels a terminé toutes les opérations d’appel, il doit appeler NdisCmMakeCallComplete pour signaler à NDIS que cet appel a été terminé.
NDIS_STATUS_RESOURCES	Indique que le gestionnaire d’appels n’a pas pu allouer et/ou initialiser ses ressources pour activer la connexion virtuelle comme demandé par le client.
NDIS_STATUS_NOT_SUPPORTED	Indique que le gestionnaire d’appels n’a pas pu activer une connexion virtuelle, car l’appelant a demandé des fonctionnalités non valides ou non disponibles dans les paramètres d’appel spécifiés dans CallParameters .

Remarques

Si ProtocolCmMakeCall reçoit un NdisPartyHandle explicite, ce vc a été créé par le client pour un appel multipoint. Le gestionnaire d’appels doit allouer et initialiser toutes les ressources nécessaires pour conserver les informations d’état et contrôler un appel multipoint. Ces ressources incluent, sans s’y limiter, les mémoires tampons, les structures de données, les événements et d’autres ressources similaires. Si le gestionnaire d’appels ne peut pas allouer ou initialiser les ressources nécessaires pour ses zones d’état, il doit retourner le contrôle à NDIS avec NDIS_STATUS_RESOURCES.

ProtocolCmMakeCall communique avec les appareils de contrôle réseau ou d’autres acteurs spécifiques aux médias, si nécessaire, pour établir une connexion entre le nœud local et un nœud distant en fonction des paramètres d’appel spécifiés dans CallParameters . Ces actions peuvent inclure, sans s’y limiter, la communication avec le matériel de basculement, les communications 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 du matériel réseau (par exemple, un commutateur réseau), il doit utiliser une connexion virtuelle au périphérique de contrôle réseau qu’il a établi dans sa fonction ProtocolBindAdapterEx . Les responsables d’appels communiquent avec leur matériel réseau via le pilote miniport en appelant NdisCoSendNetBufferLists. Les pilotes Miniport avec prise en charge intégrée de la gestion des appels n’appellent pas NdisCoSendNetBufferLists, mais transmettent les données eux-mêmes.

Une fois qu’un gestionnaire d’appels a effectué toutes les communications nécessaires avec son matériel réseau, comme requis par son support, les gestionnaires d’appels doivent appeler NdisCmActivateVc.

Si cet appel était un appel multipoint, une fois que le gestionnaire d’appels a communiqué avec le matériel réseau, vérifié les paramètres d’appel et alloué et initialisé ses données d’état par partie, l’adresse de son bloc d’état doit être définie dans le handle CallMgrPartyContext avant de renvoyer le contrôle à NDIS. Le handle est défini en déréférencement du handle et en stockant un pointeur vers le bloc d’état comme valeur du handle. Par exemple :

*CallMgrPartyContext = SomeBuffer ;

Si ProtocolCmMakeCall a terminé les opérations requises pour son réseau et que le VC a été correctement activé via NdisCmActivateVc, ProtocolCmMakeCall doit retourner le contrôle aussi rapidement que possible avec un status de STATUS_SUCCESS.

Une fois que ProtocolCmMakeCall a retourné le contrôle à NDIS, le gestionnaire d’appels doit s’attendre à n’effectuer aucune autre action sur cet appel pour le configurer. ProtocolCmMakeCall est responsable de l’établissement de la connexion afin que le client puisse effectuer des transferts de données sur le réseau sur ce VC. Toutefois, le gestionnaire d’appels peut être appelé par la suite pour modifier la qualité de service de l’appel, pour ajouter ou supprimer des parties s’il s’agit d’une vc multipoint, et éventuellement pour mettre fin à cet appel.

Exemples

Pour définir une fonction ProtocolCmMakeCall , 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, le vérificateur de pilotes statique (SDV) et d’autres outils de vérification de trouver les erreurs, et 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 ProtocolCmMakeCall nommée « MyCmMakeCall », utilisez le type PROTOCOL_CM_MAKE_CALL comme indiqué dans cet exemple de code :

PROTOCOL_CM_MAKE_CALL MyCmMakeCall;

Ensuite, implémentez votre fonction comme suit :

_Use_decl_annotations_
NDIS_STATUS
 MyCmMakeCall(
    NDIS_HANDLE  CallMgrVcContext,
    PCO_CALL_PARAMETERS  CallParameters,
    NDIS_HANDLE  NdisPartyHandle,
    PNDIS_HANDLE  CallMgrPartyContext
    )
  {...}

Le type de fonction PROTOCOL_CM_MAKE_CALL 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_MAKE_CALL 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 ProtocolCmMakeCall (NDIS 5.1)) dans Windows Vista. Pris en charge pour les pilotes NDIS 5.1 (consultez ProtocolCmMakeCall (NDIS 5.1)) dans Windows XP.
Plateforme cible	Windows
En-tête	ndis.h (inclure Ndis.h)
IRQL	<= DISPATCH_LEVEL