CreateUnicastIpAddressEntry, fonction

Article
05/03/2024

La fonction CreateUnicastIpAddressEntry ajoute une nouvelle entrée d’adresse IP de monodiffusion sur l’ordinateur local.

Syntaxe

NETIOAPI_API CreateUnicastIpAddressEntry(
  _In_ const MIB_UNICASTIPADDRESS_ROW *Row
);

Paramètres

Ligne [in]
Pointeur vers une entrée de structure MIB_UNICASTIPADDRESS_ROW pour une entrée d’adresse IP de monodiffusion.

Valeur retournée

CreateUnicastIpAddressEntry retourne STATUS_SUCCESS si la fonction réussit.

Si la fonction échoue, CreateUnicastIpAddressEntry retourne l’un des codes d’erreur suivants :

Code de retour	Description
STATUS_INVALID_PARAMETER	Un paramètre non valide a été passé à la fonction. Cette erreur est retournée si un pointeur NULL est transmis dans le paramètre Row, le membre Address de la structure MIB_UNICASTIPADDRESS_ROW vers laquelle le paramètre Row pointe n’a pas été défini sur une adresse IPv4 ou IPv6 de monodiffusion valide, ou à la fois les membres InterfaceLuid et InterfaceIndex de la structure MIB_UNICASTIPADDRESS_ROW n’ont pas été spécifiés. Cette erreur est également retournée pour d’autres erreurs dans les valeurs définies pour les membres de la structure MIB_UNICASTIPADDRESS_ROW. Ces erreurs incluent les situations suivantes : Le membre ValidLifetime est inférieur au membre PreferredLifetime . Le membre PrefixOrigin est défini sur IpPrefixOriginUnchanged et le suffixeOrigin n’est pas défini sur IpSuffixOriginUnchanged. Le membre PrefixOrigin n’est pas défini sur IpPrefixOriginUnchanged et le suffixeOrigin est défini sur IpSuffixOriginUnchanged. Le membre PrefixOrigin n’est pas défini sur une valeur de l’énumération NL_PREFIX_ORIGIN . Le membre SuffixOrigin n’est pas défini sur une valeur de l’énumération NL_SUFFIX_ORIGIN. Le membre OnLinkPrefixLength est défini sur une valeur supérieure à la longueur de l’adresse IP, en bits (32 pour une adresse IPv4 unidiffusion ou 128 pour une adresse IPv6 unicast). Pour connaître les valeurs possibles des énumérations NL_PREFIX_ORIGIN et NL_SUFFIX_ORIGIN, consultez MIB_UNICASTIPADDRESS_ROW.
STATUS_NOT_FOUND	L’interface spécifiée n’a pas pu être trouvée. Cette erreur est retournée si la fonction ne trouve pas l’interface réseau spécifiée par le membre InterfaceLuid ou InterfaceIndex de la structure MIB_UNICASTIPADDRESS_ROW vers laquelle pointe le paramètre Row .
STATUS_NOT_SUPPORTED	La demande n'est pas prise en charge. Cette erreur est retournée si aucune pile IPv4 n’est située sur l’ordinateur local et qu’une adresse IPv4 a été spécifiée dans le membre Adresse de la structure MIB_UNICASTIPADDRESS_ROW vers laquelle pointe le paramètre Ligne , ou si aucune pile IPv6 n’est située sur l’ordinateur local et qu’une adresse IPv6 a été spécifiée dans le membre Address .
ERROR_OBJECT_ALREADY_EXISTS	L'objet existe déjà. Cette erreur est retournée si le membre Address de la structure MIB_UNICASTIPADDRESS_ROW vers laquelle le paramètre Row pointe est un doublon d’une adresse IP monodiffusion existante sur l’interface spécifiée par le membre InterfaceLuid ou InterfaceIndex de l’MIB_UNICASTIPADDRESS_ROW.
Autres	Utilisez la fonction FormatMessage pour obtenir la chaîne de message correspondant à l’erreur renvoyée.

Notes

Utilisez la fonction InitializeUnicastIpAddressEntry pour initialiser les membres d’une entrée de structure MIB_UNICASTIPADDRESS_ROW avec des valeurs par défaut. Un pilote peut ensuite modifier les membres de l’entrée MIB_UNICASTIPADDRESS_ROW qu’il souhaite modifier, puis appeler la fonction CreateUnicastIpAddressEntry .

Lors de l’entrée, votre pilote doit initialiser les membres suivants de la structure MIB_UNICASTIPADDRESS_ROW vers laquelle pointe le paramètre Row .

Adresse
Définissez sur une adresse et une famille IPv4 ou IPv6 monodiffusion valides.
InterfaceLuid ou InterfaceIndex
Ces membres sont utilisés dans l’ordre répertorié précédemment. Par conséquent, si InterfaceLuid est spécifié, ce membre est utilisé pour déterminer l’interface à laquelle ajouter l’adresse IP de monodiffusion. Si aucune valeur n’a été définie pour le membre InterfaceLuid (la valeur de ce membre a été définie à zéro), le membre InterfaceIndex est ensuite utilisé pour déterminer l’interface.

