PROTOCOL_CO_CREATE_VC fonction de rappel (ndis.h)
La fonction ProtocolCoCreateVc est une fonction requise qui alloue des ressources nécessaires pour qu’un gestionnaire d’appels ou un client active et conserve une connexion virtuelle (VC).
Syntaxe
PROTOCOL_CO_CREATE_VC ProtocolCoCreateVc;
NDIS_STATUS ProtocolCoCreateVc(
[in] NDIS_HANDLE ProtocolAfContext,
[in] NDIS_HANDLE NdisVcHandle,
[out] PNDIS_HANDLE ProtocolVcContext
)
{...}
Paramètres
[in] ProtocolAfContext
Spécifie le handle dans une zone de contexte allouée par protocole dans laquelle le gestionnaire d’appels ou le client conserve son état par ouverture. Le gestionnaire d’appels a fourni ce handle à partir de sa fonction ProtocolCmOpenAf. Le client a fourni ce handle lorsqu’il a appelé NdisClOpenAddressFamilyEx à partir de sa fonction ProtocolCoRegisterNotify.
[in] NdisVcHandle
Spécifie un handle, fourni par NDIS, qui identifie de façon unique cette connexion virtuelle. Ce handle est opaque pour le pilote de protocole et réservé à l’utilisation de la bibliothèque NDIS. Toutefois, le gestionnaire d’appels et le client doivent enregistrer ce handle pour passer les appels suivants à NdisCo/Cl/Cm/MCmfonctions xxx qui concernent cette vc.
[out] ProtocolVcContext
Spécifie le handle dans une zone de contexte fournie par le protocole dans laquelle le gestionnaire d’appels ou le client conserve l’état de cette connexion virtuelle.
Valeur de retour
ProtocolCoCreateVc retourne l’état de ses opérations comme l’une des valeurs suivantes :
| Retourner le code | Description |
|---|---|
|
Indique que le gestionnaire d’appels ou le client a correctement alloué et/ou initialisé toutes les ressources nécessaires pour établir et gérer une connexion virtuelle. |
|
Indique que le gestionnaire d’appels ou le client n’a pas pu allouer et/ou initialiser ses ressources pour établir et gérer une connexion virtuelle. |
|
Indique que le gestionnaire d’appels ou le client n’a pas pu se définir lui-même dans un état où il peut établir une connexion virtuelle. Il peut s’agir d’une valeur de retour d’erreur propagée à partir d’une autre routine de bibliothèque NDIS.
Remarque gestionnaires d’appels ou clients ne peuvent pas retourner NDIS_STATUS_PENDING à partir de leurs fonctions de ProtocolCoCreateVc. Le retour en attente affiche cette connexion virtuelle inutilisable et la bibliothèque NDIS appelle le client ou le gestionnaire d’appels pour le supprimer.
|
Remarques
La fonction ProtocolCoCreateVc d’un gestionnaire d’appels ou d’un client est appelée chaque fois que le client ou le gestionnaire d’appels correspondant, respectivement, appelle NdisCoCreateVc. Les clients lancent la création de machines virtuelles dans le processus de configuration de leurs appels sortants avant d’appeler NdisClMakeCall. Un gestionnaire d’appels lance la création d’un vc dans le processus de notification de son client que le CM a reçu une offre d’appel entrante à partir d’un nœud distant dirigé vers un SAP déjà inscrit auprès du CLIENT par ce client avant les appels CM NdisCmDispatchIncomingCall.
ProtocolCoCreateVc effectue toutes les allocations nécessaires de ressources et de structures dynamiques requises par le gestionnaire d’appels ou le client pour effectuer les opérations suivantes sur une vc qui sera activée. 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. Les gestionnaires d’appels et les clients doivent également initialiser toutes les structures par vc pertinentes dont ils auront besoin lorsqu’un appel est établi.
Les pilotes de protocole orientés connexion doivent stocker le handle pour la vc, spécifié dans NdisVcHandle, dans leur zone d’état par VC à utiliser dans les opérations futures sur cette connexion virtuelle. Le NdisVcHandle est le paramètre requis pour le NdisCoXxx, NdisCmXxxet/ou NdisClXxx qu’un protocole orienté connexion appelle par la suite.
Lorsqu’un gestionnaire d’appels ou un client a alloué de la mémoire pour ses propres données par VC et initialisé son état, l’adresse de cette structure de données doit être définie dans le handle avant de retourner le contrôle à NDIS. Pour ce faire, déréférencez le handle et stockez un pointeur vers la zone de données allouée au protocole comme valeur du handle. Par exemple:
*ProtocolVcContext = SomeBuffer;
Si ProtocolCoCreateVc ne peut pas allouer la ressource dont elle a besoin pour effectuer les opérations d’E/S réseau suivantes, elle doit libérer toutes les ressources allouées pour ce contrôle VC et retourner le contrôle avec l’état de NDIS_STATUS_RESOURCES.
Si ProtocolCoCreateVc a effectué ses opérations requises et a rendu le gestionnaire d’appels ou le client prêt à effectuer l’initialisation des appels pour cette connexion virtuelle, ProtocolCoCreateVc doit retourner le contrôle le plus rapidement possible avec un état de NDIS_STATUS_SUCCESS.
Les appels à ProtocolCoCreateVc sont de nature intrinsèquement synchrone. Autrement dit, ProtocolCoCreateVcne peut pas retourner NDIS_STATUS_PENDING.
Une fois que la fonction ProtocolCoCreateVc du gestionnaire d’appels retourne le contrôle, la fonction ProtocolCmMakeCall du gestionnaire d’appels est appelée pour établir une connexion à un nœud distant. Les gestionnaires d’appels ne doivent pas prendre de mesures dans ProtocolCmMakeCall qui établit réellement un appel, car il est possible que la vc soit détruite avant qu’un appel soit établi en raison d’une condition d’erreur dans un autre composant de NDIS orienté connexion.
Une fois que la fonction ProtocolCoCreateVc d’un client retourne le contrôle, la fonction ProtocolClIncomingCall du client est avertie lorsqu’une demande initiée à distance pour se connecter sur un SAP précédemment inscrit par le client est envoyée sur le réseau.
exemples de
Pour définir une fonction ProtocolCoCreateVc, 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 ProtocolCoCreateVc nommée « MyCoCreateVc », utilisez le type PROTOCOL_CO_CREATE_VC comme indiqué dans cet exemple de code :
PROTOCOL_CO_CREATE_VC MyCoCreateVc;
Ensuite, implémentez votre fonction comme suit :
_Use_decl_annotations_
NDIS_STATUS
MyCoCreateVc(
NDIS_HANDLE ProtocolAfContext,
NDIS_HANDLE NdisVcHandle,
PNDIS_HANDLE ProtocolVcContext
)
{...}
Le type de fonction PROTOCOL_CO_CREATE_VC 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_CO_CREATE_VC 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 ProtocolCoCreateVc (NDIS 5.1)) dans Windows Vista. Pris en charge pour les pilotes NDIS 5.1 (voir ProtocolCoCreateVc (NDIS 5.1)) dans Windows XP. |
| plateforme cible | Windows |
| d’en-tête | ndis.h (include Ndis.h) |
| IRQL | <= DISPATCH_LEVEL |