Compartir a través de


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

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

AFPROTOCOLS

NSPLookupServiceEnd

NSPLookupServiceNext

NSP_ROUTINE

WSAQUERYSET

WSASERVICECLASSINFO

WSASetLastError