Si le membre OnLinkPrefixLength de la structure MIB_UNICASTIPADDRESS_ROW à laquelle pointe le paramètre Row est défini sur 255, CreateUnicastIpAddressEntry ajoute la nouvelle adresse IP unicast avec le membre OnLinkPrefixLength défini sur la longueur de l’adresse IP. Par conséquent, pour une adresse IPv4 monodiffusion, onLinkPrefixLength est défini sur 32 et onLinkPrefixLength est défini sur 128 pour une adresse IPv6 unicast. Si ce paramètre entraîne un masque de sous-réseau incorrect pour une adresse IPv4 ou le préfixe de lien incorrect pour une adresse IPv6, le pilote doit définir le membre OnLinkPrefixLength sur la valeur correcte avant d’appeler CreateUnicastIpAddressEntry.

Si une adresse IP unidiffusion est créée avec le membre OnLinkPrefixLength défini de manière incorrecte, votre pilote peut modifier l’adresse IP en appelant SetUnicastIpAddressEntry avec le membre OnLinkPrefixLength défini sur la valeur correcte.

Les membres DadState, ScopeId et CreationTimeStamp de la structure MIB_UNICASTIPADDRESS_ROW à laquelle le paramètre Row pointe sont ignorés lorsque la fonction CreateUnicastIpAddressEntry est appelée. Ces membres sont définis par la pile réseau. Le membre ScopeId est déterminé automatiquement par l’interface sur laquelle l’adresse est ajoutée.

La fonction CreateUnicastIpAddressEntry échoue si l’adresse IP de monodiffusion transmise dans le membre Adresse de la structure MIB_UNICASTIPADDRESS_ROW pointée par le paramètre Row est un doublon d’une adresse IP de monodiffusion existante sur l’interface. Notez que votre pilote peut ajouter une adresse IP de bouclage à une interface de bouclage uniquement à l’aide de la fonction CreateUnicastIpAddressEntry .

Adresse IP de monodiffusion transmise dans le membre Adresse de la structure MIB_UNICASTIPADDRESS_ROW vers laquelle le paramètre Row pointe n’est pas utilisable immédiatement. L’adresse IP est utilisable une fois le processus de détection d’adresse en double terminé. Le processus de détection d’adresses en double peut prendre plusieurs secondes, car les paquets IP doivent être envoyés et les réponses potentielles doivent être attendus. Pour IPv6, le processus de détection d’adresses en double prend généralement environ 1 seconde. Pour IPv4, le processus de détection d’adresses en double prend généralement environ 3 secondes.

Une fois qu’un pilote appelle la fonction CreateUnicastIpAddressEntry , il peut utiliser les méthodes suivantes pour déterminer si une adresse IP est toujours utilisable :

Utiliser l’interrogation et la fonction GetUnicastIpAddressEntry
Une fois l’appel à la fonction CreateUnicastIpAddressEntry retourné avec succès, suspendez pendant 1 à 3 secondes (selon qu’une adresse IPv6 ou IPv4 est en cours de création) pour permettre la réussite du processus de détection d’adresses de duplication. Ensuite, appelez GetUnicastIpAddressEntry pour récupérer la structure de MIB_UNICASTIPADDRESS_ROW mise à jour et examinez la valeur du membre DadState . Si la valeur du membre DadState est définie sur IpDadStatePreferred, l’adresse IP est désormais utilisable. Si la valeur du membre DadState est définie sur IpDadStateTentative, la détection d’adresses dupliquée n’a pas encore été terminée. Dans ce cas, appelez la fonction GetUnicastIpAddressEntry toutes les 0,5 secondes pendant que le membre DadState est toujours défini sur IpDadStateTentative . Si la valeur du membre DadState est retournée avec une valeur autre que IpDadStatePreferred ou IpDadStateTentative, la détection d’adresses en double a échoué et l’adresse IP n’est pas utilisable.
Appelez l’une des fonctions de notification NotifyXxx de l’assistance IP pour configurer une notification asynchrone lorsqu’une adresse change
Une fois l’appel à la fonction CreateUnicastIpAddressEntry retourné, appelez la fonction NotifyUnicastIpAddressChange pour inscrire le pilote afin d’être informé des modifications apportées aux adresses IP monodiffusion IPv6 ou IPv4, selon le type d’adresse IP en cours de création. Lorsqu’une notification est reçue pour l’adresse IP en cours de création, appelez la fonction GetUnicastIpAddressEntry pour récupérer le membre DadState . Si la valeur du membre DadState est définie sur IpDadStatePreferred, l’adresse IP est désormais utilisable. Si la valeur du membre DadState est définie sur IpDadStateTentative, la détection d’adresses dupliquée n’a pas encore été terminée et le pilote doit attendre les notifications futures. Si la valeur du membre DadState est retournée avec une valeur autre que IpDadStatePreferred ou IpDadStateTentative, la détection d’adresses en double a échoué et l’adresse IP n’est pas utilisable.

Si, pendant le processus de détection d’adresses en double, le média est déconnecté, puis reconnecté, le processus de détection d’adresse dupliqué est redémarré. Ainsi, le temps d’exécution du processus peut augmenter au-delà de la valeur standard de 1 seconde pour IPv6 ou 3 secondes pour IPv4.

Spécifications

Plateforme cible	Universal
Version	Disponible sous Windows Vista et les versions ultérieures du système d’exploitation Windows.
En-tête	Netioapi.h (inclure Netioapi.h)
Bibliothèque	Netio.lib
IRQL	< DISPATCH_LEVEL