Compartir a través de

Función DnsQueryEx (windns.h)

  • Artículo

La función DnsQueryEx es la interfaz de consulta genérica asincrónica al espacio de nombres DNS. Proporciona a los desarrolladores de aplicaciones una interfaz de resolución de consultas DNS.

Al igual que DnsQuery, DnsQueryEx también se puede usar para realizar consultas sincrónicas en el espacio de nombres DNS.

Sintaxis

DNS_STATUS DnsQueryEx(
  [in]                PDNS_QUERY_REQUEST pQueryRequest,
  [in, out]           PDNS_QUERY_RESULT  pQueryResults,
  [in, out, optional] PDNS_QUERY_CANCEL  pCancelHandle
);

Parámetros

[in] pQueryRequest

Puntero a una estructura de DNS_QUERY_REQUEST o DNS_QUERY_REQUEST3 que contiene la información de solicitud de consulta.

Nota Al omitir la devolución de llamada DNS_QUERY_COMPLETION_ROUTINE del miembro pQueryCompleteCallback de esta estructura, DnsQueryEx se llama de forma sincrónica.
 

[in, out] pQueryResults

Puntero a una estructura de DNS_QUERY_RESULT que contiene los resultados de la consulta. En la entrada, el miembro de versión de pQueryResults debe ser DNS_QUERY_RESULTS_VERSION1 y todos los demás miembros deben ser NULL. En la salida, los miembros restantes se rellenarán como parte de la consulta completada.

Nota En el caso de las consultas asincrónicas, una aplicación no debe liberar esta estructura hasta que se invoque la devolución de llamada DNS_QUERY_COMPLETION_ROUTINE . Cuando se completa la consulta, la estructura DNS_QUERY_RESULT contiene un puntero a una lista de DNS_RECORDS que se deben liberar mediante DnsRecordListFree.
 

[in, out, optional] pCancelHandle

Puntero a una estructura de DNS_QUERY_CANCEL que se puede usar para cancelar una consulta asincrónica pendiente.

Nota Una aplicación no debe liberar esta estructura hasta que se invoque la devolución de llamada DNS_QUERY_COMPLETION_ROUTINE .
 

Valor devuelto

La función DnsQueryEx tiene los siguientes valores devueltos posibles:

Código devuelto Descripción
ERROR_SUCCESS
 La llamada se realizó correctamente.
ERROR_INVALID_PARAMETER
 Los parámetros pQueryRequest o pQueryRequest no están inicializados o contienen la versión incorrecta.
DNS RCODE
 La llamada produjo un error de RCODE .
DNS_INFO_NO_RECORDS
 No hay registros en la respuesta.
DNS_REQUEST_PENDING
 La consulta se completará de forma asincrónica.

Comentarios

Si una llamada a DnsQueryEx se completa de forma sincrónica (es decir, el valor devuelto de la función no es DNS_REQUEST_PENDING), el miembro pQueryRecords de pQueryResults contiene un puntero a una lista de DNS_RECORDS y DnsQueryEx devolverá un error o correcto.

Las condiciones siguientes invocan una llamada sincrónica a DnsQueryEx y no utilizan la devolución de llamada DNS:

  • La devolución de llamada DNS_QUERY_COMPLETION_ROUTINE se omite del miembro pQueryCompleteCallback de pQueryRequest.
  • Una consulta es para el nombre del equipo local y los registros de recursos de tipo A o AAAA (RR).
  • Una llamada a DnsQueryEx consulta una dirección IPv4 o IPv6.
  • Una llamada a DnsQueryEx devuelve un error.
Si una llamada a DnsQueryEx se completa de forma asincrónica, los resultados de la consulta se devuelven mediante la devolución de llamada DNS_QUERY_COMPLETION_ROUTINE en pQueryRequest, el miembro QueryStatus de pQueryResults contiene DNS_REQUEST_PENDING y DnsQueryEx devuelve DNS_REQUEST_PENDING. Las aplicaciones deben realizar un seguimiento de la estructura pQueryResults que se pasa a DnsQueryEx hasta que la devolución de llamada dns se realice correctamente. Las aplicaciones pueden cancelar una consulta asincrónica mediante el identificador pCancelHandle devuelto por DnsQueryEx.

pCancelHandle devuelto desde una llamada asincrónica a DnsQueryEx y pQueryContext es válido hasta que se invoca la devolución de llamada DNS de DNS_QUERY_COMPLETION_ROUTINE .

Nota Las aplicaciones reciben una notificación de finalización asincrónica de DnsQueryEx a través de la devolución de llamada DNS_QUERY_COMPLETION_ROUTINE dentro del mismo contexto de proceso.
 

Requisitos

Requisito Value
Cliente mínimo compatible Windows 8 [solo aplicaciones de escritorio]
Servidor mínimo compatible Windows Server 2012 [solo aplicaciones de escritorio]
Plataforma de destino Windows
Encabezado windns.h
Library Dnsapi.lib
Archivo DLL Dnsapi.dll

Consulte también