WSALookupServiceBeginA, 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 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.
| Drapeau | Signification |
|---|---|
|
Requêtes approfondies par opposition au premier niveau. |
|
Retourne uniquement des conteneurs. |
|
Ne retournez pas de conteneurs. |
|
Si possible, retourne des résultats dans l’ordre de distance. La mesure de distance est spécifique au fournisseur. |
|
Récupère le nom en tant que lpszServiceInstanceName. |
|
Récupère le type en tant que lpServiceClassId. |
|
Récupère la version en tant que lpVersion. |
|
Récupère le commentaire en tant que 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 le jeu d’indicateurs RESULT_IS_ALIAS. |
|
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 passez 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 prime 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 de retour
La valeur de retour est égale à 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 donné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 des 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
Dans la plupart des cas, les applications intéressées par un protocole de transport particulier doivent limiter leur requête par famille d’adresses et par protocole à l’aide de la dwNumberOfProtocols et lpafpProtocols membres du WSAQUERYSET plutôt que de specifiyer 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 des
Il est également possible de limiter la requête à un espace de noms unique. Par exemple, une requête qui souhaite uniquement obtenir les résultats du DNS (et non des résultats du fichier hôte local et d’autres services d’affectation de noms) définirait le membre dwNameSpace sur NS_DNS. Par exemple, une découverte d’appareils bluetooth définit le membre dwNameSpace sur NS_BTH.
Les applications peuvent également restreindre la requête à un fournisseur d’espaces de noms spécifique en spécifiant un pointeur vers le GUID du fournisseur dans le lpNSProviderId membre.
Les informations sur les fournisseurs d’espaces de noms sur l’ordinateur local peuvent être récupérées à l’aide des WSAEnumNameSpaceProviders, WSAEnumNameSpaceProvidersEx, WSCEnumNameSpaceProviders32ou WSCEnumNameSpaceProvidersEx32 function.
Si LUP_CONTAINERS est spécifié dans un appel, d’autres valeurs de restriction doivent être évitées. Le cas échéant, il incombe au fournisseur de services de nom de décider s’il peut prendre en charge cette restriction sur les conteneurs. S’il ne peut pas le faire, il doit retourner une erreur.
Certains fournisseurs de services de nom peuvent avoir d’autres moyens de rechercher 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 que le fournisseur de services de noms a pour localiser des conteneurs, LUP_CONTAINERS et LUP_NOCONTAINERS précédence. Par conséquent, si une restriction de requête est donnée qui inclut des conteneurs, la spécification de LUP_NOCONTAINERS empêchera les éléments de conteneur d’être retournés. 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 d’obtention des 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 suivantes de WSALookupServiceBegin utiliser 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 le WSAQUERYSET
| Membre WSAQUERYSET | Interprétation des requêtes |
|---|---|
| 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 pour le 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érences le numéro de version souhaité et fournit une sémantique de comparaison de versions (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 d’inclure tous les espaces de noms. |
| lpNSProviderId | (Facultatif) Fait référence au GUID d’un fournisseur d’espaces 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 sont retournés. |
| lpszQueryString | (Facultatif) Certains espaces de noms (tels que whois++) prennent en charge les requêtes 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. |
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.
Note
L’en-tête winsock2.h définit WSALookupServiceBegin 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. 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.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Windows 8.1, Windows Vista [applications de bureau | Applications UWP] |
| serveur minimum pris en charge | Windows Server 2003 [applications de bureau | Applications UWP] |
| plateforme cible | Windows |
| d’en-tête | winsock2.h |
| bibliothèque | Ws2_32.lib |
| DLL | Ws2_32.dll |