Función WSALookupServiceBeginW (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 WSALookupServiceBeginW(
[in] LPWSAQUERYSETW 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 va a 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 mediante una llamada a WSAGetLastError.
Código de error | Significado |
---|---|
No había memoria suficiente para realizar la operación. | |
Faltaban uno o varios parámetros o no eran válidos para este proveedor. | |
El nombre se encontró en la base de datos, pero no se encontró ningún dato que coincida 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 en solo un protocolo de transporte determinado deben restringir su consulta por familia de direcciones y protocolo mediante los miembros dwNumberOfProtocols y lpafpProtocols del WSAQUERYSET en lugar de especificar el espacio de nombres en el miembro dwNameSpace .
La información sobre los protocolos de transporte de red admitidos se puede recuperar 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 local 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 espacio de nombres específico especificando un puntero al GUID para el 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 alguno, corresponde al proveedor de servicios de nombre decidir si puede admitir esta restricción sobre los contenedores. Si no es posible, debe devolver un error.
Algunos proveedores de servicios de nombre 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 buscarlos. Independientemente de lo que otro significa que el proveedor de servicios de nombre tiene para localizar 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 de contenedor. Del mismo modo, independientemente de la restricción de consulta, si se especifica 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 desde una llamada anterior.
Como se mencionó anteriormente, se usa una estructura WSAQUERYSET como parámetro de entrada para WSALookupBegin para 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 de caracteres 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
Consulte la nota importante que se indica a continuación. |
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 neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.
Requisitos
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
Comentarios
https://aka.ms/ContentUserFeedback.
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea:Enviar y ver comentarios de