Fonction NdisCoAssignInstanceName (ndis.h)

Article
02/26/2024

NdisCoAssignInstanceName affecte un nom instance à un vc et permet à NDIS d’inscrire un GUID (identificateur global unique) pour le nom attribué auprès de Windows Management Instrumentation (WMI).

Syntaxe

NDIS_STATUS NdisCoAssignInstanceName(
  [in]            NDIS_HANDLE  NdisVcHandle,
  [in]            PNDIS_STRING BaseInstanceName,
  [out, optional] PNDIS_STRING VcInstanceName
);

Paramètres

[in] NdisVcHandle

Spécifie le handle du vc nommé. Ce handle a été fourni par NDIS lorsque le VC a été créé à l’origine avec NdisCoCreateVc, que ce soit par le client en préparation d’un appel sortant ou par le gestionnaire d’appels en préparation de la distribution d’un appel entrant au client.

[in] BaseInstanceName

Pointeur vers un type NDIS_STRING qui décrit une chaîne Unicode fournie par l’appelant qui spécifie le nom de base du vc. Le nom de base peut être n’importe quelle chaîne Unicode localisable qui identifie de manière unique le vc par rapport aux autres machines virtuelles nommées dans l’étendue du pilote miniport. Pour Windows Vista et versions ultérieures, NDIS définit le type NDIS_STRING comme un type UNICODE_STRING .

[out, optional] VcInstanceName

Pointeur vers un type de NDIS_STRING alloué à l’appelant dans lequel cette routine retourne une chaîne Unicode qui spécifie le nom de instance attribué par NDIS pour le vc.

Valeur retournée

NdisCoAssignInstanceName peut retourner l’un des éléments suivants :

Code de retour	Description
NDIS_STATUS_SUCCESS	NDIS a attribué un nom de instance au vc spécifié et a enregistré un GUID pour le nom instance avec WMI.
NDIS_STATUS_FAILURE	La tentative d’affectation d’un nom instance au vc a échoué.
NDIS_STATUS_RESOURCES	NDIS n’a pas pu allouer de mémoire tampon pour le nom instance.

Remarques

Après avoir lancé la configuration d’un vc avec NdisCoCreateVc, un gestionnaire d’appels ou un client orienté connexion peut nommer le vc avec NdisCoAssignInstanceName. L’appel de NdisCoAssignInstanceName permet à NDIS d’affecter au vc un nom de instance et d’inscrire le nom instance auprès de WMI. Les clients WMI peuvent ensuite énumérer le VC et interroger ou définir des OID par rapport au vc.

Un pilote MCM (miniport call manager) intégré ne peut pas utiliser NdisCoAssignInstanceName pour nommer ses machines virtuelles. Au lieu de cela, un pilote MCM doit créer un GUID et un OID personnalisés pour le vc et inscrire le mappage GUID-to-OID avec NDIS.

NDIS crée un nom instance pour le vc spécifié en ajoutant un index au nom de base pointé par l’appelant. NDIS retourne le nom de instance complet (nom de base + index) à l’appelant, puis inscrit un GUID pour le nom instance avec WMI. Seules les machines virtuelles nommées peuvent être énumérées et interrogées par les clients WMI. Les machines virtuelles sans nom ne sont pas visibles pour les clients WMI.

Si le vc spécifié a déjà un nom instance (attribué dans un appel précédent à NdisCoAssignInstanceName), NDIS retourne NDIS_STATUS_SUCCESS et le nom de instance d’origine attribué au vc. Un nom de instance reste attribué à un vc jusqu’à ce que ce vc soit supprimé.

L’appelant peut associer le nom instance retourné au handle du vc nommé que NDIS a précédemment retourné à l’appelant à partir de NdisCoCreateVc. NDIS, toutefois, continuera d’utiliser le handle VC (et non le nom instance) pour faire référence au vc dans les appels suivants. L’appelant de NdisCoAssignInstanceName peut trouver la nécessité de renvoyer le nom instance à une autre entité de gestion.

L’appelant est chargé de libérer la mémoire tampon contenant le nom instance retourné. Après avoir supprimé le vc nommé avec NdisCoDeleteVc, l’appelant doit libérer la mémoire tampon avec NdisFreeString.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Pris en charge pour les pilotes NDIS 6.0 et NDIS 5.1 (voir NdisCoAssignInstanceName (NDIS 5.1)) dans Windows Vista. Pris en charge pour les pilotes NDIS 5.1 (consultez NdisCoAssignInstanceName (NDIS 5.1)) dans Windows XP.
Plateforme cible	Desktop (Expérience utilisateur)
En-tête	ndis.h (inclure Ndis.h)
Bibliothèque	Ndis.lib
IRQL	DISPATCH_LEVEL
Règles de conformité DDI	Irql_Connection_Function(ndis)