Fonction NotifyStableUnicastIpAddressTable (netioapi.h)

Article
08/25/2023

La fonction NotifyStableUnicastIpAddressTable récupère la table d’adresses IP unicast stable sur un ordinateur local.

Syntaxe

IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API NotifyStableUnicastIpAddressTable(
  [in]      ADDRESS_FAMILY                           Family,
  [in, out] PMIB_UNICASTIPADDRESS_TABLE              *Table,
  [in]      PSTABLE_UNICAST_IPADDRESS_TABLE_CALLBACK CallerCallback,
  [in]      PVOID                                    CallerContext,
  [in, out] HANDLE                                   *NotificationHandle
);

Paramètres

[in] Family

Famille d’adresses à récupérer.

Les valeurs possibles pour la famille d’adresses sont répertoriées dans le fichier d’en-tête Winsock2.h . Notez que les valeurs de la AF_ adressent les constantes famille et PF_ de famille de protocole sont identiques (par exemple, AF_INET et PF_INET), de sorte que l’une ou l’autre constante peut être utilisée.

Sur le SDK Windows publié pour Windows Vista et versions ultérieures, le organization des fichiers d’en-tête a changé et les valeurs possibles pour ce membre sont définies dans le fichier d’en-tête Ws2def.h. Notez que le fichier d’en-tête Ws2def.h est automatiquement inclus dans Winsock2.h et ne doit jamais être utilisé directement.

Les valeurs actuellement prises en charge sont AF_INET, AF_INET6 et AF_UNSPEC.

Valeur	Signification
AF_UNSPEC 0	La famille d’adresses n’est pas spécifiée. Lorsque ce paramètre est spécifié, la fonction récupère la table d’adresses IP unicast stable contenant à la fois des entrées IPv4 et IPv6.
AF_INET 2	Famille d’adresses IPv4 (Internet Protocol version 4). Lorsque ce paramètre est spécifié, la fonction récupère la table d’adresses IP de unidiffusion stable contenant uniquement des entrées IPv4.
AF_INET6 23	Famille d’adresses IPv6 (Internet Protocol version 6). Lorsque ce paramètre est spécifié, la fonction récupère la table d’adresses IP unicast stable contenant uniquement les entrées IPv6.

[in, out] Table

Pointeur vers une structure MIB_UNICASTIPADDRESS_TABLE . Lorsque NotifyStableUnicastIpAddressTable réussit, ce paramètre retourne la table d’adresses IP unidiffusion stable sur l’ordinateur local.

Lorsque NotifyStableUnicastIpAddressTable retourne ERROR_IO_PENDING indiquant que la demande d’E/S est en attente, la table d’adresses IP unicast stable est retournée à la fonction dans le paramètre CallerCallback .

[in] CallerCallback

Pointeur vers la fonction à appeler avec la table d’adresses IP de unidiffusion stable. Cette fonction sera appelée si NotifyStableUnicastIpAddressTable retourne ERROR_IO_PENDING, ce qui indique que la demande d’E/S est en attente.

[in] CallerContext

Contexte utilisateur passé à la fonction de rappel spécifiée dans le paramètre CallerCallback lorsque la table d’adresses IP stable unicast est disponible.

[in, out] NotificationHandle

Pointeur utilisé pour retourner un handle qui peut être utilisé pour annuler la demande de récupération de la table d’adresses IP de unidiffusion stable. Ce paramètre est retourné si la valeur de retour de NotifyStableUnicastIpAddressTable est ERROR_IO_PENDING indiquant que la demande d’E/S est en attente.

Valeur retournée

Si la fonction réussit immédiatement, la valeur de retour est NO_ERROR et la table IP de unidiffusion stable est retournée dans le paramètre Table .

Si la demande d’E/S est en attente, la fonction retourne ERROR_IO_PENDING et la fonction pointée par le paramètre CallerCallback est appelée lorsque la demande d’E/S est terminée avec la table d’adresses IP de unidiffusion stable.

Si la fonction échoue, la valeur de retour est l’un des codes d’erreur suivants.

Code de retour	Description
ERROR_INVALID_HANDLE	Une erreur interne s’est produite lorsqu’un handle non valide a été rencontré.
ERROR_INVALID_PARAMETER	Un paramètre non valide a été transmis à la fonction. Cette erreur est retournée si le paramètre Table était un pointeur NULL , si le paramètre NotificationHandle était un pointeur NULL ou si le paramètre Familyn’était pas AF_INET, AF_INET6 ou AF_UNSPEC.
ERROR_NOT_ENOUGH_MEMORY	La mémoire était insuffisante.
Autres	Utilisez FormatMessage pour obtenir la chaîne de message pour l’erreur retournée.

Remarques

La fonction NotifyStableUnicastIpAddressTable est définie sur Windows Vista et versions ultérieures.

