Funzione RtlIpv4StringToAddressA (ip2string.h)

Articolo
08/24/2023

La funzione RtlIpv4StringToAddress converte una rappresentazione 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 la rappresentazione di stringa con terminazione NULL dell'indirizzo IPv4.

[in] Strict

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

[out] Terminator

Parametro che riceve un puntatore al carattere che ha terminato la stringa convertita. Questa operazione può essere usata 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	Un parametro non valido è stato passato alla funzione. Questo errore viene restituito se il parametro Strict è stato impostato su TRUE, ma la stringa puntata dal parametro S non contiene una rappresentazione decimale punteggiata di quattro parti di un indirizzo IPv4. Questo errore viene restituito anche se la stringa puntata dal parametro S non contiene una rappresentazione stringa appropriata di un indirizzo IPv4. Questo codice di errore viene definito nel file di intestazione Ntstatus.h.
Altri	Usare FormatMessage per ottenere la stringa di messaggio per l'errore restituito.

Codice restituito

Descrizione

STATUS_INVALID_PARAMETER

Un parametro non valido è stato passato alla funzione. Questo errore viene restituito se il parametro Strict è stato impostato su TRUE, ma la stringa puntata dal parametro S non contiene una rappresentazione decimale punteggiata di quattro parti di un indirizzo IPv4. Questo errore viene restituito anche se la stringa puntata dal parametro S non contiene una rappresentazione stringa appropriata di un indirizzo IPv4.

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

Altri

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

Commenti

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

RtlIpv4StringToAddress è una funzione di praticità che non richiede che la DLL di Windows Sockets venga caricata per accedere a una funzione fornita in Windows Sockets per eseguire la conversione della stringa all'indirizzo IP.

Se il parametro Strict è impostato su TRUE, la stringa puntata dal parametro S deve essere in notazione decimale rigorosa. Questo formato rigoroso richiede che siano specificate quattro parti. Ogni parte viene interpretata come 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 il parametro S può trovarsi in uno dei diversi formati possibili. Quando il buffer a cui punta da S parametro contiene una stringa di indirizzi a tre parti, l'ultima parte viene interpretata come quantità a 16 bit e inserita nella maggior parte dei due byte di destra dell'indirizzo di rete. Questo rende il formato di indirizzo a tre parti pratico per specificare gli indirizzi di rete di classe B come "128.net.host". Quando il buffer a cui punta il parametro S contiene una stringa di indirizzi a due parti, l'ultima parte viene interpretata come quantità a 24 bit e posizionata nella parte destra più di tre byte dell'indirizzo di rete. In questo modo, il formato dell'indirizzo di due parti consente di specificare gli indirizzi di rete di Classe A come "net.host". Quando il buffer a cui punta il parametro S contiene solo una stringa di indirizzi a una parte, il valore viene archiviato direttamente nell'indirizzo di rete senza alcuna ridisistribuzione di byte.

In caso di esito positivo, il parametro Terminator punta al carattere che ha terminato la stringa convertita. Ciò consente a un'applicazione di 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 in RtlIpv4StringToAddressW, la versione Unicode di questa funzione. Il parametro S viene definito per il tipo di dati PCWSTR e il parametro Terminator viene definito al tipo di dati LPCWSTR.

Quando sia UNICODE che _UNICODE non sono definiti, RtlIpv4StringToAddress viene definito in RtlIpv4StringToAddressA, la versione ANSI di questa funzione. I parametri S e Terminator sono 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 RtlIpv4StringToAddress non è inclusa nel Microsoft Windows Software Development Kit (SDK) rilasciato 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 della 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 preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.

Requisiti


Client minimo supportato	Windows Vista [app desktop \| App UWP]
Server minimo supportato	Windows Server 2008 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	ip2string.h (includere Mstcpip.h, Ip2string.h)
Libreria	ntdll.lib
DLL	ntdll.dll