Fonction de rappel LPNSPLOOKUPSERVICEBEGIN (ws2spi.h)

  • Article

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

AFPROTOCOLS

NSPLookupServiceEnd

NSPLookupServiceNext

NSP_ROUTINE

WSAQUERYSET

WSASERVICECLASSINFO

WSASetLastError