Si la fonction NotifyStableUnicastIpAddressTable réussit immédiatement, la valeur de retour est NO_ERROR et la table IP unicast stable est retournée dans le paramètre Table . L’application appelante doit libérer la mémoire vers laquelle pointe le paramètre Table à l’aide de la fonction FreeMibTable lorsque les informations MIB_UNICASTIPADDRESS_TABLE ne sont plus nécessaires.

Toutes les adresses IP unicast, à l’exception des adresses de numérotation à la demande, sont considérées comme stables uniquement si elles sont dans l’état préféré. Pour une entrée d’adresse IP unicast normale, cela correspond à un membre DadState du MIB_UNICASTIPADDRESS_ROW pour l’adresse IP définie sur IpDadStatePreferred. Chaque adresse de numérotation à la demande définit sa propre métrique de stabilité. Actuellement, la seule adresse de numérotation à la demande prise en compte par cette fonction est l’adresse IP unicast utilisée par le client Teredo sur l’ordinateur local.

Le paramètre Family doit être défini sur AF_INET, AF_INET6 ou AF_UNSPEC.

Lorsque NotifyStableUnicastIpAddressTable réussit et retourne NO_ERROR, le paramètre Table renvoie la table d’adresses IP unicast stable sur l’ordinateur local.

La fonction NotifyStableUnicastIpAddressTable est principalement utilisée par les applications qui utilisent le client Teredo.

Si l’adresse IP de unidiffusion utilisée par Teredo est disponible sur l’ordinateur local, mais pas à l’état stable (qualifié), NotifyStableUnicastIpAddressTable retourne ERROR_IO_PENDING et la table d’adresses IP unicast stable est finalement retournée en appelant la fonction dans le paramètre CallerCallback . Si l’adresse Teredo n’est pas disponible ou est à l’état stable et que les autres adresses IP unicast sont dans un état stable, la fonction dans le paramètre CallerCallback n’est jamais appelée.

La fonction de rappel spécifiée dans le paramètre CallerCallback doit être définie comme une fonction de type VOID. Les paramètres passés à la fonction de rappel sont les suivants :

Paramètre	Description
IN PVOID CallerContext	Paramètre CallerContext passé à la fonction NotifyStableUnicastIpAddressTable lors de l’inscription aux notifications.
IN PMIB_UNICASTIPADDRESS_TABLE AddressTable	Pointeur vers un MIB_UNICASTIPADDRESS_TABLE contenant la table d’adresses IP de unidiffusion stable sur l’ordinateur local.

La fonction de rappel spécifiée dans le paramètre CallerCallback doit être implémentée dans le même processus que l’application appelant la fonction NotifyStableUnicastIpAddressTable . Si la fonction de rappel se trouve dans une DLL distincte, la DLL doit être chargée avant d’appeler la fonction NotifyStableUnicastIpAddressTable pour s’inscrire aux notifications de modification.

La mémoire pointée par le paramètre AddressTable utilisé dans une indication de rappel est allouée par le système d’exploitation. Une application qui reçoit une notification doit libérer la mémoire pointée par le paramètre AddressTable à l’aide de la fonction FreeMibTable lorsque les informations MIB_UNICASTIPADDRESS_TABLE ne sont plus nécessaires.

Une fois que la fonction NotifyStableUnicastIpAddressTable est appelée pour s’inscrire aux notifications de modification, ces notifications continuent d’être envoyées jusqu’à ce que l’application ne soit pas inscrite pour les notifications de modification ou que l’application se termine. Si l’application se termine, le système désinscrira automatiquement toute inscription pour les notifications de modification. Il est toujours recommandé qu’une application désinscrire explicitement toutes les notifications de modification avant qu’elle ne se termine.

Toute inscription pour les notifications de modification ne persiste pas si le système est arrêté ou redémarré.

Pour désinscrire les notifications de modification, appelez la fonction CancelMibChangeNotify2 en passant le paramètre NotificationHandle retourné par NotifyStableUnicastIpAddressTable.

Une application ne peut pas appeler la fonction CancelMibChangeNotify2 à partir du contexte du thread qui exécute actuellement la fonction de rappel de notification pour le même paramètre NotificationHandle . Sinon, le thread qui exécute ce rappel entraîne un blocage. Par conséquent, la fonction CancelMibChangeNotify2 ne doit pas être appelée directement dans le cadre de la routine de rappel de notification. Dans une situation plus générale, un thread qui exécute la fonction CancelMibChangeNotify2 ne peut pas posséder une ressource sur laquelle le thread qui exécute une opération de rappel de notification attendrait, car cela entraînerait un blocage similaire. La fonction CancelMibChangeNotify2 doit être appelée à partir d’un autre thread, sur lequel le thread qui reçoit le rappel de notification n’a pas de dépendances.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista [applications de bureau \| applications UWP]
Serveur minimal pris en charge	Windows Server 2008 [applications de bureau \| applications UWP]
Plateforme cible	Windows
En-tête	netioapi.h (inclure Iphlpapi.h)
Bibliothèque	Iphlpapi.lib
DLL	Iphlpapi.dll