Función WSALookupServiceBeginA (winsock2.h)

Artículo
08/27/2023

La función WSALookupServiceBegin inicia una consulta de cliente restringida por la información contenida en una estructura WSAQUERYSET . WSALookupServiceBegin solo devuelve un identificador, que deben usar las llamadas posteriores a WSALookupServiceNext para obtener los resultados reales.

Sintaxis

INT WSAAPI WSALookupServiceBeginA(
  [in]  LPWSAQUERYSETA lpqsRestrictions,
  [in]  DWORD          dwControlFlags,
  [out] LPHANDLE       lphLookup
);

Parámetros

[in] lpqsRestrictions

Puntero a los criterios de búsqueda. Consulte la sección de comentarios para obtener más información.

[in] dwControlFlags

Conjunto de marcas que controla la profundidad de la búsqueda.

Los valores admitidos para el parámetro dwControlFlags se definen en el archivo de encabezado Winsock2.h y pueden ser una combinación de las siguientes opciones.

Marca	Significado
LUP_DEEP 0x0001	Consultas profundas en lugar de solo el primer nivel.
LUP_CONTAINERS 0x0002	Devuelve solo contenedores.
LUP_NOCONTAINERS 0x0004	No devuelva contenedores.
LUP_NEAREST 0x0008	Si es posible, devuelve resultados en el orden de distancia. La medida de distancia es específica del proveedor.
LUP_RETURN_NAME 0x0010	Recupera el nombre como lpszServiceInstanceName.
LUP_RETURN_TYPE 0x0020	Recupera el tipo como lpServiceClassId.
LUP_RETURN_VERSION 0x0040	Recupera la versión como lpVersion.
LUP_RETURN_COMMENT 0x0080	Recupera el comentario como lpszComment.
LUP_RETURN_ADDR 0x0100	Recupera las direcciones como lpcsaBuffer.
LUP_RETURN_BLOB 0x0200	Recupera los datos privados como lpBlob.
LUP_RETURN_ALIASES 0x0400	Cualquier información de alias disponible se devolverá en llamadas sucesivas a WSALookupServiceNext y cada alias devuelto tendrá establecida la marca RESULT_IS_ALIAS.
LUP_RETURN_QUERY_STRING 0x0800	Recupera la cadena de consulta usada para la solicitud.
LUP_RETURN_ALL 0x0FF0	Conjunto de marcas que recupera todos los valores de LUP_RETURN_*.
LUP_FLUSHPREVIOUS 0x1000	Se usa como valor para el parámetro dwControlFlags en WSALookupServiceNext. Al establecer esta marca, se indica al proveedor que descarte el último conjunto de resultados, que era demasiado grande para el búfer especificado y pase al siguiente conjunto de resultados.
LUP_FLUSHCACHE 0x2000	Si el proveedor ha estado almacenando información en caché, omite la memoria caché y consulta el propio espacio de nombres.
LUP_RES_SERVICE 0x8000	Esto indica si la respuesta primo está en la parte remota o local de CSADDR_INFO estructura. La otra parte debe ser utilizable en cualquier caso.

[out] lphLookup

Identificador que se usará al llamar a WSALookupServiceNext para empezar a recuperar el conjunto de resultados.

Valor devuelto

El valor devuelto es cero si la operación se realizó correctamente. De lo contrario, se devuelve el valor SOCKET_ERROR y se puede recuperar un número de error específico llamando a WSAGetLastError.

Código de error	Significado
WSA_NOT_ENOUGH_MEMORY	No había memoria suficiente para realizar la operación.
WSAEINVAL	Faltan uno o varios parámetros o no son válidos para este proveedor.
WSANO_DATA	El nombre se encontró en la base de datos, pero no se encontraron datos que coincidan con las restricciones especificadas.
WSANOTINITIALISED	No se ha inicializado el WS2_32.DLL. La aplicación debe llamar primero a WSAStartup antes de llamar a cualquier función de Windows Sockets.
WSASERVICE_NOT_FOUND	No se conoce este servicio. No se encuentra el servicio en el espacio de nombres especificado. Este error se devuelve para una solicitud de detección del servicio Bluetooth si no se encontró ningún dispositivo Bluetooth remoto.

Comentarios

El parámetro lpqsRestrictions apunta a un búfer que contiene una estructura WSAQUERYSET . Como mínimo, el miembro dwSize del WSAQUERYSET debe establecerse en la longitud del búfer antes de llamar a la función WSALookupServiceBegin . Las aplicaciones pueden restringir la consulta especificando otros miembros en WSAQUERYSET.

En la mayoría de los casos, las aplicaciones interesadas solo en un protocolo de transporte determinado deben restringir su consulta por familia de direcciones y protocolos mediante los miembros dwNumberOfProtocols y lpafpProtocols del WSAQUERYSET en lugar de especificar el espacio de nombres en el miembro dwNameSpace .

Se puede recuperar información sobre los protocolos de transporte de red compatibles mediante la función EnumProtocols, WSAEnumProtocols, WSCEnumProtocols o WSCEnumProtocols32 .

También es posible restringir la consulta a un único espacio de nombres. Por ejemplo, una consulta que solo quiere resultados de DNS (no de los resultados del archivo de hosts locales y otros servicios de nomenclatura) establecería el miembro dwNameSpace en NS_DNS. Por ejemplo, una detección de dispositivos Bluetooth establecería el miembro dwNameSpace en NS_BTH.

Las aplicaciones también pueden restringir la consulta a un proveedor de espacios de nombres específico especificando un puntero al GUID del proveedor en el miembro lpNSProviderId .

