LPNSPV2LOOKUPSERVICEBEGIN función de devolución de llamada (ws2spi.h)
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 |
|---|---|
|
Consulta la jerarquía de un proveedor en lugar de solo el primer nivel. |
|
Devuelve solo contenedores. |
|
No devuelve ningún contenedor. |
|
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 NSPv2LookupServiceNextEx y cada alias devuelto tendrá establecida la marca **RESULT_IS_ALIAS**. |
|
Recupera la cadena de consulta como **lpszQueryString**. |
|
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. |
|
Si el proveedor tiene información almacenada en caché, omita la memoria caché y consulte el propio espacio de nombres. |
|
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. |
|
Indica que el proveedor de espacios de nombres debe incluir resultados no autoritativos para los nombres. |
|
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. |
|
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. |
|
Indica que el proveedor de espacios de nombres debe devolver solo los nombres preferidos. |
|
Indica que el proveedor de espacios de nombres debe devolver la configuración de la dirección. |
|
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). |
|
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 |
|---|---|
| Uno o varios parámetros no eran válidos o faltaban para este proveedor. | |
| El nombre se encontró en la base de datos, pero no tiene los datos asociados correctos para los que se resuelve. | |
| El servicio es desconocido. El servicio no se encuentra en el espacio de nombres especificado. | |
| 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 |