code de contrôle SIO_ADDRESS_LIST_QUERY

Article
06/13/2023

Description

Le code de contrôle SIO_ADDRESS_LIST_QUERY obtient une liste des adresses de transport locales de la famille de protocoles du socket à laquelle l’application peut se lier. La liste des adresses varie en fonction de la famille d’adresses et certaines adresses sont exclues de la liste.

Pour effectuer cette opération, appelez la fonction WSAIoctl ou WSPIoctl avec les paramètres suivants.

int WSAIoctl(
  (socket) s,            // descriptor identifying a socket
  SIO_ADDRESS_LIST_QUERY,            // dwIoControlCode
  NULL,                              // lpvInBuffer
  0,                                 // cbInBuffer
  (LPVOID) lpvOutBuffer,          // output buffer
  (DWORD) cbOutBuffer,            // size of output buffer  
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped, // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
);

int WSPIoctl(
  (socket) s,            // descriptor identifying a socket
  SIO_ADDRESS_LIST_QUERY,            // dwIoControlCode
  NULL,                              // lpvInBuffer
  0,                                 // cbInBuffer
  (LPVOID) lpvOutBuffer,          // output buffer
  (DWORD) cbOutBuffer,            // size of output buffer  
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped, // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
  (LPWSATHREADID) lpThreadId,   // a WSATHREADID structure
  (LPINT) lpErrno   // a pointer to the error code.
);

Paramètres

s

Descripteur identifiant un socket.

dwIoControlCode

Code de contrôle pour l’opération. Utilisez SIO_ADDRESS_LIST_QUERY pour cette opération.

lpvInBuffer

Pointeur vers la mémoire tampon d’entrée. Ce paramètre n’est pas utilisé pour cette opération.

cbInBuffer

Taille, en octets, de la mémoire tampon d’entrée. Ce paramètre n’est pas utilisé pour cette opération.

lpvOutBuffer

Pointeur vers la mémoire tampon de sortie.

cbOutBuffer

Taille, en octets, de la mémoire tampon de sortie.

lpcbBytesReturned

Pointeur vers une variable qui reçoit la taille, en octets, des données stockées dans la mémoire tampon de sortie.

lpvOverlapped

Pointeur vers une structure WSAOVERLAPPED .

Si le socket s a été créé sans l’attribut superposé, le paramètre lpOverlapped est ignoré.

Si s a été ouvert avec l’attribut qui se chevauche et que le paramètre lpOverlapped n’a pas la valeur NULL, l’opération est effectuée en tant qu’opération (asynchrone) qui se chevauche. Dans ce cas, le paramètre lpOverlapped doit pointer vers une structure WSAOVERLAPPED valide.

Pour les opérations qui se chevauchent, la fonction WSAIoctl ou WSPIoctl retourne immédiatement, et la méthode d’achèvement appropriée est signalée une fois l’opération terminée. Sinon, la fonction ne retourne pas tant que l’opération n’est pas terminée ou qu’une erreur se produit.

lpCompletionRoutine

Type : _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

Pointeur vers la routine d’achèvement appelée une fois l’opération terminée (ignorée pour les sockets qui ne se chevauchent pas).

lpThreadId

Pointeur vers une structure WSATHREADID à utiliser par le fournisseur dans un appel ultérieur à WPUQueueApc. Le fournisseur doit stocker la structure WSATHREADID référencée (pas le pointeur vers le même) jusqu’à ce que la fonction WPUQueueApc soit retournée.

Note Ce paramètre s’applique uniquement à la fonction WSPIoctl .

lpErrno

Pointeur vers le code d’erreur.

Note Ce paramètre s’applique uniquement à la fonction WSPIoctl .

Valeur retournée

Si l’opération se termine correctement, la fonction WSAIoctl ou WSPIoctl retourne zéro.

Si l’opération échoue ou est en attente, la fonction WSAIoctl ou WSPIoctl retourne SOCKET_ERROR. Pour obtenir des informations d’erreur étendues, appelez WSAGetLastError.

Code d'erreur	Signification
WSA_IO_PENDING	Une opération superposée a été lancée avec succès et l’achèvement sera indiqué ultérieurement.
WSA_OPERATION_ABORTED	Une opération qui se chevauche a été annulée en raison de la fermeture du socket ou de l’exécution de la commande IOCTL SIO_FLUSH .
WSAEFAULT	Le paramètre lpOverlapped ou lpCompletionRoutine n’est pas totalement contenu dans une partie valide de l’espace d’adressage utilisateur.
WSAEINPROGRESS	La fonction est appelée lorsqu’un rappel est en cours.
WSAEINTR	Une opération de blocage a été interrompue.
WSAEINVAL	Le paramètre dwIoControlCode n’est pas une commande valide, ou un paramètre d’entrée spécifié n’est pas acceptable, ou la commande n’est pas applicable au type de socket spécifié. Cette erreur est retournée si le paramètre cbInBuffer n’est pas défini sur NULL.
WSAENETDOWN	Le sous-système réseau a échoué.
WSAENOBUFS	Aucun espace de mémoire tampon disponible.
WSAENOPROTOOPT	L’option socket n’est pas prise en charge sur le protocole spécifié.
WSAENOTSOCK	Le descripteur s n’est pas un socket.
WSAEOPNOTSUPP	La commande IOCTL spécifiée n’est pas prise en charge. Cette erreur est retournée si le SIO_ADDRESS_LIST_QUERY IOCTL n’est pas pris en charge par le fournisseur de transport.

