Funzione RtlIpv4StringToAddressA (ip2string.h)

Articolo
11/20/2024

La funzione RtlIpv4StringToAddress converte una rappresentazione di stringa di un indirizzo IPv4 in un indirizzo IPv4 binario.

Sintassi

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

Parametri

[in] S

Puntatore a un buffer contenente il NULLrappresentazione di stringa con terminazione dell'indirizzo IPv4.

[in] Strict

Valore che indica se la stringa deve essere un indirizzo IPv4 rappresentato in notazione decimale a quattro parti rigorosa. Se questo parametro è TRUE, la stringa deve essere punteggiata con quattro parti. Se questo parametro è FALSE, sono consentite quattro forme possibili, con notazione decimale, ottale o esadecimale. Per informazioni dettagliate, vedere la sezione Osservazioni.

[out] Terminator

Parametro che riceve un puntatore al carattere che ha terminato la stringa convertita. Può essere usato dal chiamante per estrarre altre informazioni dalla stringa.

[out] Addr

Puntatore in cui deve essere archiviata la rappresentazione binaria dell'indirizzo IPv4.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è STATUS_SUCCESS.

Se la funzione ha esito negativo, il valore restituito è uno dei codici di errore seguenti.

Codice restituito	Descrizione
STATUS_INVALID_PARAMETER	Alla funzione è stato passato un parametro non valido. Questo errore viene restituito se il parametro Strict è stato impostato su TRUE, ma la stringa a cui punta il parametro S non contiene una rappresentazione di stringa decimale punteggiata in quattro parti di un indirizzo IPv4. Questo errore viene restituito anche se la stringa a cui punta il parametro S non contiene una rappresentazione di stringa corretta di un indirizzo IPv4. Questo codice di errore viene definito nel file di intestazione Ntstatus.h.
Altro	Usare FormatMessage per ottenere la stringa del messaggio per l'errore restituito.

Codice restituito

Descrizione

STATUS_INVALID_PARAMETER

Alla funzione è stato passato un parametro non valido. Questo errore viene restituito se il parametro Strict è stato impostato su TRUE, ma la stringa a cui punta il parametro S non contiene una rappresentazione di stringa decimale punteggiata in quattro parti di un indirizzo IPv4. Questo errore viene restituito anche se la stringa a cui punta il parametro S non contiene una rappresentazione di stringa corretta di un indirizzo IPv4.

Questo codice di errore viene definito nel file di intestazione Ntstatus.h.

Altro

Usare FormatMessage per ottenere la stringa del messaggio per l'errore restituito.

Osservazioni

La funzione RtlIpv4StringToAddress viene usata per convertire una rappresentazione di stringa dell'indirizzo IPv4 in un indirizzo IPv4 restituito in ordine di rete (byte ordinati da sinistra a destra).

RtlIpv4StringToAddress è una funzione utile che non richiede il caricamento della DLL di Windows Sockets per accedere a una funzione fornita in Windows Sockets per eseguire la conversione della stringa nell'indirizzo IP.

Se il parametro Strict è impostato su TRUE, la stringa a cui punta il parametro S deve essere in notazione decimale con punti rigorosa. Questo formato rigido richiede che siano specificate quattro parti. Ogni parte viene interpretata come un byte decimale di dati e assegnata, da sinistra a destra, ai quattro byte di un indirizzo IPv4.

Quando il parametro strict è impostato su FALSE, la stringa a cui punta parametro S può trovarsi in uno dei diversi formati possibili. Quando il buffer a cui punta parametro S contiene una stringa di indirizzi in tre parti, l'ultima parte viene interpretata come una quantità a 16 bit e inserita nella maggior parte dei due byte destro dell'indirizzo di rete. In questo modo il formato degli indirizzi in tre parti risulta utile per specificare gli indirizzi di rete della classe B come "128.net.host". Quando il buffer a cui punta parametro S contiene una stringa di indirizzo in due parti, l'ultima parte viene interpretata come una quantità a 24 bit e posizionata nella parte più a destra dei tre byte dell'indirizzo di rete. In questo modo il formato dell'indirizzo in due parti risulta utile per specificare gli indirizzi di rete classe A come "net.host". Quando il buffer a cui punta parametro S contiene solo una stringa di indirizzo in una parte, il valore viene archiviato direttamente nell'indirizzo di rete senza ridisporre alcun byte.

In caso di esito positivo, il parametro Terminator punta al carattere che ha terminato la stringa che è stata convertita. In questo modo un'applicazione può passare una stringa contenente un indirizzo IP e informazioni aggiuntive alla funzione RtlIpv4StringToAddress e quindi analizzare le informazioni rimanenti.

Quando viene definito UNICODE o _UNICODE, RtlIpv4StringToAddress viene definito per RtlIpv4StringToAddressW, la versione Unicode di questa funzione. Il parametro S viene definito per il tipo di dati PCWSTR e il parametro terminatore è definito al tipo di dati LPCWSTR.

Quando sia UNICODE che _UNICODE non sono definiti, RtlIpv4StringToAddress viene definito per RtlIpv4StringToAddressA, la versione ANSI di questa funzione. I parametri S e terminatore vengono definiti per il tipo di dati PCSTR.

La struttura IN_ADDR è definita nel file di intestazione Inaddr. h.

Una libreria di importazione contenente la funzione di RtlIpv4StringToAddress non è inclusa nella versione di Microsoft Windows Software Development Kit (SDK) per Windows Vista. La funzione RtlIpv4StringToAddress è inclusa nella libreria di importazione ntdll.lib inclusa in Windows Driver Kit (WDK). Un'applicazione può anche usare le funzioni GetModuleHandle e GetProcAddress per recuperare il puntatore di funzione dal Ntdll.dll e chiamare questa funzione.

Nota

L'intestazione ip2string.h definisce RtlIpv4StringToAddress come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows Vista [app desktop \| App UWP]
server minimo supportato	Windows Server 2008 [app desktop \| App UWP]
piattaforma di destinazione	Finestre
intestazione	ip2string.h (include Mstcpip.h, Ip2string.h)
libreria	ntdll.lib
dll	ntdll.dll