La información sobre los proveedores de espacios de nombres del equipo local se puede recuperar mediante la función WSAEnumNameSpaceProviders, WSAEnumNameSpaceProvidersEx, WSCEnumNameSpaceProviders32 o WSCEnumNameSpaceProvidersEx32 .

Si LUP_CONTAINERS se especifica en una llamada, se deben evitar otros valores de restricción. Si se especifica alguna, es necesario que el proveedor de servicios de nombre decida si puede admitir esta restricción sobre los contenedores. Si no es así, debe devolver un error.

Algunos proveedores de servicios de nombres pueden tener otros medios para buscar contenedores. Por ejemplo, los contenedores pueden ser de algún tipo conocido o de un conjunto de tipos conocidos y, por lo tanto, se puede crear una restricción de consulta para encontrarlos. Independientemente de lo que otro significa que el proveedor de servicios de nombres tiene para buscar contenedores, LUP_CONTAINERS y LUP_NOCONTAINERS tienen prioridad. Por lo tanto, si se da una restricción de consulta que incluye contenedores, especificar LUP_NOCONTAINERS impedirá que se devuelvan los elementos del contenedor. Del mismo modo, independientemente de la restricción de consulta, si se da LUP_CONTAINERS, solo se deben devolver contenedores. Si un espacio de nombres no admite contenedores y se especifica LUP_CONTAINERS, simplemente debe devolver WSANO_DATA.

El método preferido para obtener los contenedores dentro de otro contenedor es la llamada:

dwStatus = WSALookupServiceBegin(
      lpqsRestrictions,
      LUP_CONTAINERS,
      lphLookup);

Esta llamada va seguida del número necesario de llamadas WSALookupServiceNext . Esto devolverá todos los contenedores contenidos inmediatamente dentro del contexto inicial; es decir, no es una consulta profunda. Con esto, se puede asignar la estructura del espacio de direcciones caminando por la jerarquía, quizás enumerando el contenido de los contenedores seleccionados. Los usos posteriores de WSALookupServiceBegin usan los contenedores devueltos de una llamada anterior.

Como se mencionó anteriormente, se usa una estructura WSAQUERYSET como parámetro de entrada para WSALookupBegin con el fin de calificar la consulta. En la tabla siguiente se indica cómo se usa WSAQUERYSET para construir una consulta. Cuando se marca un parámetro como (opcional) se puede especificar un puntero NULL , lo que indica que el parámetro no se usará como criterio de búsqueda. Consulte la sección Estructuras de datos relacionadas con consultas para obtener información adicional.

Miembro WSAQUERYSET	Interpretación de consultas
dwSize	Debe establecerse en sizeof(WSAQUERYSET). Se trata de un mecanismo de control de versiones.
dwOutputFlags	Se omite para las consultas.
lpszServiceInstanceName	(Opcional) La cadena a la que se hace referencia contiene el nombre del servicio. La semántica para el carácter comodín dentro de la cadena no está definida, pero puede ser compatible con determinados proveedores de espacios de nombres.
lpServiceClassId	(Obligatorio) GUID correspondiente a la clase de servicio.
lpVersion	(Opcional) Hace referencia al número de versión deseado y proporciona semántica de comparación de versiones (es decir, la versión debe coincidir exactamente o la versión no debe ser menor que el valor especificado).
lpszComment	Se omite para las consultas.
dwNameSpace Vea la nota importante que sigue.	Identificador de un único espacio de nombres en el que restringir la búsqueda o NS_ALL incluir todos los espacios de nombres.
lpNSProviderId	(Opcional) Hace referencia al GUID de un proveedor de espacio de nombres específico y limita la consulta solo a este proveedor.
lpszContext	(Opcional) Especifica el punto inicial de la consulta en un espacio de nombres jerárquico.
dwNumberOfProtocols	El tamaño de la matriz de restricciones de protocolo puede ser cero.
lpafpProtocols	(Opcional) Hace referencia a una matriz de la estructura AFPROTOCOLS . Solo se devolverán los servicios que usan estos protocolos.
lpszQueryString	(Opcional) Algunos espacios de nombres (como whois++) admiten consultas enriquecidas de tipo SQL contenidas en una cadena de texto simple. Este parámetro se usa para especificar esa cadena.
dwNumberOfCsAddrs	Se omite para las consultas.
lpcsaBuffer	Se omite para las consultas.
lpBlob	(Opcional) Se trata de un puntero a una entidad específica del proveedor.

Importante En la mayoría de los casos, las aplicaciones interesadas solo en un protocolo de transporte determinado deben restringir su consulta por familia de direcciones y protocolos en lugar de por espacio de nombres. Esto permitiría que una aplicación que necesite localizar un servicio TCP/IP, por ejemplo, que todas las consultas estén procesadas por todos los espacios de nombres disponibles, como el archivo de hosts locales, DNS y NIS.

Windows Phone 8: La función WSALookupServiceBeginW es compatible con las aplicaciones de Windows Phone Store en Windows Phone 8 y versiones posteriores.

Windows 8.1 y Windows Server 2012 R2: la función WSALookupServiceBeginW es compatible con las aplicaciones de la Tienda Windows en Windows 8.1, Windows Server 2012 R2 y versiones posteriores.

Nota

El encabezado winsock2.h define WSALookupServiceBegin como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutro de codificación con código que no es neutral de codificación puede provocar discrepancias que dan lugar a errores de compilación o en tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 8.1, Windows Vista [aplicaciones de escritorio \| Aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2003 [aplicaciones de escritorio \| aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	winsock2.h
Library	Ws2_32.lib
Archivo DLL	Ws2_32.dll