LPNSPV2LOOKUPSERVICEBEGIN fonction de rappel (ws2spi.h)

Article
08/28/2023

La fonction NSPv2LookupServiceBegin lance une requête cliente d’un fournisseur de services d’espace de noms version 2 qui est limitée par les informations contenues dans une structure de WSAQUERYSET2.

Syntaxe

LPNSPV2LOOKUPSERVICEBEGIN Lpnspv2lookupservicebegin;

INT Lpnspv2lookupservicebegin(
  [in]  LPGUID lpProviderId,
  [in]  LPWSAQUERYSET2W lpqsRestrictions,
  [in]  DWORD dwControlFlags,
  [out] LPVOID lpvClientSessionArg,
  [out] LPHANDLE lphLookup
)
{...}

Paramètres

[in] lpProviderId

Pointeur vers l’identificateur du fournisseur de services d’espace de noms à interroger.

[in] lpqsRestrictions

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

[in] dwControlFlags

Ensemble d’indicateurs qui affectent la recherche. Ce paramètre peut être une combinaison des valeurs suivantes définies dans le fichier d’en-tête Winsock2.h .

Valeur	Signification
LUP_DEEP 0x0001	Interroge la hiérarchie d’un fournisseur par opposition au seul premier niveau.
LUP_CONTAINERS 0x0002	Retourne uniquement les conteneurs.
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 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 en tant que lpBlob.
LUP_RETURN_ALIASES 0x0400	Toutes les informations d’alias disponibles doivent être retournées dans les appels successifs à NSPv2LookupServiceNextEx, et chaque alias retourné aura l’indicateur RESULT_IS_ALIAS*.
LUP_RETURN_QUERY_STRING 0x0800	Récupère la chaîne de requête en tant que 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 a mis en cache des informations, ignorez le cache et interrogez l’espace de noms lui-même.
LUP_FLUSHPREVIOUS 0x2000	Utilisé comme valeur pour le paramètre dwControlFlags dans NSPv2LookupServiceNextEx. 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 en mode double (adresses mappées IPv6 et IPv4).
LUP_DISABLE_IDN_ENCODING 0x800000	Indique que le fournisseur d’espaces de noms doit désactiver l’encodage automatique des noms de domaine internationaux. Cette valeur est prise en charge sur Windows 8 et Windows Server 2012

[out] lpvClientSessionArg

Pointeur vers la session cliente.

[out] lphLookup

Pointeur vers le handle à utiliser dans les appels suivants à NSPv2LookupServiceNextEx 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. Il doit retourner SOCKET_ERROR (c’est-à-dire 1) si la routine échoue et il doit définir le code d’erreur approprié à l’aide de WSASetLastError.

Code d'erreur	Signification
WSAEINVAL	Un ou plusieurs paramètres n’étaient pas valides ou manquants pour ce fournisseur.
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é.
WSA_NOT_ENOUGH_MEMORY	La mémoire disponible est insuffisante pour effectuer cette opération.

Remarques

La fonction NSPv2LookupServiceBegin est utilisée dans le cadre de l’architecture du fournisseur de services d’espace de noms version 2 (NSPv2) disponible sur Windows Vista et versions ultérieures.

Sur Windows Vista et Windows Server 2008, la fonction NSPv2LookupServiceBegin ne peut être utilisée que pour les opérations sur NS_EMAIL fournisseurs d’espaces de noms.

La fonction NSPv2LookupServiceBegin retourne uniquement un handle, qui doit être utilisé par les appels suivants à NSPv2LookupServiceNextEx 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 d’initier une requête réseau, cette fonction ne doit pas nécessiter de réponse pour retourner correctement.

La fonction NSPv2Startup est appelée chaque fois qu’un nouveau processus client commence à utiliser le fournisseur d’espaces de noms. Les fournisseurs peuvent utiliser l’argument de session client pointé vers le paramètre ppvClientSessionArg pour stocker des informations sur cette session. Si une valeur a été spécifiée pour l’argument de session cliente dans l’appel à la fonction NSPv2Startup , ce même argument de session client est passé dans le paramètre lpvClientSessionArg à la fonction NSPv2LookupServiceBegin .

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 = NSPv2LookupServiceBegin(
    lpProviderId,
    lpqsRestrictions,
    LUP_CONTAINERS,
    lpClientSession,
    lphLookup);

suivi du nombre requis d’appels NSPv2LookupServiceNextEx . 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 NSPv2LookupServiceBegin utilisent les conteneurs retournés par un appel précédent.

