LPNSPV2LOOKUPSERVICENEXTEX función de devolución de llamada (ws2spi.h)

Artículo
08/28/2023

Se llama a la función NSPv2LookupServiceNextEx después de obtener un identificador de una llamada anterior a NSPv2LookupServiceBegin para recuperar la información solicitada de un proveedor de servicios de espacio de nombres version-2.

Sintaxis

LPNSPV2LOOKUPSERVICENEXTEX Lpnspv2lookupservicenextex;

void Lpnspv2lookupservicenextex(
  [in]      HANDLE hAsyncCall,
  [in]      HANDLE hLookup,
  [in]      DWORD dwControlFlags,
  [in, out] LPDWORD lpdwBufferLength,
  [out]     LPWSAQUERYSET2W lpqsResults
)
{...}

Parámetros

[in] hAsyncCall

Identificador devuelto de la llamada anterior a NSPv2LookupServiceBegin usado para llamadas asincrónicas.

[in] hLookup

Identificador devuelto de la llamada anterior a NSPv2LookupServiceBegin.

[in] dwControlFlags

Marcas usadas para controlar la siguiente operación. Actualmente, solo LUP_FLUSHPREVIOUS se define como un medio para controlar un conjunto de resultados demasiado grande. Si una aplicación no puede proporcionar un búfer suficientemente grande, al establecer LUP_FLUSHPREVIOUS se indica al proveedor que descarte el último conjunto de resultados, que era demasiado grande y pasar al siguiente conjunto para esta llamada.

[in, out] lpdwBufferLength

Tamaño, en bytes, en entrada, contenido 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 tamaño mínimo, en bytes para pasar para que lpqsResults recupere el registro.

[out] lpqsResults

Puntero a un bloque de memoria que contendrá, al devolver, un conjunto de resultados en una estructura de WSAQUERYSET2 .

Valor devuelto

La función debe devolver NO_ERROR (cero) si la rutina se realiza correctamente. Debe devolver SOCKET_ERROR (es decir, 1) si se produce un error en la rutina y debe establecer el código de error adecuado mediante WSASetLastError.

Código de error	Significado
WSA_E_CANCELLED	Se realizó una llamada a NSPv2LookupServiceEnd mientras esta llamada todavía se estaba procesando. La llamada se ha cancelado. Los datos del búfer lpqsResults no están definidos. En Windows Sockets 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 WSA_E_CANCELLED permanecerá. Los proveedores de espacios de nombres deben usar el código de error WSA_E_CANCELLED para mantener la compatibilidad con la gama de aplicaciones más amplia posible.
WSA_E_NO_MORE	No hay más datos disponibles. En Windows Sockets 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á WSA_E_NO_MORE. Los proveedores de espacios de nombres deben usar el código de error WSA_E_NO_MORE para mantener la compatibilidad con la gama de aplicaciones más amplia posible.
WSAEFAULT	El búfer lpqsResults era demasiado pequeño para contener un conjunto WSAQUERYSET .
WSAEINVAL	Uno o varios parámetros no son válidos o faltan para este proveedor.
WSA_INVALID_HANDLE	El identificador de búsqueda especificado no es válido.
WSANO_DATA	El nombre se encontró en la base de datos, pero no se encontró ningún dato, que coincida con las restricciones especificadas.
WSASERVICE_NOT_FOUND	El servicio es desconocido. El servicio no se encuentra en el espacio de nombres especificado.
WSA_NOT_ENOUGH_MEMORY	No hay suficiente memoria disponible para realizar esta operación.

Observaciones

La función NSPv2LookupServiceNextEx se usa como parte de la arquitectura del proveedor de servicios de espacio de nombres versión 2 (NSPv2) disponible en Windows Vista y versiones posteriores.

En Windows Vista y Windows Server 2008, la función NSPv2LookupServiceNextEx solo se puede usar para las operaciones en proveedores de espacios de nombres NS_EMAIL.

El proveedor pasará una estructura de WSAQUERYSET2 en el búfer lpqsResults . El cliente debe llamar a la función NSPv2LookupServiceNextEx hasta que devuelva WSA_E_NOMORE, lo que indica que se han devuelto todas las estructuras de WSAQUERYSET2 .

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

El LUP_FLUSHPREVIOUSdwControlFlags 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 se usa cualquiera de las marcas en NSPv2LookupServiceNextEx, tienen su efecto definido independientemente de la configuración de las mismas marcas en NSPv2LookupServiceBegin.

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

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

