PROTOCOL_CL_MAKE_CALL_COMPLETE fonction de rappel (ndis.h)

Article
08/07/2023

La fonction ProtocolClMakeCallComplete est utilisée par les clients NDIS orientés connexion qui effectuent des appels sortants. Ces clients doivent disposer de fonctions ProtocolClMakeCallComplete pour effectuer les opérations asynchrones qu’ils lancent avec NdisClMakeCall. Sinon, la fonction ProtocolClMakeCallComplete inscrite d’un pilote de protocole peut simplement retourner le contrôle.

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

Syntaxe

PROTOCOL_CL_MAKE_CALL_COMPLETE ProtocolClMakeCallComplete;

void ProtocolClMakeCallComplete(
  [in]           NDIS_STATUS Status,
  [in]           NDIS_HANDLE ProtocolVcContext,
  [in, optional] NDIS_HANDLE NdisPartyHandle,
  [in]           PCO_CALL_PARAMETERS CallParameters
)
{...}

Paramètres

[in] Status

Spécifie le status final de l’appel d’origine du client à NdisClMakeCall, qui peut être l’un des éléments suivants :

NDIS_STATUS_SUCCESS

La tentative du client de configurer une connexion virtuelle a réussi. Par conséquent, le client peut procéder à des transferts sur le vc actif à l’aide du NdisVcHandle retourné par NdisCoCreateVc, que le client a stocké dans sa zone de contexte par VC sur ProtocolVcContext .

NDIS_STATUS_RESOURCES

NDIS, le gestionnaire d’appels ou un pilote sous-jacent n’ont pas pu allouer suffisamment de ressources pour configurer la connexion.

NDIS_STATUS_XXX

Le gestionnaire d’appels ou le pilote miniport sous-jacent n’ont pas pu établir une connexion active et NDIS a propagé cette défaillance déterminée par le pilote status au client.

[in] ProtocolVcContext

Spécifie le handle de la zone de contexte par VC du client, que le client a initialement fourni à NDIS lorsqu’il a appelé NdisCoCreateVc pour configurer le vc pour son appel sortant.

[in, optional] NdisPartyHandle

Si Status est NDIS_STATUS_SUCCESS et que le client a créé un vc multipoint en passant un handle ProtocolPartyContext explicite à NdisClMakeCall, il s’agit d’un NdisPartyHandle valide . Sinon, ce paramètre a la valeur NULL.

ProtocolClMakeCallComplete doit enregistrer toute entrée valide NdisPartyHandle, généralement dans la zone de contexte par partie du client. Le client doit utiliser ce handle si (ou quand) il effectue un appel ultérieur à NdisClDropParty ou NdisClCloseCall qui fait référence à cette partie.

[in] CallParameters

Pointeur vers une structure CO_CALL_PARAMETERS mise en mémoire tampon. Le client a alloué cette mémoire tampon et initialisé cette structure avec des données déterminées par le client avant de passer ce pointeur à NdisClMakeCall. Lors du traitement de la demande du client, le gestionnaire d’appels peut modifier ces données pour refléter les résultats de leur négociation avec le réseau ou avec un homologue de signalisation.

Valeur de retour

None

Remarques

Un appel à ProtocolClMakeCallComplete indique que le gestionnaire d’appels a terminé le traitement de la demande du client d’établir une connexion virtuelle avec NdisClMakeCall.

Si la tentative du client d’établir un appel sortant échoue ( l’état d’entrée est tout sauf NDIS_STATUS_SUCCESS), ProtocolClMakeCallComplete doit effectuer les opérations suivantes :

Libérez ou préparez la réutilisation de la zone ProtocolPartyContext , le cas échéant, et de la mémoire tampon sur CallParameters allouées par le client.
Démontez le vc créé par le client avec un appel à NdisCoDeleteVc et libérez ou préparez la réutilisation de la zone ProtocolVcContext allouée par le client.

Sinon, ProtocolClMakeCallComplete doit effectuer les opérations suivantes :

Vérifiez le membre Flags de la structure dans CallParameters pour voir si CALL_PARAMETERS_CHANGED est défini, ce qui indique que le gestionnaire d’appels a modifié les paramètres d’appel fournis par le client.
Si c’est le cas, examinez les données dans CallParameters pour déterminer si elles sont acceptables pour cette connexion.
Par exemple, le client peut conserver les paramètres d’appel mis en mémoire tampon pour le vc actif, enregistrer le NdisPartyHandle s’il s’agit d’un vc multipoint, et généralement préparer le client pour les transferts suivants et d’autres opérations sur le VC actif s’il trouve les paramètres d’appel donnés satisfaisants.
Si ce n’est pas le cas, le protocole de signalisation détermine si le client peut tenter de renégocier des paramètres d’appel acceptables avec le gestionnaire d’appels.
Par exemple, un gestionnaire d’appels particulier peut autoriser ses clients à appeler NdisClModifyCallQoS une ou plusieurs fois dans ces circonstances.
Si les paramètres d’appel modifiés par CM sont inacceptables et qu’une renégociation supplémentaire est impossible, ProtocolClMakeCallComplete doit supprimer l’appel avec NdisClCloseCall.
Dans ce cas, ProtocolClMakeCallCompletene doit pas tenter de libérer les ressources allouées par le client au retour de NdisClCloseCall , mais peut simplement retourner le contrôle. Au lieu de cela, le client doit libérer les ressources qu’il a allouées (ou les préparer pour une réutilisation) dans sa fonction ProtocolClCloseCallComplete .

Exemples

Pour définir une fonction ProtocolClMakeCallComplete , 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 ProtocolClMakeCallComplete nommée « MyClMakeCallComplete », utilisez le type PROTOCOL_CL_MAKE_CALL_COMPLETE comme indiqué dans cet exemple de code :

PROTOCOL_CL_MAKE_CALL_COMPLETE MyClMakeCallComplete;

Ensuite, implémentez votre fonction comme suit :

_Use_decl_annotations_
VOID
 MyClMakeCallComplete(
    NDIS_STATUS  Status,
    NDIS_HANDLE  ProtocolVcContext,
    NDIS_HANDLE  NdisPartyHandle,
    PCO_CALL_PARAMETERS  CallParameters
    )
  {...}

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