WSALookupServiceBeginA, fonction (winsock2.h)

Article
08/27/2023

La fonction WSALookupServiceBegin lance une requête cliente qui est limitée par les informations contenues dans une structure WSAQUERYSET . WSALookupServiceBegin retourne uniquement un handle, qui doit être utilisé par les appels suivants à WSALookupServiceNext pour obtenir les résultats réels.

Syntaxe

INT WSAAPI WSALookupServiceBeginA(
  [in]  LPWSAQUERYSETA lpqsRestrictions,
  [in]  DWORD          dwControlFlags,
  [out] LPHANDLE       lphLookup
);

Paramètres

[in] lpqsRestrictions

Pointeur vers les critères de recherche. Pour plus d’informations, consultez les remarques.

[in] dwControlFlags

Ensemble d’indicateurs qui contrôle la profondeur de la recherche.

Les valeurs prises en charge pour le paramètre dwControlFlags sont définies dans le fichier d’en-tête Winsock2.h et peuvent être une combinaison des options suivantes.

Indicateur	Signification
LUP_DEEP 0x0001	Requêtes approfondies par opposition au seul premier niveau.
LUP_CONTAINERS 0x0002	Retourne uniquement les conteneurs.
LUP_NOCONTAINERS 0x0004	Ne retournez pas de conteneurs.
LUP_NEAREST 0x0008	Si possible, retourne les résultats dans l’ordre de distance. La mesure de la distance est spécifique au fournisseur.
LUP_RETURN_NAME 0x0010	Récupère le nom sous la forme lpszServiceInstanceName.
LUP_RETURN_TYPE 0x0020	Récupère le type sous la forme lpServiceClassId.
LUP_RETURN_VERSION 0x0040	Récupère la version en tant que lpVersion.
LUP_RETURN_COMMENT 0x0080	Récupère le commentaire sous la forme lpszComment.
LUP_RETURN_ADDR 0x0100	Récupère les adresses en tant que lpcsaBuffer.
LUP_RETURN_BLOB 0x0200	Récupère les données privées en tant que lpBlob.
LUP_RETURN_ALIASES 0x0400	Toutes les informations d’alias disponibles doivent être retournées dans les appels successifs à WSALookupServiceNext, et chaque alias retourné aura l’indicateur RESULT_IS_ALIAS défini.
LUP_RETURN_QUERY_STRING 0x0800	Récupère la chaîne de requête utilisée pour la requête.
LUP_RETURN_ALL 0x0FF0	Ensemble d’indicateurs qui récupère toutes les valeurs LUP_RETURN_*.
LUP_FLUSHPREVIOUS 0x1000	Utilisé comme valeur pour le paramètre dwControlFlags dans WSALookupServiceNext. La définition de cet indicateur indique au fournisseur d’ignorer le dernier jeu de résultats, qui était trop volumineux pour la mémoire tampon spécifiée, et de passer au jeu de résultats suivant.
LUP_FLUSHCACHE 0x2000	Si le fournisseur a mis en cache des informations, ignore le cache et interroge l’espace de noms lui-même.
LUP_RES_SERVICE 0x8000	Cela indique si la réponse principale se trouve dans la partie distante ou locale de CSADDR_INFO structure. L’autre partie doit être utilisable dans les deux cas.

[out] lphLookup

Handle à utiliser lors de l’appel de WSALookupServiceNext afin de commencer à récupérer le jeu de résultats.

Valeur retournée

La valeur de retour est 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
WSA_NOT_ENOUGH_MEMORY	La mémoire était insuffisante pour effectuer l’opération.
WSAEINVAL	Un ou plusieurs paramètres étaient manquants ou non valides pour ce fournisseur.
WSANO_DATA	Le nom a été trouvé dans la base de données, mais aucune donnée correspondant aux restrictions spécifiées n’a été trouvée.
WSANOTINITIALISED	Le WS2_32.DLL n’a pas été initialisé. L’application doit d’abord appeler WSAStartup avant d’appeler les fonctions windows Sockets.
WSASERVICE_NOT_FOUND	Aucun service de ce type n’est connu. Le service est introuvable dans l’espace de nom spécifié. Cette erreur est retournée pour une demande de découverte de service Bluetooth si aucun appareil Bluetooth distant n’a été trouvé.

Remarques

Le paramètre lpqsRestrictions pointe vers une mémoire tampon contenant une structure WSAQUERYSET . Au minimum, le membre dwSize du WSAQUERYSET doit être défini sur la longueur de la mémoire tampon avant d’appeler la fonction WSALookupServiceBegin . Les applications peuvent restreindre la requête en spécifiant d’autres membres dans WSAQUERYSET.

Dans la plupart des cas, les applications qui ne s’intéressent qu’à un protocole de transport particulier doivent limiter leur requête par la famille d’adresses et le protocole à l’aide des membres dwNumberOfProtocols et lpafpProtocols du WSAQUERYSET plutôt que par la spécification de l’espace de noms dans le membre dwNameSpace .

Les informations sur les protocoles de transport réseau pris en charge peuvent être retreives à l’aide de la fonction EnumProtocols, WSAEnumProtocols, WSCEnumProtocols ou WSCEnumProtocols32 .

Il est également possible de limiter la requête à un espace de noms unique. Par exemple, une requête qui souhaite uniquement des résultats à partir du DNS (et non des résultats du fichier hôtes locaux et d’autres services de nommage) définit le membre dwNameSpace sur NS_DNS. Par exemple, une découverte d’appareil Bluetooth définit le membre dwNameSpace sur NS_BTH.

