WSALookupServiceNextA, fonction (winsock2.h)
La fonction WSALookupServiceNext est appelée après avoir obtenu un handle à partir d’un appel précédent à WSALookupServiceBegin afin de récupérer les informations de service demandées.
Le fournisseur transmet une structure WSAQUERYSET dans la mémoire tampon lpqsResults . Le client doit continuer à appeler cette fonction jusqu’à ce qu’elle retourne WSA_E_NO_MORE, indiquant que tout WSAQUERYSET a été retourné.
Syntaxe
INT WSAAPI WSALookupServiceNextA(
[in] HANDLE hLookup,
[in] DWORD dwControlFlags,
[in, out] LPDWORD lpdwBufferLength,
[out] LPWSAQUERYSETA lpqsResults
);
Paramètres
[in] hLookup
Handle retourné par l’appel précédent à WSALookupServiceBegin.
[in] dwControlFlags
Ensemble d’indicateurs qui contrôle l’opération. Les valeurs passées dans le paramètre dwControlFlags à la fonction WSALookupServiceBegin déterminent les critères possibles. Toutes les valeurs passées dans le paramètre dwControlFlags à la fonction WSALookupServiceNext limitent davantage les critères de la recherche de service.
Actuellement, LUP_FLUSHPREVIOUS est défini comme un moyen de faire face à un jeu de résultats trop volumineux. Si une application ne fournit pas (ou ne peut pas) fournir une mémoire tampon suffisamment grande, la définition LUP_FLUSHPREVIOUS indique au fournisseur d’ignorer le dernier jeu de résultats( qui était trop volumineux) et de passer au jeu suivant pour cet appel.
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. |
[in, out] lpdwBufferLength
En entrée, le nombre d’octets contenus dans la mémoire tampon pointée par lpqsResults. En sortie, si la fonction échoue et que l’erreur est WSAEFAULT, elle contient le nombre minimal d’octets à passer pour que l’objet lpqsResults récupère l’enregistrement.
[out] lpqsResults
Pointeur vers un bloc de mémoire, qui contiendra un jeu de résultats dans une structure WSAQUERYSET en retour.
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 |
|---|---|
| Un appel à WSALookupServiceEnd a été effectué pendant le traitement de cet appel. L’appel a été annulé. Les données dans la mémoire tampon lpqsResults ne sont pas définies. Dans les sockets Windows version 2, des codes d’erreur en conflit sont définis pour WSAECANCELLED (10103) et WSA_E_CANCELLED (10111). Le code d’erreur WSAECANCELLED sera supprimé dans une version ultérieure et seuls WSA_E_CANCELLED resteront. Pour les sockets Windows version 2, toutefois, les applications doivent case activée pour WSAECANCELLED et WSA_E_CANCELLED pour une compatibilité la plus large possible avec les fournisseurs d’espaces de noms qui utilisent l’un ou l’autre. | |
| Il n’y a plus de données disponibles. Dans les sockets Windows version 2, des codes d’erreur en conflit sont définis pour WSAENOMORE (10102) et WSA_E_NO_MORE (10110). Le code d’erreur WSAENOMORE sera supprimé dans une version ultérieure et seuls WSA_E_NO_MORE resteront. Pour les sockets Windows version 2, toutefois, les applications doivent case activée pour WSAENOMORE et WSA_E_NO_MORE pour une compatibilité la plus large possible avec les fournisseurs d’espace de noms qui utilisent l’un ou l’autre. | |
| La mémoire tampon lpqsResults était trop petite pour contenir un ensemble WSAQUERYSET . | |
| Un ou plusieurs paramètres requis n’étaient pas valides ou manquants. | |
| Le handle de recherche spécifié n’est pas valide. | |
| Le WS2_32.DLL n’a pas été initialisé. L’application doit d’abord appeler WSAStartup avant d’appeler les fonctions windows Sockets. | |
| 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. | |
| La mémoire était insuffisante pour effectuer l’opération. |
Remarques
Le paramètre dwControlFlags spécifié dans cette fonction et ceux spécifiés au moment de WSALookupServiceBegin sont traités comme des restrictions à des fins de combinaison. Les restrictions sont combinées entre celles à l’heure WSALookupServiceBegin et celles de WSALookupServiceNext . Par conséquent, les indicateurs de WSALookupServiceNext ne peuvent jamais augmenter la quantité de données retournées au-delà de ce qui a été demandé dans WSALookupServiceBegin, bien que ce ne soit pas une erreur pour spécifier plus ou moins d’indicateurs. Les indicateurs spécifiés dans un WSALookupServiceNext donné s’appliquent uniquement à cet appel.
Les LUP_FLUSHPREVIOUS et LUP_RES_SERVICE dwControlFlags sont des exceptions à la règle de restrictions combinées (car il s’agit d’indicateurs de comportement au lieu d’indicateurs de restriction). Si l’un de ces indicateurs est utilisé dans WSALookupServiceNext , ils ont leur effet défini quel que soit le paramètre des mêmes indicateurs dans WSALookupServiceBegin.
Par exemple, si LUP_RETURN_VERSION est spécifié dans WSALookupServiceBegin , le fournisseur de services récupère les enregistrements, y compris la version. Si LUP_RETURN_VERSION n’est PAS spécifié dans WSALookupServiceNext, les informations retournées n’incluent pas la version, même si elle était disponible. Aucune erreur n’est générée.
Par exemple, si LUP_RETURN_BLOB n’est PAS spécifié dans WSALookupServiceBegin , mais dans WSALookupServiceNext, les informations retournées n’incluent pas les données privées. Aucune erreur n’est générée.
Si la fonction WSALookupServiceNext échoue avec une erreur WSAEFAULT, cela indique que la mémoire tampon pointée par le paramètre lpqsResults était trop petite pour contenir les résultats de la requête. Une nouvelle mémoire tampon pour un WSAQUERYSET doit être fournie avec une taille spécifiée par la valeur pointée par le paramètre lpdwBufferLength . Cette nouvelle mémoire tampon pour WSAQUERYSET doit avoir certains des membres de WSAQUERYSET spécifiés avant d’appeler à nouveau la fonction WSALookupServiceNext . Au minimum, le membre dwSize de WSAQUERYSET doit être défini sur la nouvelle taille de la mémoire tampon.
Résultats de la requête
Le tableau suivant décrit comment les résultats de la requête sont représentés dans la structure WSAQUERYSET .| Membre WSAQUERYSET | Interprétation du résultat |
|---|---|
| dwSize | Sera défini sur sizeof( WSAQUERYSET). Il est utilisé comme mécanisme de contrôle de version. |
| dwOutputFlags | RESULT_IS_ALIAS indicateur indique qu’il s’agit d’un résultat d’alias. |
| lpszServiceInstanceName | La chaîne référencée contient le nom du service. |
| lpServiceClassId | GUID correspondant à la classe de service. |
| lpVersion | Référence le numéro de version du service particulier instance. |
| lpszComment | Chaîne de commentaire facultative spécifiée par le service instance. |
| dwNameSpace | Espace de noms dans lequel le service instance a été trouvé. |
| lpNSProviderId | Identifie le fournisseur d’espaces de noms spécifique qui a fourni ce résultat de requête. |
| lpszContext | Spécifie le point de contexte dans un espace de noms hiérarchique où se trouve le service. |
| dwNumberOfProtocols | Non défini pour les résultats. |
| lpafpProtocols | Non définies pour les résultats, toutes les informations de protocole nécessaires se situent dans les structures CSADDR_INFO . |
| lpszQueryString | Lorsque dwControlFlags inclut LUP_RETURN_QUERY_STRING, ce paramètre retourne le reste non évalué du lpszServiceInstanceName spécifié dans la requête d’origine. Par exemple, dans un espace de noms qui identifie les services par des noms hiérarchiques qui spécifient un nom d’hôte et un chemin de fichier dans cet hôte, l’adresse retournée peut être l’adresse de l’hôte et le reste non traité peut être le chemin du fichier. Si lpszServiceInstanceName est entièrement analysé et LUP_RETURN_QUERY_STRING est utilisé, ce paramètre a la valeur NULL ou pointe vers une chaîne de longueur nulle. |
| dwNumberOfCsAddrs | Indique le nombre d’éléments dans le tableau de structures CSADDR_INFO . |
| lpcsaBuffer | Pointeur vers un tableau de structures CSADDR_INFO , avec une adresse de transport complète contenue dans chaque élément. |
| lpBlob | (Facultatif) Il s’agit d’un pointeur vers une entité spécifique au fournisseur. |
Windows Phone 8 : La fonction WSALookupServiceNextW 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 WSALookupServiceNextW 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 WSALookupServiceNext 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
| 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 |