LPNSPV2LOOKUPSERVICEBEGIN fonction de rappel (ws2spi.h)
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 |
|---|---|
|
Interroge la hiérarchie d’un fournisseur par opposition au seul premier niveau. |
|
Retourne uniquement les conteneurs. |
|
Ne retourne aucun conteneur. |
|
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 **lpServiceClassId**. |
|
Récupère la version en tant que **lpVersion**. |
|
Récupère le commentaire sous la forme **lpszComment**. |
|
Récupère les adresses sous la forme **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 à NSPv2LookupServiceNextEx, et chaque alias retourné aura l’indicateur **RESULT_IS_ALIAS***. |
|
Récupère la chaîne de requête en tant que **lpszQueryString**. |
|
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. |
|
Si le fournisseur a mis en cache des informations, ignorez le cache et interrogez l’espace de noms lui-même. |
|
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. |
|
Indique que le fournisseur d’espaces de noms doit inclure des résultats non faisant autorité pour les noms. |
|
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. |
|
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. |
|
Indique que le fournisseur d’espaces de noms doit retourner uniquement les noms préférés. |
|
Indique que le fournisseur d’espaces de noms doit retourner la configuration de l’adresse. |
|
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). |
|
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 |
|---|---|
| Un ou plusieurs paramètres n’étaient pas valides ou manquants pour ce fournisseur. | |
| 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. | |
| Le service est inconnu. Le service est introuvable dans l’espace de noms spécifié. | |
| 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 |