Fonction RtlIpv6StringToAddressW (ip2string.h)

Article
03/06/2024

La fonction RtlIpv6StringToAddress convertit une représentation sous forme de chaîne d’une adresse IPv6 en adresse IPv6 binaire.

Syntaxe

NTSYSAPI NTSTATUS RtlIpv6StringToAddressW(
  [in]  PCWSTR   S,
  [out] PCWSTR   *Terminator,
  [out] in6_addr *Addr
);

Paramètres

[in] S

Pointeur vers une mémoire tampon contenant la représentation sous forme de chaîne terminée par null de l’adresse IPv6.

[out] Terminator

Paramètre qui reçoit un pointeur vers le caractère qui a terminé la chaîne convertie. Cela peut être utilisé par l’appelant pour extraire plus d’informations à partir de la chaîne.

[out] Addr

Pointeur dans lequel la représentation binaire de l’adresse IPv6 doit être stockée.

Valeur retournée

Si la fonction réussit, la valeur de retour est STATUS_SUCCESS.

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

Code de retour	Description
STATUS_INVALID_PARAMETER	Un paramètre non valide a été transmis à la fonction. Cette erreur est retournée si la chaîne pointée par le paramètre S ne contient pas une représentation sous forme de chaîne appropriée d’une adresse IPv6. Ce code d’erreur est défini dans le fichier d’en-tête Ntstatus.h.
Autres	Utilisez FormatMessage pour obtenir la chaîne de message de l’erreur retournée.

Remarques

La fonction RtlIpv6StringToAddress permet de convertir une représentation sous forme de chaîne de l’adresse IPv6 en adresse IPv6 retournée dans l’ordre réseau (octets classés de gauche à droite).

RtlIpv6StringToAddress est une fonction pratique qui ne nécessite pas que la DLL Windows Sockets soit chargée pour accéder à une fonction fournie dans Windows Sockets pour effectuer la conversion de chaîne en adresse IP.

La chaîne pointée par le paramètre S doit être représentée sous la forme d’une chaîne d’adresse IPv6. La représentation sous forme de chaîne de base d’une adresse IPv6 se compose de 8 nombres hexadécimaux séparés par des points-virgules. Une chaîne de nombres zéro consécutifs peut être remplacée par un deux-points. Il ne peut y avoir qu’un seul signe deux-points dans la représentation sous forme de chaîne de l’adresse IPv6. Les 32 derniers bits peuvent être représentés en notation d’octets pointillés de style IPv4 si l’adresse est une adresse compatible IPv4, une adresse IPv6 mappée IPv4 ou une adresse ISATAP. Pour plus d’informations, consultez la section 5 de la RFC 5942 publiée par l’IETF.

En cas de réussite, le paramètre Terminator pointe vers le caractère qui a terminé la chaîne convertie. Cela permet à une application de passer une chaîne qui contient et l’adresse IP ainsi que des informations supplémentaires à la fonction RtlIpv6StringToAddress , puis d’analyser les informations restantes.

Note Certaines adresses IPv6 incorrectes ( ::::, par exemple) commencent par une adresse IPv6 valide. La fonction RtlIpv6StringToAddress retourne la réussite, après avoir analysé la partie valide de l’adresse IPv6 en tant que deux-points ( ::). Le terminateur pointe ensuite vers le troisième signe deux-points. Pour vérifier que l’intégralité de la chaîne passée est une adresse IPv6 valide, vous devez vous assurer que l’indicateur de fin pointe vers le caractère correct. Si le paramètre S contient uniquement une adresse IPv6, l’indicateur de fin doit pointer vers le caractère NULL à la fin de la chaîne.

Lorsque unicode ou _UNICODE est défini, RtlIpv6StringToAddress est défini sur RtlIpv6StringToAddressW, la version Unicode de cette fonction. Les paramètres S et Terminator sont définis sur le type de données PCWSTR.

Lorsque unicode et _UNICODE ne sont pas définis, RtlIpv6StringToAddress est défini sur RtlIpv6StringToAddressA, la version ANSI de cette fonction. Les paramètres S et Terminator sont définis sur le type de données PCSTR.

La structure IN6_ADDR est définie dans le fichier d’en-tête In6addr.h.

Une bibliothèque d’importation contenant la fonction RtlIpv6StringToAddress n’est pas incluse dans le Microsoft Kit de développement logiciel Windows (Kit SDK Windows) (SDK) publié pour Windows Vista. La fonction RtlIpv6StringToAddress est incluse dans la bibliothèque d’importation Ntdll.lib incluse dans le Kit de pilotes Windows (WDK). Une application peut également utiliser les fonctions GetModuleHandle et GetProcAddress pour récupérer le pointeur de fonction à partir du Ntdll.dll et appeler cette fonction.

Notes

L’en-tête ip2string.h définit RtlIpv6StringToAddress en tant qu’alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. La combinaison de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

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	ip2string.h (include Mstcpip.h, Ip2string.h)
Bibliothèque	ntdll.lib
DLL	ntdll.dll