Fonction RtlIpv4StringToAddressExW (ip2string.h)

Article
02/05/2024

La fonction RtlIpv4StringToAddressEx convertit une représentation sous forme de chaîne d’une adresse IPv4 et d’un numéro de port en adresse et port IPv4 binaires.

Syntaxe

NTSYSAPI NTSTATUS RtlIpv4StringToAddressExW(
  [in]  PCWSTR  AddressString,
  [in]  BOOLEAN Strict,
  [out] in_addr *Address,
  [out] PUSHORT Port
);

Paramètres

[in] AddressString

Pointeur vers une mémoire tampon contenant la représentation sous forme de chaîne terminée par null de l’adresse IPv4 suivie d’une représentation facultative des deux-points et de la chaîne d’un numéro de port.

[in] Strict

Valeur qui indique si la chaîne doit être une adresse IPv4 représentée en notation décimale à quatre parties stricte. Si ce paramètre a la valeur TRUE, la chaîne doit être décimal en pointillés avec quatre parties. Si ce paramètre a la valeur FALSE, quatre formes sont autorisées pour la représentation sous forme de chaîne de l’adresse Ipv4, avec une notation décimale, octale ou hexadécimale. Pour plus d'informations, consultez la section Notes.

[out] Address

Pointeur dans lequel la représentation binaire de l’adresse IPv4 doit être stockée. L’adresse IPv4 est stockée dans l’ordre des octets réseau.

[out] Port

Pointeur dans lequel la représentation binaire du numéro de port doit être stockée. Le numéro de port est retourné dans l’ordre d’octets réseau. Si aucun port n’a été spécifié dans la chaîne pointée par le paramètre AddressString , le paramètre Port est défini sur zéro.

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 le paramètre Strict a été défini sur TRUE, mais que la chaîne pointée par le paramètre AddressString ne contenait pas de représentation de chaîne décimale en quatre parties d’une adresse IPv4. Cette erreur est également retournée si la chaîne pointée par le paramètre AddressString ne contient pas une représentation sous forme de chaîne appropriée d’une adresse IPv4. 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.

Code de retour

Description

STATUS_INVALID_PARAMETER

Un paramètre non valide a été transmis à la fonction. Cette erreur est retournée si le paramètre Strict a été défini sur TRUE, mais que la chaîne pointée par le paramètre AddressString ne contenait pas de représentation de chaîne décimale en quatre parties d’une adresse IPv4. Cette erreur est également retournée si la chaîne pointée par le paramètre AddressString ne contient pas une représentation sous forme de chaîne appropriée d’une adresse IPv4.

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 RtlIpv4StringToAddressEx permet de convertir une représentation sous forme de chaîne de l’adresse IPv4 et du numéro de port en adresse IPv4 binaire et en numéro de port. L’adresse IPv4 est retournée dans l’ordre réseau (octets classés de gauche à droite). Le numéro de port est retourné dans l’ordre réseau.

RtlIpv4StringToAddressEx 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.

Si le paramètre Strict a la valeur TRUE, la chaîne pointée par le paramètre AddressString doit être en notation décimale stricte. Ce format strict nécessite que quatre parties soient spécifiées. Chaque partie est interprétée comme un octet décimal de données et affectée, de gauche à droite, aux quatre octets d’une adresse IPv4.

Lorsque le paramètre Strict a la valeur FALSE, la chaîne pointée par le paramètre AddressString peut être dans l’un des différents formats possibles. Lorsque la mémoire tampon pointée vers le paramètre AddressString contient une chaîne d’adresse en trois parties, la dernière partie est interprétée comme une quantité de 16 bits et placée dans les deux octets les plus à droite de l’adresse réseau. Cela rend le format d’adresse en trois parties pratique pour spécifier des adresses réseau de classe B comme « 128.net.host ». Lorsque la mémoire tampon pointée vers le paramètre AddressString contient une chaîne d’adresse en deux parties, la dernière partie est interprétée comme une quantité 24 bits et placée dans le plus à droite des trois octets de l’adresse réseau. Cela rend le format d’adresse en deux parties pratique pour spécifier des adresses réseau de classe A comme « net.host ». Lorsque la mémoire tampon pointée vers le paramètre AddressString ne contient qu’une chaîne d’adresse en une seule partie, la valeur est stockée directement dans l’adresse réseau sans aucun réarrangement d’octets.

La mémoire tampon vers laquelle pointe le paramètre AddressString peut contenir la chaîne d’adresse IPv4 suivie d’un signe deux-points facultatif et de la représentation sous forme de chaîne d’un numéro de port. Si une chaîne de numéro de port est incluse dans la mémoire tampon pointée vers le paramètre AddressString , la représentation binaire du numéro de port est retournée dans le paramètre Port . Si la mémoire tampon pointée par le paramètre AddressString ne contient pas de numéro de port, un zéro est retourné dans le paramètre Port .

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

Lorsque unicode et _UNICODE ne sont pas définis, RtlIpv4StringToAddressEx est défini sur RtlIpv4StringToAddressExA, la version ANSI de cette fonction. Le paramètre AddressString est défini sur le type de données PCSTR.

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

Une bibliothèque d’importation contenant la fonction RtlIpv4StringToAddressEx n’est pas incluse dans le Microsoft Kit de développement logiciel Windows (Kit SDK Windows) (SDK) publié pour Windows Vista. La fonction RtlIpv4StringToAddressEx 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 (include Mstcpip.h)
Bibliothèque	ntdll.lib
DLL	ntdll.dll