Funzione RtlIpv6StringToAddressA (ip2string.h)

Articolo
11/20/2024

La funzione RtlIpv6StringToAddress converte una rappresentazione di stringa di un indirizzo IPv6 in un indirizzo IPv6 binario.

Sintassi

NTSYSAPI NTSTATUS RtlIpv6StringToAddressA(
  [in]  PCSTR    S,
  [out] PCSTR    *Terminator,
  [out] in6_addr *Addr
);

Parametri

[in] S

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

[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 IPv6.

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 la stringa a cui punta il parametro S non contiene una rappresentazione di stringa corretta di un indirizzo IPv6. 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 RtlIpv6StringToAddress viene usata per convertire una rappresentazione di stringa dell'indirizzo IPv6 in un indirizzo IPv6 restituito in ordine di rete (byte ordinati da sinistra a destra).

RtlIpv6StringToAddress è 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.

La stringa a cui punta il parametro S deve essere rappresentata nel formato per una stringa di indirizzo IPv6. La rappresentazione di stringa di base di un indirizzo IPv6 è costituita da 8 numeri esadecimali separati da due punti. Una stringa di numeri zero consecutivi può essere sostituita con due due punti. Nella rappresentazione di stringa dell'indirizzo IPv6 può essere presente un solo doppio due punti. Gli ultimi 32 bit possono essere rappresentati nella notazione IPv4 punteggiata-ottetto se l'indirizzo è un indirizzo compatibile con IPv4, un indirizzo IPv4 mappato a IPv6 o un indirizzo ISATAP. Per altre informazioni, vedere la sezione 5 di RFC 5942 pubblicata da IETF.

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 e un indirizzo IP più informazioni aggiuntive alla funzione RtlIpv6StringToAddress e quindi analizzare le informazioni rimanenti.

Nota Alcuni indirizzi IPv6 in formato non valido (::::, ad esempio) iniziano con un indirizzo IPv6 valido. La funzione RtlIpv6StringToAddress restituirà esito positivo, dopo aver analizzato la parte valida dell'indirizzo IPv6 come due punti (::). Il carattere di terminazione punta quindi al terzo punto. Per verificare che l'intera stringa passata sia un indirizzo IPv6 valido, è necessario assicurarsi che il carattere di terminazione punti al carattere corretto. Se il parametro S contiene solo un indirizzo IPv6, il carattere di terminazione deve puntare al carattere NULL alla fine della stringa.

Quando viene definito UNICODE o _UNICODE, RtlIpv6StringToAddress viene definito per RtlIpv6StringToAddressW, la versione Unicode di questa funzione. I parametri E Terminator sono definiti per il tipo di dati PCWSTR.

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

La struttura IN6_ADDR è definita nel file di intestazione In6addr.h.

Una libreria di importazione contenente il funzione di RtlIpv6StringToAddress non è inclusa nel Microsoft Windows Software Development Kit (SDK) rilasciato per Windows Vista. La funzione RtlIpv6StringToAddress è 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 RtlIpv6StringToAddress 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