Notes

La SIO_ADDRESS_LIST_QUERY IOCTL est prise en charge sur Windows 2000 et versions ultérieures du système d’exploitation.

Pour la famille d’adresses AF_INET6, toutes les adresses sont retournées à l’exception des suivantes :

Toute adresse IP dont l’état de détection d’adresse dupliquée (DAD) n’est pas IpDadStatePreferred.
Toute adresse IP dont le niveau d’étendue est inférieur à ScopeLevelSubnet sur une interface où le type d’interface est IF_TYPE_SOFTWARE_LOOPBACK. Cela signifie que les adresses link-local (fe80:*) et bouclage (::1) sur les interfaces de IF_TYPE_SOFTWARE_LOOPBACK type sont exclues, mais pas si ces adresses se trouvent sur une interface avec un type différent.

Pour la famille d’adresses AF_INET , toutes les adresses sont retournées à l’exception des suivantes :

Toute adresse IP dont l’état de détection d’adresse dupliquée (DAD) n’est pas IpDadStatePreferred.
Toute adresse IP sur une interface où le type d’interface est IF_TYPE_SOFTWARE_LOOPBACK et le lien est local. Cela signifie que les adresses link-local (169.254.) et bouclage (127.) sur les interfaces de IF_TYPE_SOFTWARE_LOOPBACK type sont exclues, mais pas si ces adresses se trouvent sur une interface avec un type différent.

Pour plus d’informations sur l’état de DAD, consultez la documentation ip Helper sur l’énumération IP_DAD_STATE et la structure IP_ADAPTER_UNICAST_ADDRESS et la documentation MIB sur la structure MIB_UNICASTIPADDRESS_ROW . Pour plus d’informations sur le type d’interface, consultez la documentation IP Helper sur la structure IP_ADAPTER_ADDRESSES et la fonction GetAdaptersAddresses et la documentation MIB sur MIB_IF_ROW2 structure. Pour plus d’informations sur le niveau d’étendue, consultez la documentation ip Helper sur la structure IP_ADAPTER_ADDRESSES et l’énumération SCOPE_LEVEL .

La liste retournée dans la mémoire tampon de sortie pointée par le paramètre lpvOutBuffer se présente sous la forme d’une structure SOCKET_ADDRESS_LIST .

Si la mémoire tampon de sortie spécifiée dans le paramètre lpvOutBuffer n’est pas suffisamment grande pour contenir la liste d’adresses, SOCKET_ERROR est retourné en tant que résultat de ce IOCTL et WSAGetLastError renvoie WSAEFAULT. La taille requise, en octets, pour la mémoire tampon de sortie est retournée dans le paramètre lpcbBytesReturned dans ce cas. Notez que le code d’erreur WSAEFAULT est également retourné si le paramètre lpvInBuffer, lpvOutBuffer ou lpcbBytesReturned n’est pas entièrement contenu dans une partie valide de l’espace d’adressage utilisateur.

Le SIO_ADDRESS_LIST_QUERY IOCTL est normalement appelé de manière synchrone avec le paramètre lpvOverlapped défini sur NULL, car la liste d’adresses est retournée immédiatement.

Note Dans les environnements Windows Plug-n-Play, les adresses peuvent être ajoutées et supprimées dynamiquement. Par conséquent, les applications ne peuvent pas s’appuyer sur les informations retournées par SIO_ADDRESS_LIST_QUERY être persistantes. Les applications peuvent s’inscrire aux notifications de changement d’adresse par le biais de la SIO_ADDRESS_LIST_CHANGE IOCTL qui fournit la notification par le biais d’un événement d’E/S superposé ou de FD_ADDRESS_LIST_CHANGE . La séquence d’actions suivante peut être utilisée pour garantir que l’application dispose toujours des informations de liste d’adresses actuelles :

Émettre le SIO_ADDRESS_LIST_CHANGE IOCTL
Émettre le SIO_ADDRESS_LIST_QUERY IOCTL
Chaque fois que le SIO_ADDRESS_LIST_CHANGE appel IOCTL notifie l’application d’un changement de liste d’adresses (par le biais d’E/S superposées ou en signalant FD_ADDRESS_LIST_CHANGE événement), l’ensemble de la séquence d’actions doit être répétée.

Dans le Kit de développement logiciel (SDK) Microsoft Windows publié pour Windows Vista et versions ultérieures, la organization des fichiers d’en-tête a changé et le code de contrôle SIO_ADDRESS_LIST_QUERY est défini dans le fichier d’en-tête Ws2def.h. Notez que le fichier d’en-tête Ws2def.h est automatiquement inclus dans Winsock2.h et ne doit jamais être utilisé directement.