Formation de requêtes

La structure WSAQUERYSET2 est utilisée comme paramètre d’entrée dans NSPv2LookupServiceBegin pour qualifier la requête. Le tableau suivant répertorie les noms de membres **WSAQUERYSET2** et décrit comment le **WSAQUERYSET2** est utilisé pour construire une requête. Les membres étiquetés comme facultatifs et dépendant des exigences du fournisseur NSPv2 peuvent être fournis en tant que pointeur **NULL** lorsqu’ils ne sont pas utilisés comme critère de recherche par le fournisseur d’espaces de noms. Pour plus d’informations, consultez Structures de données liées aux requêtes.

WSAQUERYSET2 nom du membre	Interprétation de requête
dwSize	Sera défini sur sizeof(WSAQUERYSET2). Il s’agit d’un mécanisme de contrôle de version.
lpszServiceInstanceName	Chaîne qui 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. Ce membre est facultatif, dépendant des exigences du fournisseur de services NSPv2.
lpVersion	Numéro de version souhaité qui fournit la sémantique de comparaison des versions (autrement dit, la version doit correspondre exactement ou la version ne doit pas être inférieure à la valeur fournie). Ce membre est facultatif, dépendant des exigences du fournisseur de services NSPv2.
lpszComment	Ce membre est 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	GUID d’un fournisseur d’espace de noms spécifique qui limite la requête à ce fournisseur uniquement. Ce membre est facultatif, dépendant des exigences du fournisseur de services NSPv2.
lpszContext	Point de départ de la requête dans un espace de noms hiérarchique. Ce membre est facultatif, dépendant des exigences du fournisseur de services NSPv2.
dwNumberOfProtocols	Taille, en octets, du nombre d’entrées dans le tableau de contraintes de protocole. Ce membre peut être égal à zéro.
lpafpProtocols	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. Ce membre est facultatif, dépendant des exigences du fournisseur de services NSPv2.
lpszQueryString	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. Ce membre est facultatif, dépendant des exigences du fournisseur de services NSPv2.
dwNumberOfCsAddrs	Ce membre est ignoré pour les requêtes.
lpcsaBuffer	Ce membre est ignoré pour les requêtes.
dwOutputFlags	Ce membre est ignoré pour les requêtes.
lpBlob	Pointeur vers une entité spécifique au fournisseur. Ce membre est facultatif, dépendant des exigences du fournisseur de services NSPv2.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2008 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	ws2spi.h

Voir aussi

AFPROTOCOLS

NSPV2_ROUTINE

NSPv2Cleanup

NSPv2ClientSessionRundown

NSPv2LookupServiceEnd

NSPv2LookupServiceNextEx

WSAQUERYSET2 nom du membre	Interprétation de requête
dwSize	Sera défini sur sizeof(WSAQUERYSET2). Il s’agit d’un mécanisme de contrôle de version.
lpszServiceInstanceName	Chaîne qui 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. Ce membre est facultatif, dépendant des exigences du fournisseur de services NSPv2.
lpVersion	Numéro de version souhaité qui fournit la sémantique de comparaison des versions (autrement dit, la version doit correspondre exactement ou la version ne doit pas être inférieure à la valeur fournie). Ce membre est facultatif, dépendant des exigences du fournisseur de services NSPv2.
lpszComment	Ce membre est 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	GUID d’un fournisseur d’espace de noms spécifique qui limite la requête à ce fournisseur uniquement. Ce membre est facultatif, dépendant des exigences du fournisseur de services NSPv2.
lpszContext	Point de départ de la requête dans un espace de noms hiérarchique. Ce membre est facultatif, dépendant des exigences du fournisseur de services NSPv2.
dwNumberOfProtocols	Taille, en octets, du nombre d’entrées dans le tableau de contraintes de protocole. Ce membre peut être égal à zéro.
lpafpProtocols	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. Ce membre est facultatif, dépendant des exigences du fournisseur de services NSPv2.
lpszQueryString	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. Ce membre est facultatif, dépendant des exigences du fournisseur de services NSPv2.
dwNumberOfCsAddrs	Ce membre est ignoré pour les requêtes.
lpcsaBuffer	Ce membre est ignoré pour les requêtes.
dwOutputFlags	Ce membre est ignoré pour les requêtes.
lpBlob	Pointeur vers une entité spécifique au fournisseur. Ce membre est facultatif, dépendant des exigences du fournisseur de services NSPv2.

Partager via