Función WSAStringToAddressA (winsock2.h)

Artículo
03/08/2023

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 esta 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 es NULL, la llamada se enruta al proveedor del primer protocolo que admite addressFamily indicado.

[out] lpAddress

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

[in, out] lpAddressLength

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

Comentarios

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 falten 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 quiere que un proveedor determinado realice la traducción, debe proporcionar la estructura WSAPROTOCOL_INFO correspondiente en el parámetro lpProtocolInfo .

Se produce un error en la función WSAStringToAddress (y devuelve WSAEINVAL) si el sin_family miembro de la estructura SOCKADDR_IN , que se pasa en el parámetro lpAddress en forma de 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 que la función WSAStringToAddress admita direcciones IPv6.

Windows Phone 8: esta función es compatible con las aplicaciones de Windows Phone Store 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 Convenciones para prototipos de función.

Requisitos


Cliente mínimo compatible	Windows 8.1, Windows Vista [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