WSALookupServiceBeginA, fonction (winsock2.h)
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 |
|---|---|
|
Requêtes approfondies par opposition au seul premier niveau. |
|
Retourne uniquement les conteneurs. |
|
Ne retournez pas de conteneurs. |
|
Si possible, retourne les résultats dans l’ordre de distance. La mesure de la distance est spécifique au fournisseur. |
|
Récupère le nom sous la forme lpszServiceInstanceName. |
|
Récupère le type sous la forme lpServiceClassId. |
|
Récupère la version en tant que lpVersion. |
|
Récupère le commentaire sous la forme lpszComment. |
|
Récupère les adresses en tant que lpcsaBuffer. |
|
Récupère les données privées en tant que lpBlob. |
|
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. |
|
Récupère la chaîne de requête utilisée pour la requête. |
|
Ensemble d’indicateurs qui récupère toutes les valeurs LUP_RETURN_*. |
|
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. |
|
Si le fournisseur a mis en cache des informations, ignore le cache et interroge l’espace de noms lui-même. |
|
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 |
|---|---|
| La mémoire était insuffisante pour effectuer l’opération. | |
| Un ou plusieurs paramètres étaient manquants ou non valides pour ce fournisseur. | |
| 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. | |
| Le WS2_32.DLL n’a pas été initialisé. L’application doit d’abord appeler WSAStartup avant d’appeler les fonctions windows Sockets. | |
|
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. |
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 |