PROTOCOL_CL_ADD_PARTY_COMPLETE fonction de rappel (ndis.h)

Article
02/29/2024

La fonction ProtocolClAddPartyComplete est requise pour les clients NDIS orientés connexion qui configurent des connexions multipoint. Ces clients doivent avoir des fonctions ProtocolClAddPartyComplete pour effectuer les opérations asynchrones qu’ils lancent avec NdisClAddParty. Sinon, la fonction ProtocolClAddPartyComplete 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_ADD_PARTY_COMPLETE . Pour plus d’informations, consultez la section Exemples suivante.

Syntaxe

PROTOCOL_CL_ADD_PARTY_COMPLETE ProtocolClAddPartyComplete;

void ProtocolClAddPartyComplete(
  [in] NDIS_STATUS Status,
  [in] NDIS_HANDLE ProtocolPartyContext,
  [in] NDIS_HANDLE NdisPartyHandle,
  [in] PCO_CALL_PARAMETERS CallParameters
)
{...}

Paramètres

[in] Status

Spécifie la status finale de l’opération de partie complémentaire initiée par le client, qui peut être l’une des suivantes :

NDIS_STATUS_SUCCESS

La partie donnée a été ajoutée au vc multipoint actif du client.

NDIS_STATUS_RESOURCES

NDIS n’a pas pu allouer suffisamment de ressources pour suivre la nouvelle partie.

NDIS_STATUS_FAILURE

Le client a transmis un NdisVcHandle non valide à NdisClAddParty.

NDIS_STATUS_XXX

La fonction ProtocolCmAddParty du gestionnaire d’appels a retourné une valeur déterminée par CM pour indiquer pourquoi elle n’a pas pu ajouter le tiers au vc.

[in] ProtocolPartyContext

Spécifie le handle fourni par le client passé à l’origine à NdisClAddParty.

[in] NdisPartyHandle

Si Status est NDIS_STATUS_SUCCESS, ce handle fourni par NDIS représente l’association entre le gestionnaire d’appels et le client concernant ce tiers. Sinon, la tentative d’ajout d’un tiers a échoué et le client doit considérer ce paramètre comme un handle non valide.

[in] CallParameters

Pointeur vers une structure de type CO_CALL_PARAMETERS, initialement configurée par le client pour son appel à NdisClAddParty , mais éventuellement modifiée par la suite par le gestionnaire d’appels.

Valeur de retour

None

Remarques

Un appel à ProtocolClAddPartyComplete indique l’achèvement de l’opération asynchrone lancée lorsque le client a appelé NdisClAddParty. Si l’état d’entrée est défini sur autre chose que NDIS_STATUS_SUCCESS, ProtocolClAddPartyComplete peut libérer ou réutiliser les mémoires tampons allouées par le client sur ProtocolPartyContext et sur CallParameters .

Si la tentative d’ajout d’une partie a réussi, ProtocolClAddPartyComplete doit enregistrer l’entrée NdisPartyHandle pour les appels ultérieurs aux fonctions de bibliothèque NDIS concernant ce tiers dans la zone ProtocolPartyContext du client. Par exemple, le client doit passer ce handle dans un appel ultérieur à NdisClDropParty , à moins que la partie distante qu’il représente ferme d’abord sa connexion.

La structure de CallParameters a été initialement allouée et initialisée par le client, qui a passé ce pointeur vers
NdisClAddParty. Toutefois, le gestionnaire d’appels peut avoir modifié les valeurs fournies par le client pour refléter les résultats de la négociation du cm avec le réseau ou avec un homologue de signalisation lors du traitement de la demande complémentaire du client. Pour déterminer si le gestionnaire d’appels a apporté des modifications, ProtocolClAddPartyComplete peut case activée le membre Flags de cette structure pour déterminer si CALL_PARAMETERS_CHANGED est défini. Si c’est le cas, ProtocolClAddPartyComplete doit mettre à jour l’état par partie que le client gère pour cet appel dans ProtocolPartyContext , sauf s’il trouve les modifications du cm inacceptables. Le protocole de signalisation particulier détermine ce que le client peut faire dans ce cas. En règle générale, un client appelle NdisClDropParty s’il trouve les paramètres d’appel modifiés par CM inacceptables.

Selon le protocole de signalisation du gestionnaire d’appels, les paramètres de trafic dans CallParameters peuvent être identiques pour toutes les parties sur une connexion multipoint particulière. Autrement dit, comme le client d’un tel gestionnaire d’appels ajoute des parties sur une connexion multipoint que le client a initialement configurée avec NdisClMakeCall, il peut fournir uniquement l’adresse cible de chaque partie et laisser les paramètres de trafic tels qu’initialement configurés pour le vc multipoint chaque fois qu’il appelle NdisClAddParty.

Exemples

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

PROTOCOL_CL_ADD_PARTY_COMPLETE MyClAddPartyComplete;

Ensuite, implémentez votre fonction comme suit :

_Use_decl_annotations_
VOID
 MyClAddPartyComplete(
    NDIS_STATUS  Status,
    NDIS_HANDLE  ProtocolPartyContext,
    NDIS_HANDLE  NdisPartyHandle,
    PCO_CALL_PARAMETERS  CallParameters
    )
  {...}

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