PROTOCOL_CM_MAKE_CALL fonction de rappel (ndis.h)
La fonction ProtocolCmMakeCall est une fonction requise qui configure des paramètres spécifiques au média pour une connexion virtuelle (VC) et active la connexion virtuelle.
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 son é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 est NULL si le client ne configure pas d’appel multipoint sortant.
[out, optional] CallMgrPartyContext
Lors du retour, spécifie un handle dans une zone de contexte fournie par le gestionnaire d’appels dans laquelle le gestionnaire d’appels conserve l’état de la partie initiale de l’appel multipoint. Si NdisPartyHandle est NULL, ce handle doit être défini sur NULL.
Valeur de retour
ProtocolCmMakeCall retourne l’état de ses opérations comme l’une des valeurs suivantes :
| Retourner le code | Description |
|---|---|
|
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. |
|
Indique que le gestionnaire d’appels termine la requête pour effectuer un appel de manière asynchrone. Lorsque le gestionnaire d’appels a terminé toutes les opérations pour effectuer un appel, il doit appeler NdisCmMakeCallComplete pour signaler à NDIS que cet appel a été terminé. |
|
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. |
|
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 indisponibles dans les paramètres d’appel spécifiés à CallParameters. |
Remarques
Si ProtocolCmMakeCall reçoit un NdisPartyHandle explicite, cette vc a été créée 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, mais elles ne sont pas limitées aux mémoires tampons, aux structures de données, aux événements et à d’autres ressources similaires. Si le gestionnaire d’appels ne peut pas allouer ou initialiser les ressources nécessaires pour sa ou ses zones d’état, il doit retourner le contrôle à NDIS avec NDIS_STATUS_RESOURCES.
ProtocolCmMakeCall communique avec des périphériques de contrôle réseau ou d’autres acteurs spécifiques au support, 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 à CallParameters. Ces actions peuvent inclure, mais elles ne sont pas limitées à la communication avec le matériel de basculement, les communications avec une station de contrôle réseau ou d’autres actions appropriées pour le 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 à l’appareil de contrôle réseau qu’il a établi dans sa fonction ProtocolBindAdapterEx. Les gestionnaires 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 plutôt les données elles-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 retourner le contrôle à NDIS. Le handle est défini en déreferencant le handle et en stockant un pointeur vers le bloc d’état comme valeur du handle. Par exemple:
*CallMgrPartyContext = SomeBuffer ;
Si ProtocolCmMakeCall a effectué les opérations requises pour son réseau et que le vc a été activé avec succès via NdisCmActivateVc, ProtocolCmMakeCall doit retourner le contrôle le plus rapidement possible avec un état de STATUS_SUCCESS.
Après ProtocolCmMakeCall retourne le contrôle à NDIS, le gestionnaire d’appels doit s’attendre à prendre 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’un vc multipoint, et éventuellement pour arrêter cet appel.
exemples de
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 fonctions permet d'Analyse du code pour les pilotes, de vérificateur de pilotes statiques (SDV) et d’autres outils de vérification recherchent des erreurs, et il est nécessaire d’écrire des 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 lorsque vous exécutez les 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 annoter le comportement de la fonction.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum 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 (voir ProtocolCmMakeCall (NDIS 5.1)) dans Windows XP. |
| plateforme cible | Windows |
| d’en-tête | ndis.h (include Ndis.h) |
| IRQL | <= DISPATCH_LEVEL |