Funzione RtlIpv4StringToAddressExW (ip2string.h)

Articolo
03/05/2024

La funzione RtlIpv4StringToAddressEx converte una rappresentazione stringa di un indirizzo IPv4 e un numero di porta in un indirizzo e una porta IPv4 binaria.

Sintassi

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

Parametri

[in] AddressString

Puntatore a un buffer contenente la rappresentazione stringa con terminazione NULL dell'indirizzo IPv4 seguito da due punti e una rappresentazione stringa facoltativa di un numero di porta.

[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, per la rappresentazione stringa dell'indirizzo Ipv4 è consentito uno dei quattro moduli, con notazione decimale, ottale o esadecimale. Vedere la sezione Osservazioni per informazioni dettagliate.

[out] Address

Puntatore in cui deve essere archiviata la rappresentazione binaria dell'indirizzo IPv4. L'indirizzo IPv4 viene archiviato nell'ordine di byte di rete.

[out] Port

Puntatore in cui deve essere archiviata la rappresentazione binaria del numero di porta. Il numero di porta viene restituito nell'ordine di byte di rete. Se non è stata specificata alcuna porta nella stringa a cui fa riferimento il parametro AddressString , il parametro Port è impostato su zero.

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 AddressString non contiene una rappresentazione di stringa decimale a quattro parti di un indirizzo IPv4. Questo errore viene restituito anche se la stringa puntata dal parametro AddressString 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 AddressString non contiene una rappresentazione di stringa decimale a quattro parti di un indirizzo IPv4. Questo errore viene restituito anche se la stringa puntata dal parametro AddressString 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 RtlIpv4StringToAddressEx viene usata per convertire una rappresentazione stringa dell'indirizzo E del numero di porta IPv4 in un indirizzo IPv4 binario e un numero di porta. L'indirizzo IPv4 viene restituito nell'ordine di rete (byte ordinati da sinistra a destra). Il numero di porta viene restituito nell'ordine di rete.

RtlIpv4StringToAddressEx è 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 AddressString 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 puntata dal parametro AddressString può trovarsi in uno dei diversi formati possibili. Quando il buffer a cui punta il parametro AddressString 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 AddressString 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 AddressString contiene solo una stringa di indirizzi a una parte, il valore viene archiviato direttamente nell'indirizzo di rete senza alcun byte riorganizzare.

Il buffer a cui punta il parametro AddressString può contenere la stringa di indirizzi IPv4 seguita da due punti facoltativi e la rappresentazione stringa di un numero di porta. Se una stringa di numero di porta è inclusa nel buffer a cui fa riferimento il parametro AddressString , la rappresentazione binaria del numero di porta viene restituita nel parametro Porta . Se il buffer a cui punta il parametro AddressString non contiene un numero di porta, viene restituito uno zero nel parametro Port .

Quando viene definito UNICODE o _UNICODE, RtlIpv4StringToAddressEx viene definito in RtlIpv4StringToAddressExW, la versione Unicode di questa funzione. Il parametro AddressString viene definito nel tipo di dati PCWSTR.

Quando sia UNICODE che _UNICODE non sono definiti, RtlIpv4StringToAddressEx viene definito in RtlIpv4StringToAddressExA, la versione ANSI di questa funzione. Il parametro AddressString è definito per il tipo di dati PCSTR.

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

Una libreria di importazione contenente la funzione RtlIpv4StringToAddressEx non è inclusa nella versione di Microsoft Windows Software Development Kit (Windows SDK) (SDK) per Windows Vista. La funzione RtlIpv4StringToAddressEx è 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.

Requisiti

Requisito	Valore
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)
Libreria	ntdll.lib
DLL	ntdll.dll