Fonction RtlIpv4AddressToStringExW (ip2string.h)

Article
03/04/2024

La fonction RtlIpv4AddressToStringEx convertit une adresse IPv4 et un numéro de port en chaîne au format Internet standard.

Syntaxe

NTSYSAPI NTSTATUS RtlIpv4AddressToStringExW(
  [in]      const in_addr *Address,
  [in]      USHORT        Port,
  [out]     PWSTR         AddressString,
  [in, out] PULONG        AddressStringLength
);

Paramètres

[in] Address

Adresse IPv4 dans l’ordre d’octet réseau.

[in] Port

Numéro de port au format d’ordre des octets réseau. Ce paramètre est facultatif.

[out] AddressString

Pointeur vers la mémoire tampon pour recevoir la représentation de chaîne terminée par null de l’adresse et du port IPv4. Cette mémoire tampon doit être suffisamment grande pour contenir au moins INET_ADDRSTRLEN caractères. La valeur INET_ADDRSTRLEN est définie dans le fichier d’en-tête Ws2ipdef.h .

[in, out] AddressStringLength

En entrée, le nombre de caractères qui s’intègrent dans la mémoire tampon pointée vers le paramètre AddressString , y compris le point de terminaison NULL. Sur la sortie, ce paramètre contient le nombre de caractères réellement écrits dans la mémoire tampon pointée par le paramètre AddressString .

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 un pointeur NULL est passé dans le paramètre AddressString ou AddressStringLength . Cette erreur est également retournée si la longueur de la mémoire tampon pointée par le paramètre AddressString n’est pas suffisamment grande pour recevoir la représentation sous forme de chaîne de l’adresse et du port IPv4.
Autres	Utilisez FormatMessage pour obtenir la chaîne de message pour l’erreur retournée.

Code de retour

Description

STATUS_INVALID_PARAMETER

Un paramètre non valide a été transmis à la fonction. Cette erreur est retournée si un pointeur NULL est passé dans le paramètre AddressString ou AddressStringLength . Cette erreur est également retournée si la longueur de la mémoire tampon pointée par le paramètre AddressString n’est pas suffisamment grande pour recevoir la représentation sous forme de chaîne de l’adresse et du port IPv4.

Autres

Utilisez FormatMessage pour obtenir la chaîne de message pour l’erreur retournée.

Remarques

La fonction RtlIpv4AddressToStringEx permet de convertir une adresse IPv4 et un numéro de port en représentation sous forme de chaîne de l’adresse IPv4 au format décimal en pointillés Internet suivi d’un caractère deux-points et d’une représentation sous forme de chaîne du port.

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

Si la longueur de la mémoire tampon pointée par le paramètre AddressString n’est pas assez grande pour recevoir la représentation sous forme de chaîne de l’adresse et du port IPv4, RtlIpv4AddressToStringEx retourne ERROR_INVALID_PARAMETER et définit le paramètre AddressStringLength sur la longueur de mémoire tampon requise.

Lorsque unicode ou _UNICODE est défini, RtlIpv4AddressToStringEx est défini sur RtlIpv4AddressToStringExW, la version Unicode de cette fonction. Le paramètre AddressString est défini sur le type de données PWSTR.

Lorsque UNICODE et _UNICODE ne sont pas définis, RtlIpv4AddressToStringEx est défini sur RtlIpv4AddressToStringExA, la version ANSI de cette fonction. Le paramètre AddressString est défini sur le type de données PSTR.

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

Une bibliothèque d’importation contenant la fonction RtlIpv4AddressToStringEx n’est pas incluse dans le Microsoft Kit de développement logiciel Windows (Kit SDK Windows) (SDK) publié pour Windows Vista. La fonction RtlIpv4AddressToStringEx 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.

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