PROTOCOL_CO_CREATE_VC fonction de rappel (ndis.h)

Article
02/26/2024

La fonction ProtocolCoCreateVc est une fonction obligatoire qui alloue les ressources nécessaires à un gestionnaire d’appels ou à un client pour activer et gérer une connexion virtuelle (VC).

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

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 ProtocolCoAfRegisterNotify .

[in] NdisVcHandle

Spécifie un handle, fourni par NDIS, qui identifie de manière 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 aux fonctions NdisCo/Cl/Cm/MCmXxx qui concernent ce 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 retournée

ProtocolCoCreateVc 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 ou le client a correctement alloué et/ou initialisé toutes les ressources nécessaires pour établir et maintenir une connexion virtuelle.
NDIS_STATUS_RESOURCES	Indique que le gestionnaire d’appels ou le client n’a pas pu allouer et/ou initialiser ses ressources pour établir et maintenir une connexion virtuelle.
NDIS_STATUS_XXX	Indique que le gestionnaire d’appels ou le client n’a pas pu se définir dans un état où il pourrait é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. Note Les gestionnaires d’appels ou les clients ne peuvent pas retourner NDIS_STATUS_PENDING à partir de leurs fonctions ProtocolCoCreateVc . Le retour en attente rend cette connexion virtuelle inutilisable et la bibliothèque NDIS appelle le client ou le gestionnaire d’appels pour la 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 appelle respectivement 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 d’informer son client que le cm a reçu une offre d’appel entrante à partir d’un nœud distant qui est 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 dont le gestionnaire d’appels ou le client a besoin pour effectuer les opérations suivantes sur un vc qui sera activé. Ces ressources incluent, sans s’y limiter, des mémoires tampons, des structures de données, des événements et d’autres ressources similaires. Les gestionnaires d’appels et les clients doivent également initialiser toutes les structures pertinentes par VC dont ils auront besoin lorsqu’un appel est établi.

Les pilotes de protocole orientés connexion doivent stocker le handle pour le vc, spécifié dans NdisVcHandle, dans leur zone d’état par VC pour être utilisé dans les opérations futures sur cette connexion virtuelle. Le NdisVcHandle est le paramètre requis pour NdisCoXxx, NdisCmXxx et/ou NdisClXxx qu’un tel 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 renvoyer 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 par le protocole comme valeur du handle. Par exemple :

*ProtocolVcContext = SomeBuffer;

Si ProtocolCoCreateVc ne peut pas allouer la ressource dont il a besoin pour effectuer des opérations d’E/S réseau ultérieures, il doit libérer toutes les ressources qui ont été allouées pour cette VC et retourner le contrôle avec un status de NDIS_STATUS_RESOURCES.

Si ProtocolCoCreateVc a terminé les opérations requises et que le gestionnaire d’appels ou le client est prêt à effectuer l’initialisation des appels pour cette connexion virtuelle, ProtocolCoCreateVc doit retourner le contrôle le plus rapidement possible avec un status de NDIS_STATUS_SUCCESS.

Les appels à ProtocolCoCreateVc sont par nature synchrones. C’est-à-dire que ProtocolCoCreateVcne peut pas retourner NDIS_STATUS_PENDING.

Une fois que la fonction ProtocolCoCreateVc d’un 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 entreprendre d’action dans ProtocolCmMakeCall qui établit réellement un appel, car il est possible que le VC soit détruit avant qu’un appel ne 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 lancée à distance de connexion sur un SAP précédemment inscrit par le client arrive sur le réseau.

Exemples

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