WSAStringToAddressA, fonction (winsock2.h)

Article
11/20/2024

La fonction WSAStringToAddress convertit une adresse réseau dans sa forme de présentation de texte standard en forme binaire numérique dans une structure sockaddr, adaptée à la transmission aux routines Windows Sockets qui prennent une telle structure.

Syntaxe

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

Paramètres

[in] AddressString

Pointeur vers la chaîne sans fin qui contient l’adresse réseau sous forme de texte standard à convertir.

[in] AddressFamily

Famille d’adresses de l’adresse réseau pointée par le paramètre AddressString.

[in, optional] lpProtocolInfo

Structure WSAPROTOCOL_INFO associée au fournisseur à utiliser. S’il s’agit NULL, l’appel est acheminé vers le fournisseur du premier protocole prenant en charge l'AddressFamilyindiqué.

[out] lpAddress

Pointeur vers une mémoire tampon remplie d’une structure sockaddr pour la chaîne d’adresse si la fonction réussit.

[in, out] lpAddressLength

Pointeur vers la longueur, en octets, de la mémoire tampon pointée par le paramètre lpAddress. Si l’appel de fonction réussit, ce paramètre retourne un pointeur vers la taille de la structure sockaddr retournée dans le paramètre lpAddress . Si la mémoire tampon spécifiée n’est pas suffisamment grande, la fonction échoue avec une erreur spécifique de WSAEFAULT et ce paramètre est mis à jour avec la taille requise en octets.

Valeur de retour

La valeur de retour de WSAStringToAddress est égale à zéro si l’opération a réussi. Sinon, la valeur SOCKET_ERROR est retournée et un numéro d’erreur spécifique peut être récupéré en appelant WSAGetLastError.

Code d’erreur	Signification
WSAEFAULT	La mémoire tampon pointée par le paramètre lpAddress est trop petite. Passez une mémoire tampon plus grande.
WSAEINVAL	Les fonctions n’ont pas pu traduire la chaîne en sockaddr. Pour plus d’informations, consultez la section Remarques suivantes.
WSANOTINITIALISED	Le WS2_32.DLL n’a pas été initialisé. L’application doit d’abord appeler WSAStartup avant d’appeler des fonctions Windows Socket.
WSA_NOT_ENOUGH_MEMORY	La mémoire était insuffisante pour effectuer l’opération.

Remarques

La fonction WSAStringToAddress convertit une adresse réseau sous forme de texte standard en forme binaire numérique dans une structure sockaddr.

Tous les composants manquants de l’adresse sont par défaut une valeur raisonnable, si possible. Par exemple, un numéro de port manquant est défini par défaut sur zéro. Si l’appelant souhaite que la traduction soit effectuée par un fournisseur particulier, elle doit fournir la structure de WSAPROTOCOL_INFO correspondante dans le paramètre lpProtocolInfo.

La fonction WSAStringToAddress échoue (et retourne WSAEINVAL) si le membre sin_family de la structure SOCKADDR_IN, qui est transmis dans le paramètre lpAddress sous la forme d’une structure sockaddr , n’est pas défini sur AF_INET ou AF_INET6.

La prise en charge des adresses IPv6 à l’aide de la fonction WSAStringToAddress a été ajoutée sur Windows XP avec Service Pack 1 (SP1) et versions ultérieures. IPv6 doit également être installé sur l’ordinateur local pour la fonction WSAStringToAddress pour prendre en charge les adresses IPv6.

Windows Phone 8 : Cette fonction est prise en charge pour les applications du Windows Phone Store sur Windows Phone 8 et versions ultérieures.

windows 8.1 et Windows Server 2012 R2: cette fonction est prise en charge pour les applications du Windows Store sur Windows 8.1, Windows Server 2012 R2 et versions ultérieures.

Note

L’en-tête winsock2.h définit WSAStringToAddress comme alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows 8.1, Windows Vista [applications de bureau \| Applications UWP]
serveur minimum pris en charge	Windows Server 2003 [applications de bureau \| Applications UWP]
plateforme cible	Windows
d’en-tête	winsock2.h
bibliothèque	Ws2_32.lib
DLL	Ws2_32.dll