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

  • Artículo

La función NSPv2LookupServiceBegin inicia una consulta de cliente de un proveedor de servicios de espacio de nombres version-2 restringido por la información contenida en una estructura de WSAQUERYSET2 .

Sintaxis

LPNSPV2LOOKUPSERVICEBEGIN Lpnspv2lookupservicebegin;

INT Lpnspv2lookupservicebegin(
  [in]  LPGUID lpProviderId,
  [in]  LPWSAQUERYSET2W lpqsRestrictions,
  [in]  DWORD dwControlFlags,
  [out] LPVOID lpvClientSessionArg,
  [out] LPHANDLE lphLookup
)
{...}

Parámetros

[in] lpProviderId

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

[in] lpqsRestrictions

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

[in] dwControlFlags

Conjunto de marcas que afectan a la búsqueda. Este parámetro puede ser una combinación de los siguientes valores definidos en el archivo de encabezado Winsock2.h .

Valor 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 NSPv2LookupServiceNextEx 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 NSPv2LookupServiceNextEx. 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 nombres.
LUP_RETURN_PREFERRED_NAMES
0x10000
 Indica que el proveedor de espacios de nombres debe devolver solo los 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 sockets de modo dual (direcciones asignadas IPv6 e IPv4).
LUP_DISABLE_IDN_ENCODING
0x800000
 Indica que el proveedor de espacios de nombres debe deshabilitar la codificación automática de nombres de dominio internacionales.

Este valor se admite en Windows 8 y Windows Server 2012

[out] lpvClientSessionArg

Puntero a la sesión del cliente.

[out] lphLookup

Puntero al identificador que se va a usar en llamadas posteriores a NSPv2LookupServiceNextEx 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 (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
WSAEINVAL
 Uno o varios parámetros no eran válidos o faltaban para este proveedor.
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.
WSA_NOT_ENOUGH_MEMORY
 No hay suficiente memoria disponible para realizar esta operación.

Comentarios

La función NSPv2LookupServiceBegin 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 NSPv2LookupServiceBegin solo se puede usar para las operaciones en proveedores de espacios de nombres NS_EMAIL.

La función NSPv2LookupServiceBegin solo devuelve un identificador, que deben usar las llamadas subsiguientes a NSPv2LookupServiceNextEx 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.

La función NSPv2Startup se llama cada vez que un nuevo proceso de cliente comienza a usar el proveedor de espacios de nombres. Los proveedores pueden usar el argumento de sesión de cliente al que apunta el parámetro ppvClientSessionArg para almacenar información sobre esta sesión. Si se especificó un valor para el argumento de sesión de cliente en la llamada a la función NSPv2Startup , este mismo argumento de sesión de cliente se pasa en el parámetro lpvClientSessionArg a la función NSPv2LookupServiceBegin .

Si LUP_CONTAINERS se especifica en una llamada, evite todos los demás valores de restricción. Si se proporciona alguna, 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, 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 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 de 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 , debe devolver WSANO_DATA.

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

dwStatus = NSPv2LookupServiceBegin(
    lpProviderId,
    lpqsRestrictions,
    LUP_CONTAINERS,
    lpClientSession,
    lphLookup);

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

Formación de consultas

La estructura WSAQUERYSET2 se usa como parámetro de entrada para NSPv2LookupServiceBegin para calificar la consulta. En la tabla siguiente se enumeran los nombres de miembros **WSAQUERYSET2** y se describe cómo se usa el **WSAQUERYSET2** para construir una consulta. Los miembros etiquetados como opcionales y dependientes de los requisitos del proveedor NSPv2 se pueden proporcionar como puntero **NULL** cuando no se usarán como criterios de búsqueda por parte del proveedor de espacios de nombres. Para obtener más información, consulte Estructuras de datos relacionadas con consultas.
WSAQUERYSET2 nombre de miembro Interpretación de consultas
**dwSize** Se establecerá en sizeof(WSAQUERYSET2). Se trata de un mecanismo de control de versiones.
**lpszServiceInstanceName** Cadena que 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. Este miembro es opcional, dependiendo de los requisitos del proveedor de servicios NSPv2.
**lpVersion** Número de versión deseado que 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). Este miembro es opcional, dependiendo de los requisitos del proveedor de servicios NSPv2.
**lpszComment** Este miembro se omite para las consultas.
**dwNameSpace** Identificador de un único espacio de nombres en el que se va a restringir la búsqueda o **NS_ALL** para incluir todos los espacios de nombres.
**lpNSProviderId** GUID de un proveedor de espacio de nombres específico que limita la consulta solo a este proveedor. Este miembro es opcional, dependiendo de los requisitos del proveedor de servicios NSPv2.
**lpszContext** Punto de partida de la consulta en un espacio de nombres jerárquico. Este miembro es opcional, dependiendo de los requisitos del proveedor de servicios NSPv2.
**dwNumberOfProtocols** Tamaño, en bytes, del número de entradas de la matriz de restricciones de protocolo. Este miembro puede ser cero.
**lpafpProtocols** 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 protocolo, 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. Este miembro es opcional, dependiendo de los requisitos del proveedor de servicios NSPv2.
**lpszQueryString** 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. Este miembro es opcional, dependiendo de los requisitos del proveedor de servicios NSPv2.
**dwNumberOfCsAddrs** Este miembro se omite para las consultas.
**lpcsaBuffer** Este miembro se omite para las consultas.
**dwOutputFlags** Este miembro se omite para las consultas.
**lpBlob** Puntero a una entidad específica del proveedor. Este miembro es opcional, dependiendo de los requisitos del proveedor de servicios NSPv2.

Requisitos

Requisito Value
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

AFPROTOCOLS

NSPV2_ROUTINE

NSPv2Cleanup

NSPv2ClientSessionRundown

NSPv2LookupServiceEnd

NSPv2LookupServiceNextEx

NSPv2SetServiceEx

NSPv2Startup

WSAQUERYSET2

WSASERVICECLASSINFO

WSASetLastError