Les applications peuvent également restreindre la requête à un fournisseur d’espace de noms spécifique en spécifiant un pointeur vers le GUID du fournisseur dans le membre lpNSProviderId .

Les informations sur les fournisseurs d’espaces de noms sur l’ordinateur local peuvent être récupérées à l’aide de la fonction WSAEnumNameSpaceProviders , WSAEnumNameSpaceProvidersEx, WSCEnumNameSpaceProviders32 ou WSCEnumNameSpaceProvidersEx32.

Si LUP_CONTAINERS est spécifié dans un appel, d’autres valeurs de restriction doivent être évitées. Le cas échéant, c’est au fournisseur de services de nom de décider s’il peut prendre en charge cette restriction sur les conteneurs. Si ce n’est pas le cas, il doit retourner une erreur.

Certains fournisseurs de services de noms peuvent avoir d’autres moyens de trouver des conteneurs. Par exemple, les conteneurs peuvent tous être d’un type connu ou d’un ensemble de types connus, et par conséquent, une restriction de requête peut être créée pour les trouver. Quel que soit l’autre moyen dont dispose le fournisseur de services de nom pour localiser les conteneurs, les LUP_CONTAINERS et les LUP_NOCONTAINERS sont prioritaires. Par conséquent, si une restriction de requête incluant des conteneurs est donnée, la spécification de LUP_NOCONTAINERS empêchera le retour des éléments du conteneur. De même, quelle que soit la restriction de requête, si LUP_CONTAINERS est donné, seuls les conteneurs doivent être retournés. Si un espace de noms ne prend pas en charge les conteneurs et qu’LUP_CONTAINERS est spécifié, il doit simplement retourner WSANO_DATA.

La méthode préférée pour obtenir les conteneurs dans un autre conteneur est l’appel :

dwStatus = WSALookupServiceBegin(
      lpqsRestrictions,
      LUP_CONTAINERS,
      lphLookup);

Cet appel est suivi du nombre requis d’appels WSALookupServiceNext . Cela retourne tous les conteneurs contenus immédiatement dans le contexte de départ ; c’est-à-dire qu’il ne s’agit pas d’une requête approfondie. Avec cela, vous pouvez mapper la structure de l’espace d’adressage en parcourant la hiérarchie, en énumérant peut-être le contenu des conteneurs sélectionnés. Les utilisations ultérieures de WSALookupServiceBegin utilisent les conteneurs retournés par un appel précédent.

Comme mentionné ci-dessus, une structure WSAQUERYSET est utilisée comme paramètre d’entrée pour WSALookupBegin afin de qualifier la requête. Le tableau suivant indique comment WSAQUERYSET est utilisé pour construire une requête. Lorsqu’un paramètre est marqué comme (Facultatif), un pointeur NULL peut être spécifié, ce qui indique que le paramètre ne sera pas utilisé comme critère de recherche. Pour plus d’informations, consultez la section Structures de données liées aux requêtes.

Membre WSAQUERYSET	Interprétation de requête
dwSize	Doit être défini sur sizeof(WSAQUERYSET). Il s’agit d’un mécanisme de contrôle de version.
dwOutputFlags	Ignoré pour les requêtes.
lpszServiceInstanceName	(Facultatif) La chaîne référencée contient le nom du service. La sémantique du caractère générique dans la chaîne n’est pas définie, mais peut être prise en charge par certains fournisseurs d’espaces de noms.
lpServiceClassId	(Obligatoire) GUID correspondant à la classe de service.
lpVersion	(Facultatif) Référence le numéro de version souhaité et fournit une sémantique de comparaison de version (autrement dit, la version doit correspondre exactement ou la version ne doit pas être inférieure à la valeur spécifiée).
lpszComment	Ignoré pour les requêtes.
dwNameSpace Consultez la note importante qui suit.	Identificateur d’un espace de noms unique dans lequel limiter la recherche, ou NS_ALL inclure tous les espaces de noms.
lpNSProviderId	(Facultatif) Référence le GUID d’un fournisseur d’espace de noms spécifique et limite la requête à ce fournisseur uniquement.
lpszContext	(Facultatif) Spécifie le point de départ de la requête dans un espace de noms hiérarchique.
dwNumberOfProtocols	La taille du tableau de contraintes de protocole peut être égale à zéro.
lpafpProtocols	(Facultatif) Référence un tableau de structure AFPROTOCOLS . Seuls les services qui utilisent ces protocoles sont retournés.
lpszQueryString	(Facultatif) Certains espaces de noms (comme whois++) prennent en charge les requêtes enrichies de type SQL contenues dans une chaîne de texte simple. Ce paramètre est utilisé pour spécifier cette chaîne.
dwNumberOfCsAddrs	Ignoré pour les requêtes.
lpcsaBuffer	Ignoré pour les requêtes.
lpBlob	(Facultatif) Il s’agit d’un pointeur vers une entité spécifique au fournisseur.

Important Dans la plupart des cas, les applications qui s’intéressent uniquement à un protocole de transport particulier doivent limiter leur requête par famille d’adresses et par protocole plutôt que par espace de noms. Cela permettrait à une application qui doit localiser un service TCP/IP, par exemple, de faire traiter sa requête par tous les espaces de noms disponibles tels que le fichier d’hôtes locaux, DNS et NIS.

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

Windows 8.1 et Windows Server 2012 R2 : la fonction WSALookupServiceBeginW 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 winsock2.h définit WSALookupServiceBegin en tant qu’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 2003 [applications de bureau \| applications UWP]
Plateforme cible	Windows
En-tête	winsock2.h
Bibliothèque	Ws2_32.lib
DLL	Ws2_32.dll