InetNtopW, fonction (ws2tcpip.h)

Article
03/04/2024

La fonction InetNtop convertit une adresse réseau Internet IPv4 ou IPv6 en chaîne au format Internet standard. La version ANSI de cette fonction est inet_ntop.

Syntaxe

PCWSTR WSAAPI InetNtopW(
  [in]  INT        Family,
  [in]  const VOID *pAddr,
  [out] PWSTR      pStringBuf,
  [in]  size_t     StringBufSize
);

Paramètres

[in] Family

Famille d’adresses.

Les valeurs possibles pour la famille d’adresses 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. Notez que les valeurs de la famille d’adresses AF_ et des constantes de famille de protocole PF_ sont identiques (par exemple , AF_INET et PF_INET), de sorte que l’une ou l’autre constante peut être utilisée.

Les valeurs actuellement prises en charge sont AF_INET et AF_INET6.

Valeur	Signification
AF_INET 2	Famille d’adresses IPv4 (Internet Protocol version 4). Lorsque ce paramètre est spécifié, cette fonction retourne une chaîne d’adresse IPv4.
AF_INET6 23	Famille d’adresses IPv6 (Internet Protocol version 6). Lorsque ce paramètre est spécifié, cette fonction retourne une chaîne d’adresse IPv6.

[in] pAddr

Pointeur vers l’adresse IP dans l’octet réseau à convertir en chaîne.

Lorsque le paramètre Family est AF_INET, le paramètre pAddr doit pointer vers une structure IN_ADDR avec l’adresse IPv4 à convertir.

Lorsque le paramètre Family est AF_INET6, le paramètre pAddr doit pointer vers une structure IN6_ADDR avec l’adresse IPv6 à convertir.

[out] pStringBuf

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

Pour une adresse IPv4, cette mémoire tampon doit être suffisamment grande pour contenir au moins 16 caractères.

Pour une adresse IPv6, cette mémoire tampon doit être suffisamment grande pour contenir au moins 46 caractères.

[in] StringBufSize

Lors de l’entrée, la longueur, en caractères, de la mémoire tampon pointée vers le paramètre pStringBuf .

Valeur retournée

Si aucune erreur ne se produit, la fonction InetNtop retourne un pointeur vers une mémoire tampon contenant la représentation sous forme de chaîne de l’adresse IP au format standard.

Sinon, une valeur NULL est retournée et un code d’erreur spécifique peut être récupéré en appelant le
WSAGetLastError pour obtenir des informations d’erreur étendues.

Si la fonction échoue, le code d’erreur étendu retourné par WSAGetLastError peut être l’une des valeurs suivantes.

Code d'erreur	Signification
WSAEAFNOSUPPORT	La famille d’adresses spécifiée dans le paramètre Family n’est pas prise en charge. Cette erreur est retournée si le paramètre Family spécifié n’a pas été AF_INET ou AF_INET6.
ERROR_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 pStringBuf ou si le paramètre StringBufSize est égal à zéro. Cette erreur est également retournée si la longueur de la mémoire tampon pointée par le paramètre pStringBuf n’est pas suffisamment grande pour recevoir la représentation sous forme de chaîne de l’adresse IP.

Code d'erreur

Signification

WSAEAFNOSUPPORT

La famille d’adresses spécifiée dans le paramètre Family n’est pas prise en charge. Cette erreur est retournée si le paramètre Family spécifié n’a pas été AF_INET ou AF_INET6.

ERROR_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 pStringBuf ou si le paramètre StringBufSize est égal à zéro. Cette erreur est également retournée si la longueur de la mémoire tampon pointée par le paramètre pStringBuf n’est pas suffisamment grande pour recevoir la représentation sous forme de chaîne de l’adresse IP.

Remarques

La fonction InetNtop est prise en charge sur Windows Vista et versions ultérieures.

La fonction InetNtop fournit une traduction d’adresse en chaîne indépendante du protocole. La fonction InetNtop prend une structure d’adresse Internet spécifiée par le paramètre pAddr et retourne une chaîne terminée par NULL qui représente l’adresse IP. Alors que la fonction inet_ntoa fonctionne uniquement avec les adresses IPv4, la fonction InetNtop fonctionne avec les adresses IPv4 ou IPv6.

La version ANSI de cette fonction est inet_ntop comme défini dans RFC 2553. Pour plus d’informations, consultez RFC 2553 disponible sur le site web de l’IETF.

La fonction InetNtop ne nécessite pas que la DLL Windows Sockets soit chargée pour effectuer une conversion d’adresse IP en chaîne.

Si le paramètre Family spécifié est AF_INET, le paramètre pAddr doit pointer vers une structure IN_ADDR avec l’adresse IPv4 à convertir. La chaîne d’adresse retournée dans la mémoire tampon vers laquelle pointe le paramètre pStringBuf est en notation décimale en pointillés comme dans « 192.168.16.0 », un exemple d’adresse IPv4 en notation décimale en pointillés.

Si le paramètre Family spécifié est AF_INET6, le paramètre pAddr doit pointer vers une structure IN6_ADDR avec l’adresse IPv6 à convertir. La chaîne d’adresse retournée dans la mémoire tampon vers laquelle pointe le paramètre pStringBuf est au format internet standard. La représentation sous forme de chaîne de base se compose de 8 nombres hexadécimaux séparés par des deux-points. Une chaîne de nombres zéro consécutifs est remplacée par un signe 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 sont représentés en notation d’octets pointillés de style IPv4 si l’adresse est une adresse compatible IPv4.

Si la longueur de la mémoire tampon vers laquelle pointe le paramètre pStringBuf n’est pas suffisamment grande pour recevoir la représentation sous forme de chaîne de l’adresse IP, InetNtop retourne ERROR_INVALID_PARAMETER.

Lorsque unicode ou _UNICODE est défini, InetNtop est défini sur InetNtopW, la version Unicode de cette fonction. Le paramètre pStringBuf est défini sur le type de données PSTR .

Lorsque UNICODE ou _UNICODE n’est pas défini, InetNtop est défini sur InetNtopA, la version ANSI de cette fonction. La version ANSI de cette fonction est toujours définie comme inet_ntop. Le paramètre pStringBuf est défini sur le type de données PWSTR .

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

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

Sur Windows Vista et versions ultérieures, les fonctions RtlIpv4AddressToString et RtlIpv4AddressToStringEx peuvent être utilisées pour convertir une adresse IPv4 représentée sous la forme d’une structure IN_ADDR en une représentation sous forme de chaîne d’une adresse IPv4 dans la notation décimale standard d’Internet. Sur Windows Vista et versions ultérieures, les fonctions RtlIpv6AddressToString et RtlIpv6AddressToStringEx peuvent être utilisées pour convertir une adresse IPv6 représentée sous la forme d’une structure IN6_ADDR en une représentation sous forme de chaîne d’une adresse IPv6. La fonction RtlIpv6AddressToStringEx est plus flexible, car elle convertit également une adresse IPv6, un ID d’étendue et un port en chaîne IPv6 au format standard.

Windows 8.1 et Windows Server 2012 R2 : la fonction InetNtopW est prise en charge pour les applications du Windows Store sur Windows 8.1, Windows Server 2012 R2 et versions ultérieures.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 8.1, 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	ws2tcpip.h
Bibliothèque	Ws2_32.lib
DLL	Ws2_32.dll