Fonction RtlIpv4StringToAddressA (ip2string.h)

Article
02/01/2024

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

Syntaxe

NTSYSAPI NTSTATUS RtlIpv4StringToAddressA(
  [in]  PCSTR   S,
  [in]  BOOLEAN Strict,
  [out] PCSTR   *Terminator,
  [out] in_addr *Addr
);

Paramètres

[in] S

Pointeur vers une mémoire tampon contenant la représentation de chaîne terminée par NULL de l’adresse IPv4.

[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 en pointillé-décimal avec quatre parties. Si ce paramètre a la valeur FALSE, l’une des quatre formes possibles est autorisée, avec une notation décimale, octale ou hexadécimale. Pour plus d'informations, consultez la section Notes.

[out] Terminator

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

[out] Addr

Pointeur dans lequel la représentation binaire de l’adresse IPv4 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 le paramètre Strict a été défini sur TRUE, mais que la chaîne pointée par le paramètre S ne contient pas de représentation de chaîne décimale en pointillés en quatre parties d’une adresse IPv4. Cette erreur est également retournée si la chaîne pointée vers par le paramètre S ne contient pas de 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 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 le paramètre Strict a été défini sur TRUE, mais que la chaîne pointée par le paramètre S ne contient pas de représentation de chaîne décimale en pointillés en quatre parties d’une adresse IPv4. Cette erreur est également retournée si la chaîne pointée vers par le paramètre S ne contient pas de 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 pour l’erreur retournée.

Remarques

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

RtlIpv4StringToAddress 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 de chaîne en adresse IP.

Si le paramètre Strict a la valeur TRUE, la chaîne pointée par le paramètre S 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 S peut se trouver dans l’un des différents formats possibles. Lorsque la mémoire tampon pointée vers le paramètre S contient une chaîne d’adresse en trois parties, la dernière partie est interprétée comme une quantité 16 bits et placée dans les deux octets à droite de l’adresse réseau. Cela rend le format d’adresse en trois parties pratique pour spécifier les adresses réseau de classe B comme « 128.net.host ». Lorsque la mémoire tampon pointée vers le paramètre S 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 les adresses réseau de classe A comme « net.host ». Lorsque la mémoire tampon pointée vers le paramètre S 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.

En cas de réussite, le paramètre Terminator pointe vers le caractère qui a mis fin à la chaîne convertie. Cela permet à une application de passer une chaîne contenant une adresse IP plus des informations supplémentaires à la fonction RtlIpv4StringToAddress , puis d’analyser les informations restantes.

Lorsque unicode ou _UNICODE est défini, RtlIpv4StringToAddress est défini sur RtlIpv4StringToAddressW, la version Unicode de cette fonction. Le paramètre S est défini sur le type de données PCWSTR et le paramètre Terminator est défini sur le type de données LPCWSTR.

Lorsque UNICODE et _UNICODE ne sont pas définis, RtlIpv4StringToAddress est défini sur RtlIpv4StringToAddressA, la version ANSI de cette fonction. Les paramètres S et Terminator sont définis pour 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 RtlIpv4StringToAddress n’est pas incluse dans le Kit de développement logiciel (SDK) Microsoft Windows publié pour Windows Vista. La fonction RtlIpv4StringToAddress 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 RtlIpv4StringToAddress comme un 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. Le mélange 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


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