SetAddrInfoExA, fonction (ws2tcpip.h)
La fonction SetAddrInfoEx inscrit ou annule l’inscription d’un nom, d’un nom de service et des adresses associées auprès d’un fournisseur d’espaces de noms spécifique.
Syntaxe
INT WSAAPI SetAddrInfoExA(
[in] PCSTR pName,
[in] PCSTR pServiceName,
[in, out] SOCKET_ADDRESS *pAddresses,
[in] DWORD dwAddressCount,
[in, optional] LPBLOB lpBlob,
[in] DWORD dwFlags,
[in] DWORD dwNameSpace,
[in, optional] LPGUID lpNspId,
[in, optional] timeval *timeout,
[in, optional] LPOVERLAPPED lpOverlapped,
[in, optional] LPLOOKUPSERVICE_COMPLETION_ROUTINE lpCompletionRoutine,
[out, optional] LPHANDLE lpNameHandle
);
Paramètres
[in] pName
Pointeur vers une chaîne terminée par NULL contenant un nom sous lequel les adresses doivent être enregistrées ou supprimées. Interprétation de ce paramètre spécifique au fournisseur d’espaces de noms.
[in] pServiceName
Pointeur vers une chaîne facultative terminée par null qui contient le nom de service associé au nom en cours d’inscription. L’interprétation de ce paramètre est spécifique au fournisseur d’espaces de noms.
[in, out] pAddresses
Pointeur vers une liste facultative d’adresses à inscrire auprès du fournisseur d’espaces de noms.
[in] dwAddressCount
Nombre d’adresses passées dans le paramètre pAddresses . Si ce paramètre est égal à zéro, le paramètre pName est désinscrit du fournisseur d’espaces de noms.
[in, optional] lpBlob
Pointeur facultatif vers des données utilisées pour définir des informations d’espace de noms spécifiques au fournisseur associées au paramètre pName au-delà d’une liste d’adresses. Toutes les informations qui ne peuvent pas être passées dans le paramètre pAddresses peuvent être passées dans le paramètre lpBlob . Le format de ces informations est spécifique au fournisseur d’espaces de noms.
[in] dwFlags
Ensemble d’indicateurs contrôlant la façon dont les paramètres pName et pServiceName doivent être inscrits auprès du fournisseur d’espaces de noms. L’interprétation de ces informations est spécifique au fournisseur d’espaces de noms.
[in] dwNameSpace
Identificateur d’espace de noms qui détermine le fournisseur d’espaces de noms avec lequel inscrire ces informations. La transmission d’un identificateur d’espace de noms spécifique entraîne l’inscription de ces informations uniquement auprès des fournisseurs d’espaces de noms qui prennent en charge l’espace de noms spécifié. La spécification de NS_ALL entraîne l’inscription des informations auprès de tous les fournisseurs d’espaces de noms installés et actifs.
Les options du paramètre dwNameSpace sont répertoriées dans le fichier Include Winsock2.h . Plusieurs fournisseurs d’espaces de noms sont inclus dans Windows Vista et versions ultérieures. D’autres fournisseurs d’espaces de noms peuvent être installés, de sorte que les valeurs possibles suivantes sont uniquement celles couramment disponibles. Beaucoup d’autres sont possibles.
[in, optional] lpNspId
Pointeur vers un GUID facultatif d’un fournisseur d’espaces de noms spécifique avec lequel inscrire ces informations dans le cas où plusieurs fournisseurs d’espaces de noms sont inscrits sous un seul espace de noms, comme NS_DNS. Le passage du GUID pour un fournisseur d’espace de noms spécifique entraîne l’inscription des informations uniquement auprès du fournisseur d’espace de noms spécifié. La fonction WSAEnumNameSpaceProviders peut être appelée pour récupérer le GUID d’un fournisseur d’espaces de noms.
[in, optional] timeout
Paramètre facultatif indiquant le temps, en millisecondes, d’attendre une réponse du fournisseur d’espaces de noms avant d’arrêter l’appel. Ce paramètre est actuellement réservé et doit être défini sur NULL , car aucune option de délai d’expiration n’est prise en charge.
[in, optional] lpOverlapped
Pointeur facultatif vers une structure superposée utilisée pour l’opération asynchrone. Ce paramètre est actuellement réservé et doit être défini sur NULL , car les opérations asynchrones ne sont pas prises en charge.
[in, optional] lpCompletionRoutine
Pointeur facultatif vers une fonction à appeler en cas de réussite des opérations asynchrones. Ce paramètre est actuellement réservé et doit être défini sur NULL , car les opérations asynchrones ne sont pas prises en charge.
[out, optional] lpNameHandle
Pointeur facultatif utilisé uniquement pour les opérations asynchrones. Ce paramètre est actuellement réservé et doit être défini sur NULL , car les opérations asynchrones ne sont pas prises en charge.
Valeur retournée
En cas de réussite, SetAddrInfoEx retourne NO_ERROR (0). L’échec retourne un code d’erreur Windows Sockets différent de zéro, comme indiqué dans les codes d’erreur des sockets Windows.
| Code d'erreur | Signification |
|---|---|
| Un appel WSAStartup réussi doit se produire avant d’utiliser cette fonction. | |
| Un échec temporaire de la résolution de noms s’est produit. | |
| Un paramètre non valide a été fourni. Cette erreur est retournée si l’un des paramètres réservés n’est pas NULL. | |
| L’espace de mémoire tampon est insuffisant. | |
| Un échec non récupérable de la résolution de noms s’est produit. | |
| Un échec d’allocation de mémoire s’est produit. |
Remarques
La fonction SetAddrInfoEx fournit une méthode indépendante du protocole pour inscrire ou annuler l’inscription d’un nom et d’une ou plusieurs adresses auprès d’un fournisseur d’espaces de noms. Le NS_EMAIL fournisseur d’espaces de noms dans Windows Vista et ultérieurement prend en charge l’inscription et la désinscription des adresses. Les fournisseurs d’espaces de noms NS_DNS, NS_PNRPNAME et NS_PNRPNAME par défaut ne prennent actuellement pas en charge l’inscription de noms.
Si la fonction SetAddrInfoEx est appelée avec NS_ALL définie comme paramètre dwNameSpace et le paramètre lpNspId non spécifié, SetAddrInfoEx tente d’inscrire ou de désinscrire le nom et les adresses associées à tous les espaces de noms installés et actifs. La fonction SetAddrInfoEx retourne la réussite si l’un des fournisseurs d’espaces de noms a correctement inscrit ou désinscrit le nom, mais il n’y aura aucune indication du fournisseur d’espace de noms qui a réussi ou de ceux qui ont échoué à la demande.
Lorsque unicode ou _UNICODE est défini, SetAddrInfoEx est défini sur SetAddrInfoExW, la version Unicode de cette fonction. Les paramètres de chaîne sont définis sur le type de données PWSTR .
Quand UNICODE ou _UNICODE n’est pas défini, SetAddrInfoEx est défini sur SetAddrInfoExA, la version ANSI de cette fonction. Les paramètres de chaîne sont du type de données PCSTR .
Les informations inscrites auprès d’un fournisseur d’espaces de noms peuvent être retournées en appelant les fonctions GetAddrInfoEx, getaddrinfo ou GetAddrInfoW . La fonction GetAddrInfoEx est une version améliorée des fonctions getaddrinfo et GetAddrInfoW .
Sur Windows Vista et versions ultérieures, lorsque SetAddrInfoEx est appelé à partir d’un service, si l’opération est le résultat d’un processus utilisateur appelant le service, le service doit emprunter l’identité de l’utilisateur. Cela permet d’appliquer correctement les compartiments de sécurité et de routage.
Windows 8.1 et Windows Server 2012 R2 : la fonction SetAddrInfoExW est prise en charge pour les applications du Windows Store sur Windows 8.1, Windows Server 2012 R2 et versions ultérieures.
Notes
L’en-tête ws2tcpip.h définit SetAddrInfoEx 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. La combinaison 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.
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows 8.1, Windows Vista [applications de bureau | Applications UWP] |
| Serveur minimal pris en charge | Windows Server 2008 [applications de bureau | applications UWP] |
| Plateforme cible | Windows |
| En-tête | ws2tcpip.h |
| Bibliothèque | Ws2_32.lib |
| DLL | Ws2_32.dll |