Función WSAAddressToStringA (winsock2.h)
La función WSAAddressToString convierte todos los componentes de una estructura de sockaddr en una representación de cadena legible de la dirección.
Esto está pensado para usarse principalmente con fines de visualización. Si el autor de la llamada requiere que un proveedor determinado realice la traducción, debe proporcionar la estructura WSAPROTOCOL_INFO correspondiente en el parámetro lpProtocolInfo .
Sintaxis
INT WSAAPI WSAAddressToStringA(
[in] LPSOCKADDR lpsaAddress,
[in] DWORD dwAddressLength,
[in, optional] LPWSAPROTOCOL_INFOA lpProtocolInfo,
[in, out] LPSTR lpszAddressString,
[in, out] LPDWORD lpdwAddressStringLength
);
Parámetros
[in] lpsaAddress
Puntero a la estructura sockaddr que se va a traducir en una cadena.
[in] dwAddressLength
Longitud, en bytes, de la dirección de la estructura sockaddr a la que apunta el parámetro lpsaAddress . El parámetro dwAddressLength puede variar en tamaño con distintos protocolos.
[in, optional] lpProtocolInfo
Puntero a la estructura WSAPROTOCOL_INFO para un proveedor determinado. Si este parámetro es NULL, la llamada se enruta al proveedor del primer protocolo que admite la familia de direcciones indicada en el parámetro lpsaAddress .
[in, out] lpszAddressString
Puntero al búfer que recibe la cadena de dirección legible.
[in, out] lpdwAddressStringLength
En la entrada, este parámetro especifica la longitud del búfer al que apunta el parámetro lpszAddressString . La longitud se representa en bytes para cadenas ANSI y en WCHAR para cadenas Unicode. En la salida, este parámetro devuelve la longitud de la cadena, incluido el terminador NULL copiado realmente en el búfer al que apunta el parámetro lpszAddressString . Si el búfer especificado no es lo suficientemente grande, la función produce un error específico de WSAEFAULT y este parámetro se actualiza con el tamaño necesario.
Valor devuelto
Si no se produce ningún error, WSAAddressToString devuelve un valor de cero. De lo contrario, se devuelve el valor SOCKET_ERROR y se puede recuperar un número de error específico llamando a WSAGetLastError.
Código de error | Significado |
---|---|
Los parámetros lpcsAddress, lpProtocolInfo y lpszAddressString especificados apuntan a la memoria que no está todo en el espacio de direcciones del proceso o el búfer al que apunta el parámetro lpszAddressString es demasiado pequeño. Pase un búfer más grande. | |
Se pasó un parámetro no válido. Este error se devuelve si el parámetro lpsaAddress, dwAddressLength o lpdwAddressStringLength son NULL. Este error también se devuelve si la dirección especificada no es una dirección de socket válida o ningún proveedor de transporte admite la familia de direcciones indicada. | |
No hay espacio disponible en el búfer. | |
El archivo DLL winsock 2 no se ha inicializado. La aplicación debe llamar primero a WSAStartup antes de llamar a cualquier función de Windows Sockets. |
Comentarios
La función WSAAddressToString proporciona una traducción de direcciones a cadenas independiente del protocolo. La función WSAAddressToString toma una estructura de direcciones de socket a la que apunta el parámetro lpsaAddress y devuelve un puntero a una cadena terminada en NULL que representa la dirección del socket en el parámetro lpszAddressString . Aunque la función inet_ntoa solo funciona con direcciones IPv4, la función WSAAddressToString funciona con cualquier dirección de socket compatible con un proveedor winsock en el equipo local, incluidas las direcciones IPv6.
Si el parámetro lpsaAddress apunta a una dirección de socket IPv4 (la familia de direcciones es AF_INET), la cadena de dirección devuelta en el búfer a la que apunta el parámetro lpszAddressString está en notación decimal con puntos como en "192.168.16.0", un ejemplo de una dirección IPv4 en notación decimal con puntos.
Si el parámetro lpsaAddress apunta a una dirección de socket IPv6 (la familia de direcciones es AF_INET6), la cadena de dirección devuelta en el búfer a la que apunta el parámetro lpszAddressString está en formato estándar de Internet. La representación de cadena básica consta de 8 números hexadecimales separados por dos puntos. Una cadena de números cero consecutivos se reemplaza por dos puntos. Solo puede haber dos puntos en la representación de cadena de la dirección IPv6.
Si la longitud del búfer a la que apunta el parámetro lpszAddressString no es lo suficientemente grande como para recibir la representación de cadena de la dirección del socket, WSAAddressToString devuelve WSAEFAULT.
Se agregó compatibilidad con direcciones IPv6 mediante la función WSAAddressToString en Windows XP con Service Pack 1 (SP1) y versiones posteriores. IPv6 también debe instalarse en el equipo local para que la función WSAAddressToString admita direcciones IPv6.
Windows Phone 8: La función WSAAddressToStringW es compatible con las aplicaciones de la Tienda de Windows Phone en Windows Phone 8 y versiones posteriores.
Windows 8.1 y Windows Server 2012 R2: La función WSAAddressToStringW es compatible con las aplicaciones de la Tienda Windows en Windows 8.1, Windows Server 2012 R2 y versiones posteriores.
Nota
El encabezado winsock2.h define WSAAddressToString como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutro de codificación con código que no es neutral de codificación puede provocar discrepancias que dan lugar a errores de compilación o en tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.
Requisitos
Requisito | Value |
---|---|
Cliente mínimo compatible | Windows XP, Windows 8.1 [aplicaciones de escritorio | Aplicaciones para UWP] |
Servidor mínimo compatible | Windows Server 2003 [aplicaciones de escritorio | aplicaciones para UWP] |
Plataforma de destino | Windows |
Encabezado | winsock2.h |
Library | Ws2_32.lib |
Archivo DLL | Ws2_32.dll |