Fonction de rappel LPNSPLOOKUPSERVICEBEGIN (ws2spi.h)

Article
08/28/2023

La fonction NSPLookupServiceBegin lance une requête cliente d’un fournisseur de services de nom qui est limité par les informations contenues dans une structure WSAQUERYSET .

NSPLookupServiceBegin retourne uniquement un handle, qui doit être utilisé par les appels suivants à NSPLookupServiceNext pour obtenir les résultats réels. Étant donné que cette opération ne peut pas être annulée, elle doit être implémentée pour s’exécuter rapidement. Bien qu’il soit acceptable de lancer une requête réseau, cette fonction ne doit pas nécessiter de réponse pour retourner correctement.

Syntaxe

LPNSPLOOKUPSERVICEBEGIN Lpnsplookupservicebegin;

INT Lpnsplookupservicebegin(
  [in]  LPGUID lpProviderId,
  [in]  LPWSAQUERYSETW lpqsRestrictions,
  [in]  LPWSASERVICECLASSINFOW lpServiceClassInfo,
  [in]  DWORD dwControlFlags,
  [out] LPHANDLE lphLookup
)
{...}

Paramètres

[in] lpProviderId

Pointeur vers l’identificateur du fournisseur de services de nom à interroger.

[in] lpqsRestrictions

Pointeur vers les critères de recherche. Consultez la section Notes.

[in] lpServiceClassInfo

Pointeur vers la structure WSASERVICECLASSINFO qui contient des informations de schéma pour le service.

[in] dwControlFlags

Valeur qui contrôle la profondeur de la recherche.

Valeur	Signification
LUP_DEEP 0x0001	Interroge la hiérarchie d’un fournisseur plutôt que le premier niveau.
LUP_CONTAINERS 0x0002	Retourne des conteneurs uniquement.
LUP_NOCONTAINERS 0x0004	Ne retourne aucun conteneur.
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 en tant que lpServiceClassId.
LUP_RETURN_VERSION 0x0040	Récupère la version sous la forme lpVersion.
LUP_RETURN_COMMENT 0x0080	Récupère le commentaire en tant que 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 à NSPLookupServiceNext, et chaque alias retourné aura l’indicateur RESULT_IS_ALIAS.
LUP_RETURN_QUERY_STRING 0x0800	Récupère la chaîne de requête sous la forme lpszQueryString.
LUP_RETURN_ALL 0x0ff0	Récupère des informations, notamment le nom, le type, la version, le commentaire, l’adresse, l’objet blob, les alias et la chaîne de requête.
LUP_FLUSHCACHE 0x1000	Si le fournisseur contient des informations mises en cache, ignorez le cache et interrogez l’espace de noms lui-même.
LUP_FLUSHPREVIOUS 0x2000	Utilisé comme valeur pour le paramètre dwControlFlags dans NSPLookupServiceNext. 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 fournie, et de passer au jeu de résultats suivant.
LUP_NON_AUTHORITATIVE 0x4000	Indique que le fournisseur d’espaces de noms doit inclure des résultats non faisant autorité pour les noms.
LUP_RES_RESERVICE 0x8000	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. Cette option s’applique uniquement aux demandes de instance de service.
LUP_SECURE 0x8000	Indique que le fournisseur d’espaces de noms doit utiliser une requête sécurisée. Cette option s’applique uniquement aux demandes de requête de nom.
LUP_RETURN_PREFERRED_NAMES 0x10000	Indique que le fournisseur d’espaces de noms doit retourner uniquement les noms préférés.
LUP_ADDRCONFIG 0x100000	Indique que le fournisseur d’espaces de noms doit retourner la configuration de l’adresse.
LUP_DUAL_ADDR 0x200000	Indique que le fournisseur d’espaces de noms doit retourner les adresses doubles. Cette option s’applique uniquement aux sockets double mode (adresses IPv6 et IPv4 mappées).

[out] lphLookup

Pointeur vers le handle à utiliser dans les appels suivants à NSPLookupServiceNext afin de récupérer le jeu de résultats.

Valeur retournée

La fonction doit retourner NO_ERROR (zéro) si la routine réussit. Elle doit retourner SOCKET_ERROR (–1) si la routine échoue et doit définir le code d’erreur approprié à l’aide de WSASetLastError.