La función NSPv2LookupServiceNextEx suele llamarse al menos dos veces. La primera vez que se obtiene el tamaño del búfer necesario para recibir el WSAQUERYSET2 apuntado por el parámetro lpqsResults y la segunda vez para obtener el conjunto de resultados de la consulta real. En la primera llamada, el proveedor NSPv2 debe devolver el tamaño necesario para los resultados de WSAQUERYSET2 .

La estructura de WSAQUERYSET2 a la que apunta el parámetro lpqsResults que se devuelve solo es útil en el mismo contexto de proceso, ya que varios de los miembros de la estructura WSAQUERYSET2 contienen punteros a los datos reales devueltos. Si el resultado de la consulta debe pasarse a otro proceso (mediante RPC, por ejemplo), será necesario serializar y serializar los datos devueltos en la estructura de WSAQUERYSET2 apuntado por el parámetro lpqsResults , incluidos los datos a los que apuntan los miembros de la estructura WSAQUERYSET2 . Los datos deben serializarse en un formulario que se pueda pasar a través de los límites del proceso. Simplemente pasar una copia de la estructura de WSAQUERYSET2 no es suficiente, ya que solo se pasarán punteros a los datos y los datos reales no estarán disponibles para otros procesos.

Resultados de la consulta

En la tabla siguiente se enumeran WSAQUERYSET2 y se describe cómo se representan los resultados de la consulta en la estructura **WSAQUERYSET2**. Para obtener más información, consulte Estructuras de datos relacionadas con consultas.

WSAQUERYSET2 nombre de miembro	Interpretación de resultados
dwSize	Tamaño, en bytes, de WSAQUERYSET2 estructura. Se usa como mecanismo de control de versiones.
lpszServiceInstanceName	Cadena que contiene el nombre del servicio.
lpVersion	Hace referencia al número de versión de la instancia de servicio determinada.
lpszComment	Cadena de comentario proporcionada por la instancia de servicio. Este miembro es opcional, dependiendo de los requisitos del proveedor de servicios NSPv2.
dwNameSpace	Identificador del espacio de nombres en el que se encontró el nombre o la instancia de servicio.
lpNSProviderId	Proveedor de espacio de nombres específico que proporcionó este resultado de consulta.
lpszContext	Punto de contexto de un espacio de nombres jerárquico en el que se encuentra el servicio.
dwNumberOfProtocols	Este miembro no está definido para los resultados.
lpafpProtocols	Este miembro no está definido 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 miembro devuelve el resto sin consultar 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 se analiza completamente lpszServiceInstanceName y se usa LUP_RETURN_QUERY_STRING, este miembro es null o apunta a una cadena de longitud cero.
dwNumberOfCsAddrs	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.
dwOutputFlags	La marca RESULT_IS_ALIAS indica que se trata de un resultado de alias.
lpBlob	Puntero a una entidad específica del proveedor. Este miembro es opcional, dependiendo de los requisitos del proveedor de servicios NSPv2.

Requisitos


Cliente mínimo compatible	Windows Vista [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2008 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	ws2spi.h

Consulte también

CSADDR_INFO

NSPV2_ROUTINE

NSPv2Cleanup

NSPv2ClientSessionRundown

NSPv2LookupServiceBegin

NSPv2LookupServiceEnd

WSAQUERYSET2 nombre de miembro	Interpretación de resultados
dwSize	Tamaño, en bytes, de WSAQUERYSET2 estructura. Se usa como mecanismo de control de versiones.
lpszServiceInstanceName	Cadena que contiene el nombre del servicio.
lpVersion	Hace referencia al número de versión de la instancia de servicio determinada.
lpszComment	Cadena de comentario proporcionada por la instancia de servicio. Este miembro es opcional, dependiendo de los requisitos del proveedor de servicios NSPv2.
dwNameSpace	Identificador del espacio de nombres en el que se encontró el nombre o la instancia de servicio.
lpNSProviderId	Proveedor de espacio de nombres específico que proporcionó este resultado de consulta.
lpszContext	Punto de contexto de un espacio de nombres jerárquico en el que se encuentra el servicio.
dwNumberOfProtocols	Este miembro no está definido para los resultados.
lpafpProtocols	Este miembro no está definido 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 miembro devuelve el resto sin consultar 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 se analiza completamente lpszServiceInstanceName y se usa LUP_RETURN_QUERY_STRING, este miembro es null o apunta a una cadena de longitud cero.
dwNumberOfCsAddrs	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.
dwOutputFlags	La marca RESULT_IS_ALIAS indica que se trata de un resultado de alias.
lpBlob	Puntero a una entidad específica del proveedor. Este miembro es opcional, dependiendo de los requisitos del proveedor de servicios NSPv2.