Función WSALookupServiceNextA (winsock2.h)

Artículo
08/27/2023

Se llama a la función WSALookupServiceNext después de obtener un identificador de una llamada anterior a WSALookupServiceBegin para recuperar la información de servicio solicitada.

El proveedor devolverá una estructura WSAQUERYSET en el búfer lpqsResults . El cliente debe seguir llamando a esta función hasta que devuelva WSA_E_NO_MORE, lo que indica que se ha devuelto todo WSAQUERYSET .

Sintaxis

INT WSAAPI WSALookupServiceNextA(
  [in]      HANDLE         hLookup,
  [in]      DWORD          dwControlFlags,
  [in, out] LPDWORD        lpdwBufferLength,
  [out]     LPWSAQUERYSETA lpqsResults
);

Parámetros

[in] hLookup

Identificador devuelto de la llamada anterior a WSALookupServiceBegin.

[in] dwControlFlags

Conjunto de marcas que controla la operación. Los valores pasados en el parámetro dwControlFlags a la función WSALookupServiceBegin determinan los criterios posibles. Los valores pasados en el parámetro dwControlFlags a la función WSALookupServiceNext restringen aún más los criterios para la búsqueda del servicio.

Actualmente, LUP_FLUSHPREVIOUS se define como un medio para hacer frente a un conjunto de resultados demasiado grande. Si una aplicación no proporciona (o no) un búfer lo suficientemente grande, al establecer LUP_FLUSHPREVIOUS se indica al proveedor que descarte el último conjunto de resultados ( que era demasiado grande) y pase al siguiente conjunto para esta llamada.

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.

[in, out] lpdwBufferLength

En la entrada, el número de bytes contenidos en el búfer al que apunta lpqsResults. En la salida, si se produce un error en la función y el error es WSAEFAULT, contiene el número mínimo de bytes que se pasarán para que lpqsResults recupere el registro.

[out] lpqsResults

Puntero a un bloque de memoria, que contendrá un conjunto de resultados en una estructura WSAQUERYSET devuelta.

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
WSA_E_CANCELLED	Se realizó una llamada a WSALookupServiceEnd mientras esta llamada seguía procesando. La llamada se ha cancelado. Los datos del búfer lpqsResults no están definidos. En Windows Sockets versión 2, los códigos de error en conflicto se definen para WSAECANCELLED (10103) y WSA_E_CANCELLED (10111). El código de error WSAECANCELLED se quitará en una versión futura y solo permanecerán WSA_E_CANCELLED. Sin embargo, para Windows Sockets versión 2, las aplicaciones deben comprobar si WSAECANCELLED y WSA_E_CANCELLED para obtener la mayor compatibilidad posible con los proveedores de espacios de nombres que usan cualquiera de ellas.
WSA_E_NO_MORE	No hay más datos disponibles. En Windows Sockets versión 2, los códigos de error en conflicto se definen para WSAENOMORE (10102) y WSA_E_NO_MORE (10110). El código de error WSAENOMORE se quitará en una versión futura y solo permanecerán WSA_E_NO_MORE. Sin embargo, para Windows Sockets versión 2, las aplicaciones deben comprobar si WSAENOMORE y WSA_E_NO_MORE para obtener la mayor compatibilidad posible con proveedores de espacio de nombres que usen cualquiera de ellas.
WSAEFAULT	El búfer lpqsResults era demasiado pequeño para contener un conjunto WSAQUERYSET .
WSAEINVAL	Uno o varios parámetros necesarios no eran válidos o faltaban.
WSA_INVALID_HANDLE	El identificador de búsqueda especificado no es válido.
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.
WSANO_DATA	El nombre se encontró en la base de datos, pero no se encontraron datos que coincidan con las restricciones especificadas.
WSA_NOT_ENOUGH_MEMORY	No había memoria suficiente para realizar la operación.

Comentarios

El parámetro dwControlFlags especificado en esta función y los especificados en el momento de WSALookupServiceBegin se tratan como restricciones para la combinación. Las restricciones se combinan entre las de WSALookupServiceBegin y las de WSALookupServiceNext . Por lo tanto, las marcas de WSALookupServiceNext nunca pueden aumentar la cantidad de datos devueltos más allá de lo que se solicitó en WSALookupServiceBegin, aunque no es un error especificar más o menos marcas. Las marcas especificadas en un WSALookupServiceNext determinado solo se aplican a esa llamada.

