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 |
|---|---|
|
Consultas profundas en lugar de solo el primer nivel. |
|
Devuelve solo contenedores. |
|
No devuelva contenedores. |
|
Si es posible, devuelve resultados en el orden de distancia. La medida de distancia es específica del proveedor. |
|
Recupera el nombre como lpszServiceInstanceName. |
|
Recupera el tipo como lpServiceClassId. |
|
Recupera la versión como lpVersion. |
|
Recupera el comentario como lpszComment. |
|
Recupera las direcciones como lpcsaBuffer. |
|
Recupera los datos privados como lpBlob. |
|
Cualquier información de alias disponible se devolverá en llamadas sucesivas a WSALookupServiceNext y cada alias devuelto tendrá establecida la marca RESULT_IS_ALIAS. |
|
Recupera la cadena de consulta usada para la solicitud. |
|
Conjunto de marcas que recupera todos los valores de LUP_RETURN_*. |
|
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. |
|
Si el proveedor ha estado almacenando información en caché, omite la memoria caché y consulta el propio espacio de nombres. |
|
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 |
|---|---|
| No había memoria suficiente para realizar la operación. | |
| Faltan uno o varios parámetros o no son válidos para este proveedor. | |
| El nombre se encontró en la base de datos, pero no se encontraron datos que coincidan con las restricciones especificadas. | |
| 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. | |
|
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. |
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 |