Compartir a través de


Función WSALookupServiceBeginA (winsock2.h)

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

Consulte también

Bluetooth y WSALookupServiceBegin

EnumProtocols

WSAEnumNameSpaceProviders

WSAEnumNameSpaceProvidersEx

WSAEnumProtocols

WSALookupServiceEnd

WSALookupServiceNext

WSAQUERYSET

WSCEnumNameSpaceProviders32

WSCEnumNameSpaceProvidersEx32

WSCEnumProtocols

WSCEnumProtocols32