Función de devolución de llamada LPNSPLOOKUPSERVICEBEGIN (ws2spi.h)

Artículo
08/28/2023

La función NSPLookupServiceBegin inicia una consulta de cliente de un proveedor de servicios de nombre restringido por la información contenida en una estructura WSAQUERYSET .

NSPLookupServiceBegin solo devuelve un identificador, que deben usar las llamadas posteriores a NSPLookupServiceNext para obtener los resultados reales. Dado que esta operación no se puede cancelar, se debe implementar para ejecutarse rápidamente. Aunque es aceptable iniciar una consulta de red, esta función no debe requerir una respuesta para devolverse correctamente.

Sintaxis

LPNSPLOOKUPSERVICEBEGIN Lpnsplookupservicebegin;

INT Lpnsplookupservicebegin(
  [in]  LPGUID lpProviderId,
  [in]  LPWSAQUERYSETW lpqsRestrictions,
  [in]  LPWSASERVICECLASSINFOW lpServiceClassInfo,
  [in]  DWORD dwControlFlags,
  [out] LPHANDLE lphLookup
)
{...}

Parámetros

[in] lpProviderId

Puntero al identificador del proveedor de servicios de nombre que se va a consultar.

[in] lpqsRestrictions

Puntero a los criterios de búsqueda. Vea la sección Comentarios.

[in] lpServiceClassInfo

Puntero a la estructura WSASERVICECLASSINFO que contiene información de esquema para el servicio.

[in] dwControlFlags

Valor que controla la profundidad de la búsqueda.

Value	Significado
LUP_DEEP 0x0001	Consulta la jerarquía de un proveedor en lugar de solo el primer nivel.
LUP_CONTAINERS 0x0002	Devuelve solo contenedores.
LUP_NOCONTAINERS 0x0004	No devuelve ningún contenedor.
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 NSPLookupServiceNext y cada alias devuelto tendrá establecida la marca RESULT_IS_ALIAS.
LUP_RETURN_QUERY_STRING 0x0800	Recupera la cadena de consulta como lpszQueryString.
LUP_RETURN_ALL 0x0ff0	Recupera información que incluye el nombre, el tipo, la versión, el comentario, la dirección, el blob, los alias y la cadena de consulta.
LUP_FLUSHCACHE 0x1000	Si el proveedor tiene información almacenada en caché, omita la memoria caché y consulte el propio espacio de nombres.
LUP_FLUSHPREVIOUS 0x2000	Se usa como valor para el parámetro dwControlFlags en NSPLookupServiceNext. Al establecer esta marca, se indica al proveedor que descarte el último conjunto de resultados, que era demasiado grande para el búfer proporcionado y pase al siguiente conjunto de resultados.
LUP_NON_AUTHORITATIVE 0x4000	Indica que el proveedor de espacios de nombres debe incluir resultados no autoritativos para los nombres.
LUP_RES_RESERVICE 0x8000	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. Esta opción solo se aplica a las solicitudes de instancia de servicio.
LUP_SECURE 0x8000	Indica que el proveedor de espacios de nombres debe usar una consulta segura. Esta opción solo se aplica a las solicitudes de consulta de nombre.
LUP_RETURN_PREFERRED_NAMES 0x10000	Indica que el proveedor de espacios de nombres debe devolver solo nombres preferidos.
LUP_ADDRCONFIG 0x100000	Indica que el proveedor de espacios de nombres debe devolver la configuración de la dirección.
LUP_DUAL_ADDR 0x200000	Indica que el proveedor de espacios de nombres debe devolver las direcciones duales. Esta opción solo se aplica a los sockets en modo dual (direcciones asignadas IPv6 e IPv4).

[out] lphLookup

Puntero al identificador que se va a usar en llamadas posteriores a NSPLookupServiceNext para recuperar el conjunto de resultados.

Valor devuelto

La función debe devolver NO_ERROR (cero) si la rutina se realiza correctamente. Debe devolver SOCKET_ERROR (–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_NOT_ENOUGH_MEMORY	No hay suficiente memoria disponible para realizar esta operación.
WSAEINVAL	Uno o varios parámetros no eran válidos o faltaban para este proveedor.
WSAEOPNOTSUPP	La operación no es compatible. Este error se devuelve si el proveedor de espacios de nombres no implementa esta función.
WSANO_DATA	El nombre se encontró en la base de datos, pero no tiene los datos asociados correctos para los que se resuelve.
WSASERVICE_NOT_FOUND	El servicio es desconocido. El servicio no se encuentra en el espacio de nombres especificado.

Observaciones

Si LUP_CONTAINERS se especifica en una llamada, evite todos los demás valores de restricción. Si se proporciona alguno, el proveedor de servicios de nombre debe decidir 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, todos los contenedores pueden ser de algún tipo conocido o de un conjunto de tipos conocidos y, por lo tanto, se podría crear una restricción de consulta para encontrarlos. 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 , debe devolver WSANO_DATA.

El método preferido para obtener los contenedores dentro de otro contenedor es la llamada:

dwStatus = NSPLookupServiceBegin(
    lpqsRestrictions,
    LUP_CONTAINERS,
    lphLookup);

seguido del número necesario de llamadas NSPLookupServiceNext . 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 NSPLookupServiceBegin usan los contenedores devueltos desde una llamada anterior.

Formar consultas

Como se mencionó, se usa una estructura WSAQUERYSET como parámetro de entrada para NSPLookupServiceBegin para calificar la consulta. En la tabla siguiente se enumeran los nombres de miembro WSAQUERYSET y se describe cómo se usa WSAQUERYSET para construir una consulta. Cuando un miembro se marca como (opcional) se puede proporcionar un puntero nulo, lo que indica que el parámetro no se usará como criterio de búsqueda. Para obtener más información, vea Estructuras de datos relacionadas con consultas.

Nombre del miembro WSAQUERYSET	Interpretación de consultas
dwSize	Se establecerá 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	Necesario. 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 proporcionado).
lpszComment	Se omite para las consultas.
dwNameSpace	Identificador de un único espacio de nombres en el que restringir la búsqueda o NS_ALL para 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, en bytes, del número de entradas de la matriz de restricciones de protocolo, puede ser cero.
lpafpProtocols	Opcional. Referencias a una matriz de estructuras AFPROTOCOLS . Solo se devolverán los servicios que usan estos protocolos. Se permite que el valor AF_UNSPEC aparezca como un valor de familia de protocolos, lo que significa un carácter comodín. Los proveedores de espacios de nombres pueden proporcionar información sobre cualquier servicio que use el protocolo correspondiente, independientemente de la familia de direcciones.
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. Puntero a una entidad específica del proveedor.

Requisitos


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

Consulte también

Nombre del miembro WSAQUERYSET	Interpretación de consultas
dwSize	Se establecerá 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	Necesario. 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 proporcionado).
lpszComment	Se omite para las consultas.
dwNameSpace	Identificador de un único espacio de nombres en el que restringir la búsqueda o NS_ALL para 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, en bytes, del número de entradas de la matriz de restricciones de protocolo, puede ser cero.
lpafpProtocols	Opcional. Referencias a una matriz de estructuras AFPROTOCOLS . Solo se devolverán los servicios que usan estos protocolos. Se permite que el valor AF_UNSPEC aparezca como un valor de familia de protocolos, lo que significa un carácter comodín. Los proveedores de espacios de nombres pueden proporcionar información sobre cualquier servicio que use el protocolo correspondiente, independientemente de la familia de direcciones.
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. Puntero a una entidad específica del proveedor.