Funzione RtlIpv6AddressToStringExW (ip2string.h)

Articolo
08/24/2023

La funzione RtlIpv6AddressToStringEx converte un indirizzo IPv6, un ID ambito e un numero di porta in una stringa.

Sintassi

NTSYSAPI NTSTATUS RtlIpv6AddressToStringExW(
  [in]      const in6_addr *Address,
  [in]      ULONG          ScopeId,
  [in]      USHORT         Port,
  [out]     PWSTR          AddressString,
  [in, out] PULONG         AddressStringLength
);

Parametri

[in] Address

Indirizzo IPv6 nell'ordine dei byte di rete.

[in] ScopeId

ID ambito dell'indirizzo IPv6 nell'ordine dei byte di rete. Questo parametro è facoltativo e,

[in] Port

Numero di porta nel formato dell'ordine dei byte di rete. Questo parametro è facoltativo e,

[out] AddressString

Puntatore al buffer per ricevere la rappresentazione di stringa con terminazione NULL dell'indirizzo IP, dell'ID ambito e della porta. Questo buffer deve essere sufficientemente grande da contenere almeno INET6_ADDRSTRLEN caratteri. Il valore INET6_ADDRSTRLEN è definito nel file di intestazione Ws2ipdef.h .

[in, out] AddressStringLength

In input, il numero di caratteri che rientrano nel buffer a cui punta il parametro AddressString , incluso il carattere di terminazione NULL. Nell'output questo parametro contiene il numero di caratteri effettivamente scritti nel buffer a cui punta il parametro AddressString .

Valore restituito

Se la funzione ha esito positivo, il valore restituito viene 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 un puntatore NULL viene passato nel parametro AddressString o AddressStringLength . Questo errore viene restituito anche se la lunghezza del buffer a cui punta il parametro AddressString non è sufficiente per ricevere la rappresentazione di stringa dell'indirizzo IPv6, dell'ID ambito e della porta.
Altri	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 un puntatore NULL viene passato nel parametro AddressString o AddressStringLength . Questo errore viene restituito anche se la lunghezza del buffer a cui punta il parametro AddressString non è sufficiente per ricevere la rappresentazione di stringa dell'indirizzo IPv6, dell'ID ambito e della porta.

Altri

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

Commenti

La funzione RtlIpv6AddressToStringEx viene usata per convertire un indirizzo IPv6, un ID ambito e un numero di porta nella rappresentazione di stringa dell'indirizzo IPv6 in formato Internet seguito da una rappresentazione di stringa dell'ID ambito seguito da una rappresentazione di stringa della porta. L'ID ambito e il numero di porta sono parametri facoltativi.

La rappresentazione di stringa di base dell'indirizzo IPv6 restituito è costituita da 8 numeri esadecimali separati da due punti. Una stringa di numeri esadecimali consecutivi zero viene sostituita con due punti. Nella rappresentazione di stringa dell'indirizzo IPv6 possono essere presenti solo due punti. Gli ultimi 32 bit sono 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.

Se viene specificato un ID ambito, la rappresentazione di stringa dell'ID ambito è separata dalla rappresentazione di stringa dell'indirizzo IPv6 in base a un carattere percentuale ('%'). Se viene specificato un numero di porta, la rappresentazione di stringa dell'indirizzo IPv6 e l'ID ambito sono racchiusi tra parentesi graffe quadrate (un carattere "[" iniziale seguito dall'indirizzo IPv6 seguito da un carattere '% seguito dall'ID ambito con un carattere ']' finale). Il numero di porta viene rappresentato come due punti dopo il carattere di parentesi graffa destra seguito dalla rappresentazione di stringa del numero di porta in decimale.

RtlIpv6AddressToStringEx è una funzione utile che non richiede che la DLL di Windows Sockets venga caricata per accedere a una funzione fornita in Windows Sockets per eseguire la conversione dell'indirizzo IP alla conversione di stringhe.

Se la lunghezza del buffer a cui punta il parametro AddressString non è sufficiente per ricevere la rappresentazione di stringa dell'indirizzo IP, dell'ID ambito e della porta, RtlIpv6AddressToStringEx restituisce ERROR_INVALID_PARAMETER e imposta il parametro AddressStringLength sulla lunghezza del buffer richiesta.

Quando viene definito UNICODE o _UNICODE, RtlIpv6AddressToStringEx viene definito in RtlIpv6AddressToStringExW, la versione Unicode di questa funzione. Il parametro AddressString viene definito per il tipo di dati PWSTR.

Quando unicode e _UNICODE non sono definiti, RtlIpv6AddressToStringEx viene definito in RtlIpv6AddressToStringExA, la versione ANSI di questa funzione. Il parametro AddressString viene definito nel tipo di dati PSTR.

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

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

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 (include Mstcpip.h)
Libreria	ntdll.lib
DLL	ntdll.dll