DNS_QUERY_RAW_REQUEST structure (windns.h)

Represents a DNS raw query request (see DnsQueryRaw).

Syntax

typedef struct _DNS_QUERY_RAW_REQUEST {
  ULONG                            version;
  ULONG                            resultsVersion;
  ULONG                            dnsQueryRawSize;
  BYTE                             *dnsQueryRaw;
  PWSTR                            dnsQueryName;
  USHORT                           dnsQueryType;
  ULONG64                          queryOptions;
  ULONG                            interfaceIndex;
  DNS_QUERY_RAW_COMPLETION_ROUTINE queryCompletionCallback;
  VOID                             *queryContext;
  ULONG64                          queryRawOptions;
  ULONG                            customServersSize;
  DNS_CUSTOM_SERVER                *customServers;
  ULONG                            protocol;
  union {
    SOCKADDR_INET sourceAddr;
    CHAR          maxSa[DNS_ADDR_MAX_SOCKADDR_LENGTH];
  };
} DNS_QUERY_RAW_REQUEST;

Members

version

Type: ULONG

The version of this structure. Currently only DNS_QUERY_RAW_REQUEST_VERSION1 (0x1) exists.

resultsVersion

Type: ULONG

The requested version of the DNS_QUERY_RAW_RESULT structure returned in the completion callback. Currently only DNS_QUERY_RAW_RESULT_VERSION1 (0x1) exists.

dnsQueryRawSize

Type: ULONG

Size of the DNS raw query buffer, in bytes, pointed to by dnsQueryRaw.

dnsQueryRaw

Type: BYTE*

Pointer to the buffer containing the DNS raw query. This buffer contains the wire representation of a DNS query—a 12-byte header followed by the question section. This buffer is owned by the caller, and needs to persist only until DnsQueryRaw returns.

dnsQueryName

Type: PWSTR

Pointer to a string that represents the DNS name to query, used in conjunction with dnsQueryType. If this value is present, then it will be used instead of dnsQueryRaw.

dnsQueryType

Type: USHORT

Value that represents the DNS record type of the query, used in conjunction with dnsQueryName. These values are documented in DNS record types.

queryOptions

Type: ULONG64

Query options to be used. Makes use of the same query options from DnsQueryEx, as documented in DNS query options.

interfaceIndex

Type: ULONG

The interface index to send the query over. If 0, then all interfaces will be used.

queryCompletionCallback

Type: DNS_QUERY_RAW_COMPLETION_ROUTINE

Pointer to a callback function that will be called when the query finishes. This field is required.

queryContext

Type: VOID*

Pointer to a user context. This will be provided as a parameter in the queryCompletionCallback call. This field is required.

queryRawOptions

Type: ULONG64

Additional options to modify the raw query.

DNS_QUERY_RAW_OPTION_BEST_EFFORT_PARSE (0x1). Specifies that the raw query should be parsed in a best-effort fashion. That means that DnsQueryRaw won't fail in case of an input raw query that is formatted differently from expected (such as including new record types or header bits that the implementation isn't aware of) if it can extract out the necessary information including the query name and type. This will cause the query sent to the server to effectively be a subset of the caller's query with respect to the configuration.

customServersSize

Type: ULONG

The number of custom servers pointed to by customServers.

customServers

Type: DNS_CUSTOM_SERVER*

Pointer to an array of custom servers of size customServersSize. This pointer can be NULL, in which case customServersSize must be 0. If not NULL, then this pointer must persist until the DnsQueryRaw call returns.

protocol

Type: ULONG

The DNS protocol used for the source query in dnsQueryRaw, and what the caller expects the response to be in. You can use this to change a DNS query response to match the original query, regardless of what protocol is used by the DNS system underneath. For example, if the caller specifies UDP, and the DNS systems decides to use DNS over HTTPS (DoH), and gets a response larger than UDP allows, then the API will truncate the packet as appropriate to match the behavior of what a UDP server responds with if the result is too large. If TCP is requested by the caller, then the packet must be prefixed with the 2-byte length, as specified in section 4.2.2 of RFC 1035.

The allowed values are DNS_PROTOCOL_UDP (0x1) and DNS_PROTOCOL_TCP (0x2).

sourceAddr

Type: SOCKADDR_INET

The address of the source of the DNS raw query.

maxSa[DNS_ADDR_MAX_SOCKADDR_LENGTH]

Type: CHAR[]

The address of the source of the DNS raw query. You can use the maxSa array in code that doesn't have the SOCKADDR_INET type defined.

Requirements