Partager via


WSALookupServiceBeginW, fonction (winsock2.h)

La fonction WSALookupServiceBegin lance une requête cliente contrainte 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 WSALookupServiceBeginW(
  [in]  LPWSAQUERYSETW 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ôlent 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 des conteneurs uniquement.
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 sous la forme lpcsaBuffer.
LUP_RETURN_BLOB
0x0200
Récupère les données privées sous la forme 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 périphérique 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 de 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 s’intéressent uniquement à 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 qu’en specifiant l’espace de noms dans le membre dwNameSpace .

Les informations sur les protocoles de transport réseau pris en charge peuvent être récupérées à 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 du DNS (et non des résultats du fichier d’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. Si certaines sont spécifiées, 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, elle 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 rechercher. Quels que soient les autres moyens que le fournisseur de services de nom a 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êche le retour des éléments de 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 que 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 ; autrement dit, 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 au sein de 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) Fait référence à un tableau de structure AFPROTOCOLS . Seuls les services qui utilisent ces protocoles seront retournés.
lpszQueryString (Facultatif) Certains espaces de noms (tels que whois++) prennent en charge les requêtes de type SQL enrichies 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 protocole plutôt que par espace de noms. Cela permettrait à une application qui a besoin de localiser un service TCP/IP, par exemple, d’avoir sa requête traitée par tous les espaces de noms disponibles, tels que le fichier hôte local, DNS et NIS.
 
Windows Phone 8 : la fonction WSALookupServiceBeginW est prise en charge pour les applications du Store Windows Phone 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 comme un 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.

Configuration requise

   
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

Voir aussi

Bluetooth et WSALookupServiceBegin

EnumProtocols

WSAEnumNameSpaceProviders

WSAEnumNameSpaceProvidersEx

WSAEnumProtocols

WSALookupServiceEnd

WSALookupServiceNext

WSAQUERYSET

WSCEnumNameSpaceProviders32

WSCEnumNameSpaceProvidersEx32

WSCEnumProtocols

WSCEnumProtocols32