Code d'erreur	Signification
WSA_NOT_ENOUGH_MEMORY	La mémoire disponible est insuffisante pour effectuer cette opération.
WSAEINVAL	Un ou plusieurs paramètres n’étaient pas valides ou manquants pour ce fournisseur.
WSAEOPNOTSUPP	L'opération n'est pas prise en charge. Cette erreur est retournée si le fournisseur d’espaces de noms n’implémente pas cette fonction.
WSANO_DATA	Le nom a été trouvé dans la base de données, mais elle n’a pas les données associées correctes pour qui est résolue.
WSASERVICE_NOT_FOUND	Le service est inconnu. Le service est introuvable dans l’espace de noms spécifié.

Remarques

Si LUP_CONTAINERS est spécifié dans un appel, évitez toutes les autres valeurs de restriction. Le cas échéant, le fournisseur de services de nom doit décider s’il peut prendre en charge cette restriction sur les conteneurs. Si ce n’est pas le cas, elle doit renvoyer 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 des 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 qu’LUP_CONTAINERS est spécifié, il doit retourner WSANO_DATA.

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

dwStatus = NSPLookupServiceBegin(
    lpqsRestrictions,
    LUP_CONTAINERS,
    lphLookup);

suivi du nombre requis d’appels NSPLookupServiceNext . 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 NSPLookupServiceBegin utilisent les conteneurs retournés à partir d’un appel précédent.

Formation de requêtes

Comme mentionné précédemment, une structure WSAQUERYSET est utilisée comme paramètre d’entrée pour NSPLookupServiceBegin pour qualifier la requête. Le tableau suivant répertorie les noms de membres WSAQUERYSET et décrit comment WSAQUERYSET est utilisé pour construire une requête. Lorsqu’un membre est marqué comme (facultatif), un pointeur null peut être fourni, ce qui indique que le paramètre ne sera pas utilisé comme critère de recherche. Pour plus d’informations, consultez Structures de données liées aux requêtes.

Nom du membre WSAQUERYSET	Interprétation de requête
dwSize	Est 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 fournie).
lpszComment	Ignoré pour les requêtes.
dwNameSpace	Identificateur d’un espace de noms unique dans lequel limiter la recherche, ou NS_ALL pour inclure tous les espaces de noms.
lpNSProviderId	facultatif. Référence le 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, en octets, du nombre d’entrées dans le tableau de contraintes de protocole, peut être égale à zéro.
lpafpProtocols	facultatif. Référence à un tableau de structures AFPROTOCOLS . Seuls les services qui utilisent ces protocoles seront retournés. Il est possible que la valeur AF_UNSPEC apparaisse en tant que valeur de famille de protocole, ce qui signifie un caractère générique. Les fournisseurs d’espaces de noms peuvent fournir des informations sur tout service qui utilise le protocole correspondant, quelle que soit la famille d’adresses.
lpszQueryString	facultatif. Certains espaces de noms (tels que whois++) prennent en charge les requêtes riches 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. Pointeur vers une entité spécifique au fournisseur.

Spécifications


Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	ws2spi.h

Voir aussi

Nom du membre WSAQUERYSET	Interprétation de requête
dwSize	Est 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 fournie).
lpszComment	Ignoré pour les requêtes.
dwNameSpace	Identificateur d’un espace de noms unique dans lequel limiter la recherche, ou NS_ALL pour inclure tous les espaces de noms.
lpNSProviderId	facultatif. Référence le 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, en octets, du nombre d’entrées dans le tableau de contraintes de protocole, peut être égale à zéro.
lpafpProtocols	facultatif. Référence à un tableau de structures AFPROTOCOLS . Seuls les services qui utilisent ces protocoles seront retournés. Il est possible que la valeur AF_UNSPEC apparaisse en tant que valeur de famille de protocole, ce qui signifie un caractère générique. Les fournisseurs d’espaces de noms peuvent fournir des informations sur tout service qui utilise le protocole correspondant, quelle que soit la famille d’adresses.
lpszQueryString	facultatif. Certains espaces de noms (tels que whois++) prennent en charge les requêtes riches 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. Pointeur vers une entité spécifique au fournisseur.

Partager via