El LUP_FLUSHPREVIOUS dwControlFlags y LUP_RES_SERVICE son excepciones a la regla de restricciones combinadas (porque son marcas de comportamiento en lugar de marcas de restricción). Si cualquiera de estas marcas se usa en WSALookupServiceNext , tienen su efecto definido independientemente de la configuración de las mismas marcas en WSALookupServiceBegin.

Por ejemplo, si se especifica LUP_RETURN_VERSION en WSALookupServiceBegin , el proveedor de servicios recupera registros, incluida la versión. Si no se especifica LUP_RETURN_VERSION en WSALookupServiceNext, la información devuelta no incluye la versión, aunque estuviera disponible. No se genera ningún error.

Por ejemplo, si LUP_RETURN_BLOB NO se especifica en WSALookupServiceBegin , pero se especifica en WSALookupServiceNext, la información devuelta no incluye los datos privados. No se genera ningún error.

Si se produce un error en la función WSALookupServiceNext con un error de WSAEFAULT, esto indica que el búfer al que apunta el parámetro lpqsResults era demasiado pequeño para contener los resultados de la consulta. Se debe proporcionar un nuevo búfer para un WSAQUERYSET con un tamaño especificado por el valor al que apunta el parámetro lpdwBufferLength . Este nuevo búfer para WSAQUERYSET debe tener algunos de los miembros del WSAQUERYSET especificados antes de volver a llamar a la función WSALookupServiceNext . Como mínimo, el miembro dwSize del WSAQUERYSET debe establecerse en el nuevo tamaño del búfer.

Resultados de la consulta

En la tabla siguiente se describe cómo se representan los resultados de la consulta en la estructura WSAQUERYSET .

Miembro WSAQUERYSET	Interpretación de resultados
dwSize	Se establecerá en sizeof( WSAQUERYSET). Se usa como mecanismo de control de versiones.
dwOutputFlags	RESULT_IS_ALIAS marca indica que se trata de un resultado de alias.
lpszServiceInstanceName	La cadena a la que se hace referencia contiene el nombre del servicio.
lpServiceClassId	GUID correspondiente a la clase de servicio.
lpVersion	Hace referencia al número de versión de la instancia de servicio determinada.
lpszComment	Cadena de comentario opcional especificada por la instancia de servicio.
dwNameSpace	Espacio de nombres en el que se encontró la instancia de servicio.
lpNSProviderId	Identifica el proveedor de espacio de nombres específico que proporcionó este resultado de consulta.
lpszContext	Especifica el punto de contexto en un espacio de nombres jerárquico en el que se encuentra el servicio.
dwNumberOfProtocols	Sin definir para los resultados.
lpafpProtocols	Sin definir para los resultados, toda la información de protocolo necesaria se encuentra en las estructuras de CSADDR_INFO .
lpszQueryString	Cuando dwControlFlags incluye LUP_RETURN_QUERY_STRING, este parámetro devuelve el resto no preparado del lpszServiceInstanceName especificado en la consulta original. Por ejemplo, en un espacio de nombres que identifica los servicios por nombres jerárquicos que especifican un nombre de host y una ruta de acceso de archivo dentro de ese host, la dirección devuelta podría ser la dirección de host y el resto sin análisis podría ser la ruta de acceso del archivo. Si lpszServiceInstanceName está completamente analizado y se usa LUP_RETURN_QUERY_STRING, este parámetro es NULL o apunta a una cadena de longitud cero.
dwNumberOfCsAddrs	Indica el número de elementos de la matriz de estructuras de CSADDR_INFO .
lpcsaBuffer	Puntero a una matriz de estructuras de CSADDR_INFO , con una dirección de transporte completa incluida en cada elemento.
lpBlob	(Opcional) Se trata de un puntero a una entidad específica del proveedor.

Windows Phone 8: La función WSALookupServiceNextW es compatible con Windows Phone Aplicaciones de la Tienda en Windows Phone 8 y versiones posteriores.

Windows 8.1 y Windows Server 2012 R2: La función WSALookupServiceNextW 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 WSALookupServiceNext 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


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