WSALookupServiceBeginW, fonction (winsock2.h)

La fonction WSALookupServiceBegin lance une requête cliente contrainte par les informations contenues dans une structure WSAQUERYSET . WSALookupServiceBegin retourne uniquement un handle, qui doit être utilisé par les appels suivants à WSALookupServiceNext pour obtenir les résultats réels.

Syntaxe

INT WSAAPI WSALookupServiceBeginW(
  [in]  LPWSAQUERYSETW lpqsRestrictions,
  [in]  DWORD          dwControlFlags,
  [out] LPHANDLE       lphLookup
);

Paramètres

[in] lpqsRestrictions

Pointeur vers les critères de recherche. Pour plus d’informations, consultez les remarques.

[in] dwControlFlags

Ensemble d’indicateurs qui contrôlent la profondeur de la recherche.

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.

[out] lphLookup

Handle à utiliser lors de l’appel de WSALookupServiceNext afin de commencer à récupérer le jeu de résultats.

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.

Remarques

Le paramètre lpqsRestrictions pointe vers une mémoire tampon contenant une structure WSAQUERYSET . Au minimum, le membre dwSize de WSAQUERYSET doit être défini sur la longueur de la mémoire tampon avant d’appeler la fonction WSALookupServiceBegin . Les applications peuvent restreindre la requête en spécifiant d’autres membres dans WSAQUERYSET.

Dans la plupart des cas, les applications qui s’intéressent uniquement à un protocole de transport particulier doivent limiter leur requête par la famille d’adresses et le protocole à l’aide des membres dwNumberOfProtocols et lpafpProtocols du WSAQUERYSET plutôt qu’en specifiant l’espace de noms dans le membre dwNameSpace .

Les informations sur les protocoles de transport réseau pris en charge peuvent être récupérées à l’aide de la fonction EnumProtocols, WSAEnumProtocols, WSCEnumProtocols ou WSCEnumProtocols32 .

Il est également possible de limiter la requête à un espace de noms unique. Par exemple, une requête qui souhaite uniquement des résultats du DNS (et non des résultats du fichier d’hôtes locaux et d’autres services de nommage) définit le membre dwNameSpace sur NS_DNS. Par exemple, une découverte d’appareil Bluetooth définit le membre dwNameSpace sur NS_BTH.

Les applications peuvent également restreindre la requête à un fournisseur d’espace de noms spécifique en spécifiant un pointeur vers le GUID du fournisseur dans le membre lpNSProviderId .

Les informations sur les fournisseurs d’espaces de noms sur l’ordinateur local peuvent être récupérées à l’aide de la fonction WSAEnumNameSpaceProviders, WSAEnumNameSpaceProvidersEx, WSCEnumNameSpaceProviders32 ou WSCEnumNameSpaceProvidersEx32 .

Si LUP_CONTAINERS est spécifié dans un appel, d’autres valeurs de restriction doivent être évitées. Si certaines sont spécifiées, c’est au fournisseur de services de nom de décider s’il peut prendre en charge cette restriction sur les conteneurs. Si ce n’est pas le cas, elle doit retourner 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 les 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 que LUP_CONTAINERS est spécifié, il doit simplement retourner WSANO_DATA.

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

dwStatus = WSALookupServiceBegin(
      lpqsRestrictions,
      LUP_CONTAINERS,
      lphLookup);

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

Comme mentionné ci-dessus, une structure WSAQUERYSET est utilisée comme paramètre d’entrée pour WSALookupBegin afin de qualifier la requête. Le tableau suivant indique comment WSAQUERYSET est utilisé pour construire une requête. Lorsqu’un paramètre est marqué comme (facultatif), un pointeur NULL peut être spécifié, ce qui indique que le paramètre ne sera pas utilisé comme critère de recherche. Pour plus d’informations, consultez la section Structures de données liées aux requêtes.

Windows 8.1 et Windows Server 2012 R2 : la fonction WSALookupServiceBeginW est prise en charge pour les applications du Windows Store sur Windows 8.1, Windows Server 2012 R2 et versions ultérieures.

Configuration requise

Voir aussi

Bluetooth et WSALookupServiceBegin

EnumProtocols

WSAEnumNameSpaceProviders

WSAEnumNameSpaceProvidersEx

WSAEnumProtocols

WSALookupServiceEnd

WSALookupServiceNext

WSAQUERYSET

WSCEnumNameSpaceProviders32

WSCEnumNameSpaceProvidersEx32

WSCEnumProtocols

WSCEnumProtocols32