Funzione WSAAddressToStringW (winsock2.h)

Articolo
03/08/2023

La funzione WSAAddressToString converte tutti i componenti di una struttura sockaddr in una rappresentazione di stringa leggibile dell'indirizzo.

Questa operazione deve essere utilizzata principalmente a scopo di visualizzazione. Se il chiamante richiede che la traduzione venga eseguita da un determinato provider, deve fornire la struttura di WSAPROTOCOL_INFO corrispondente nel parametro lpProtocolInfo .

Sintassi

INT WSAAPI WSAAddressToStringW(
  [in]           LPSOCKADDR          lpsaAddress,
  [in]           DWORD               dwAddressLength,
  [in, optional] LPWSAPROTOCOL_INFOW lpProtocolInfo,
  [in, out]      LPWSTR              lpszAddressString,
  [in, out]      LPDWORD             lpdwAddressStringLength
);

Parametri

[in] lpsaAddress

Puntatore alla struttura sockaddr da convertire in una stringa.

[in] dwAddressLength

Lunghezza, in byte, dell'indirizzo nella struttura sockaddr a cui punta il parametro lpsaAddress . Il parametro dwAddressLength può variare in base alle dimensioni con protocolli diversi.

[in, optional] lpProtocolInfo

Puntatore alla struttura WSAPROTOCOL_INFO per un provider specifico. Se questo parametro è NULL, la chiamata viene instradata al provider del primo protocollo che supporta la famiglia di indirizzi indicata nel parametro lpsaAddress .

[in, out] lpszAddressString

Puntatore al buffer che riceve la stringa di indirizzo leggibile.

[in, out] lpdwAddressStringLength

In input, questo parametro specifica la lunghezza del buffer a cui punta il parametro lpszAddressString . La lunghezza è rappresentata in byte per le stringhe ANSI e in WCHAR per stringhe Unicode. Nell'output, questo parametro restituisce la lunghezza della stringa, incluso il carattere di terminazione NULL effettivamente copiato nel buffer a cui punta il parametro lpszAddressString . Se il buffer specificato non è sufficientemente grande, la funzione ha esito negativo con un errore specifico di WSAEFAULT e questo parametro viene aggiornato con le dimensioni necessarie.

Valore restituito

Se non si verifica alcun errore, WSAAddressToString restituisce un valore pari a zero. In caso contrario, viene restituito il valore SOCKET_ERROR e è possibile recuperare un numero di errore specifico chiamando WSAGetLastError.

Codice di errore	Significato
WSAEFAULT	I parametri lpcsAddress, lpProtocolInfo e lpszAddressString specificati puntano alla memoria che non è tutto nello spazio degli indirizzi del processo o il buffer a cui punta il parametro lpszAddressString è troppo piccolo. Passare un buffer più grande.
WSAEINVAL	È stato passato un parametro non valido. Questo errore viene restituito se il parametro lpsaAddress, dwAddressLength o lpdwAddressStringLength è NULL. Questo errore viene restituito anche se l'indirizzo specificato non è un indirizzo socket valido o nessun provider di trasporto supporta la famiglia di indirizzi indicata.
WSAENOBUFS	Nessuno spazio di buffer disponibile.
WSANOTINITIALISED	La DLL Winsock 2 non è stata inizializzata. L'applicazione deve prima chiamare WSAStartup prima di chiamare qualsiasi funzione Di Windows Sockets.

Commenti

La funzione WSAAddressToString fornisce una conversione da indirizzo a stringa indipendente dal protocollo. La funzione WSAAddressToString accetta una struttura di indirizzi socket a cui punta il parametro lpsaAddress e restituisce un puntatore a una stringa con terminazione NULL che rappresenta l'indirizzo del socket nel parametro lpszAddressString . Anche se la funzione inet_ntoa funziona solo con indirizzi IPv4, la funzione WSAAddressToString funziona con qualsiasi indirizzo socket supportato da un provider Winsock nel computer locale, inclusi gli indirizzi IPv6.

Se il parametro lpsaAddress punta a un indirizzo socket IPv4 (la famiglia di indirizzi è AF_INET), la stringa di indirizzo restituita nel buffer a cui punta il parametro lpszAddressString è in notazione decimale tratteggiata come in "192.168.16.0", un esempio di indirizzo IPv4 nella notazione decimale tratteggiata.

Se il parametro lpsaAddress punta a un indirizzo socket IPv6 (la famiglia di indirizzi è AF_INET6), la stringa di indirizzo restituita nel buffer a cui punta il parametro lpszAddressString è in formato standard Internet. La rappresentazione di stringa di base è costituita da 8 numeri esadecimali separati da due punti. Una stringa di numeri zero consecutivi viene sostituita con due punti. Nella rappresentazione di stringa dell'indirizzo IPv6 può essere presente un solo due punti.

Se la lunghezza del buffer a cui punta il parametro lpszAddressString non è sufficiente per ricevere la rappresentazione di stringa dell'indirizzo del socket, WSAAddressToString restituisce WSAEFAULT.

Il supporto per gli indirizzi IPv6 che usano la funzione WSAAddressToString è stato aggiunto in Windows XP con Service Pack 1 (SP1) e versioni successive. IPv6 deve essere installato anche nel computer locale per la funzione WSAAddressToString per supportare gli indirizzi IPv6.

Windows Phone 8: la funzione WSAAddressToStringW è supportata per le app dello Store Windows Phone in Windows Phone 8 e versioni successive.

Windows 8.1 e Windows Server 2012 R2: la funzione WSAAddressToStringW è supportata per le app di Windows Store in Windows 8.1, Windows Server 2012 R2 e versioni successive.

Nota

L'intestazione winsock2.h definisce WSAAddressToString 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 che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.

Requisiti


Client minimo supportato	Windows 8.1, Windows Vista [app desktop \| App UWP]
Server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	winsock2.h
Libreria	Ws2_32.lib
DLL	Ws2_32.dll