Funzione WSAAddressToStringA (winsock2.h)

Articolo
05/30/2024

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

Ciò è destinato a essere usato 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 WSAAddressToStringA(
  [in]           LPSOCKADDR          lpsaAddress,
  [in]           DWORD               dwAddressLength,
  [in, optional] LPWSAPROTOCOL_INFOA lpProtocolInfo,
  [in, out]      LPSTR               lpszAddressString,
  [in, out]      LPDWORD             lpdwAddressStringLength
);

Parametri

[in] lpsaAddress

Puntatore alla struttura sockaddr da tradurre 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 dimensioni con protocolli diversi.

[in, optional] lpProtocolInfo

Puntatore alla struttura di WSAPROTOCOL_INFO per un determinato provider. Se si tratta di un parametro NULL, la chiamata viene instradata al provider del primo protocollo che supporta la famiglia di indirizzi indicato 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 stringhe ANSI e in WCHARs per stringhe Unicode. Nell'output, questo parametro restituisce la lunghezza della stringa, inclusa la terminazione NULL effettivamente copiata nel buffer a cui punta il parametro lpszAddressString . Se il buffer specificato non è sufficiente, 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, il valore SOCKET_ERROR viene restituito e un numero di errore specifico può essere recuperato chiamando WSAGetLastError.

Codice di errore	Significato
WSAEFAULT	I parametri lpcsAddress, lpProtocolInfo e lpszAddressString puntano alla memoria non tutti nello spazio degli indirizzi del processo oppure il buffer puntato al 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 sono 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 Windows Sockets.

Commenti

La funzione WSAAddressToString fornisce una traduzione da indirizzo a stringa indipendente dal protocollo. La funzione WSAAddressToString accetta una struttura di indirizzi socket puntata dal parametro lpsaAddress e restituisce un puntatore alla stringa con terminazione NULL che rappresenta l'indirizzo socket nel parametro lpszAddressString . Sebbene la funzione inet_ntoa funzioni 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 un indirizzo IPv4 nella notazione decimale punteggiata.

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 puntata dal parametro lpszAddressString non è sufficiente per ricevere la rappresentazione stringa dell'indirizzo socket, WSAAddressToString restituisce WSAEFAULT.

Il supporto per gli indirizzi IPv6 tramite 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 di Windows Phone Store 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 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

Requisito	Valore
Client minimo supportato	Windows XP, Windows 8.1 [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