Función WSAStringToAddressA (winsock2.h)

Artículo
11/20/2024

La función WSAStringToAddress convierte una dirección de red en su formulario de presentación de texto estándar en su formato binario numérico en una estructura sockaddr, adecuada para pasar a rutinas de Windows Sockets que toman dicha estructura.

Sintaxis

INT WSAAPI WSAStringToAddressA(
  [in]           LPSTR               AddressString,
  [in]           INT                 AddressFamily,
  [in, optional] LPWSAPROTOCOL_INFOA lpProtocolInfo,
  [out]          LPSOCKADDR          lpAddress,
  [in, out]      LPINT               lpAddressLength
);

Parámetros

[in] AddressString

Puntero a la cadena terminada en cero que contiene la dirección de red en formato de texto estándar que se va a convertir.

[in] AddressFamily

Familia de direcciones de la dirección de red a la que apunta el parámetro AddressString.

[in, optional] lpProtocolInfo

Estructura WSAPROTOCOL_INFO asociada al proveedor que se va a usar. Si se trata de NULL, la llamada se enruta al proveedor del primer protocolo que admite el AddressFamily indicado.

[out] lpAddress

Puntero a un búfer que se rellena con un sockaddr estructura para la cadena de dirección si la función se ejecuta correctamente.

[in, out] lpAddressLength

Puntero a la longitud, en bytes, del búfer al que apunta el parámetro lpAddress. Si la llamada a la función se realiza correctamente, este parámetro devuelve un puntero al tamaño del estructura sockaddr devuelta en el parámetro lpAddress. 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 en bytes.

Valor devuelto

El valor devuelto de WSAStringToAddress es cero si la operación se realizó correctamente. 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
WSAEFAULT	El búfer al que apunta el parámetro lpAddress es demasiado pequeño. Pase un búfer mayor.
WSAEINVAL	Las funciones no pudieron traducir la cadena en un sockaddr. Consulte la sección Comentarios siguientes para obtener más información.
WSANOTINITIALISED	No se ha inicializado el WS2_32.DLL. La aplicación debe llamar primero a WSAStartup antes de llamar a cualquier función de Windows Socket.
WSA_NOT_ENOUGH_MEMORY	No había memoria suficiente para realizar la operación.

Observaciones

La función WSAStringToAddress convierte una dirección de red en formato de texto estándar en su formato binario numérico en una estructura sockaddr.

Los componentes que faltan de la dirección se establecerán de forma predeterminada en un valor razonable, si es posible. Por ejemplo, un número de puerto que falta tendrá como valor predeterminado cero. Si el autor de la llamada desea que un proveedor determinado realice la traducción, debe proporcionar la estructura de WSAPROTOCOL_INFO correspondiente en el parámetro lpProtocolInfo .

La función WSAStringToAddress produce un error (y devuelve WSAEINVAL) si el miembro sin_family de la estructura SOCKADDR_IN, que se pasa en el parámetro lpAddress en forma de una estructura sockaddr, no se establece en AF_INET o AF_INET6.

Se agregó compatibilidad con direcciones IPv6 mediante la función WSAStringToAddress en Windows XP con Service Pack 1 (SP1) y versiones posteriores. IPv6 también debe instalarse en el equipo local para la función WSAStringToAddress para admitir direcciones IPv6.

Windows Phone 8: Esta función 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: esta función 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 WSAStringToAddress 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 neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Conventions for Function Prototypes.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows 8.1, Windows Vista [aplicaciones de escritorio \| Aplicaciones para UWP]
servidor mínimo admitido	Windows Server 2003 [aplicaciones de escritorio \| Aplicaciones para UWP]
de la plataforma de destino de	Windows
encabezado de	winsock2.h
biblioteca de	Ws2_32.lib
DLL de	Ws2_32.dll