NAME

dnstable_query - dnstable query objects

SYNOPSIS

#include <dnstable.h>

typedef enum {


    DNSTABLE_QUERY_TYPE_RRSET,


    DNSTABLE_QUERY_TYPE_RDATA_NAME,


    DNSTABLE_QUERY_TYPE_RDATA_IP,


    DNSTABLE_QUERY_TYPE_RDATA_RAW,


    DNSTABLE_QUERY_TYPE_TIME_RANGE,


    DNSTABLE_QUERY_TYPE_VERSION,
} dnstable_query_type;

struct dnstable_query *
dnstable_query_init(dnstable_query_type);

void
dnstable_query_destroy(struct dnstable_query **q);

const char *
dnstable_query_get_error(struct dnstable_query *q);

dnstable_res
dnstable_query_set_data(struct dnstable_query *q,


    const char *data);

dnstable_res
dnstable_query_set_rrtype(struct dnstable_query *q,


    const char *rrtype);

dnstable_res
dnstable_query_set_offset(struct dnstable_query *q,


    uint64_t offset);

dnstable_res
dnstable_query_set_aggregated(struct dnstable_query *q,


    bool aggregated);

dnstable_res
dnstable_query_set_bailiwick(struct dnstable_query *q,


    const char *bailiwick);

dnstable_res
dnstable_query_set_case_sensitive(struct dnstable_query *q,


    bool case_sensitive);

dnstable_res
dnstable_query_set_deadline(struct dnstable_query *q,


    const struct timespec *deadline);

dnstable_res
dnstable_query_set_timeout(struct dnstable_query *q,


    const struct timespec *timeout);

dnstable_res
dnstable_query_filter(struct dnstable_query *q,


    struct dnstable_entry *ent,


    bool *filter_res);

struct dnstable_iter *
dnstable_query_iter(struct dnstable_query *q,


    const struct mtbl_source *source);

DESCRIPTION

dnstable_query objects encapsulate the search parameters used when querying a dnstable data source. They can be used to retrieve specific entries from a data source, or to test whether an already retrieved entry object matches the query.

A dnstable_query object is initialized by calling dnstable_query_init(), which takes the desired query type as a parameter. The dnstable_query_set_...() functions are then called to set the query parameters, as described below.

The functions with return type dnstable_res either return dnstable_res_success if the function completely successfully, or dnstable_res_failure otherwise. If dnstable_res_failure is returned, the dnstable_query_get_error() function can be called to obtain the error message text. (The string returned is valid for the dnstable_query object in question until the next error occurs or the query object is destroyed.)

dnstable_query_filter() tests whether the given dnstable_entry object would match the given dnstable_query object. The result is returned in the filter_res parameter.

Once the query object has been constructed, dnstable_query_iter() iterates over all the matching entries in the specified mtbl source.

dnstable_query_set_...() functions

dnstable_query_set_rrtype() sets the Resource Record type, which is specified as a string. The string parameter can be an RRtype mnemonic like "A" or "NS" or it can be the string "TYPE" followed by the decimal RRtype value.

dnstable_query_set_bailiwick() is only valid for DNSTABLE_QUERY_TYPE_RRSET type queries. If set, it causes the bailiwick field of RRset entries to be filtered against the value provided.

dnstable_query_set_rrtype() and dnstable_query_set_bailiwick() are optional. If not called, no RRtype or bailiwick filtering will be performed.

dnstable_query_set_offset() sets the number of initial rows to offset (e.g. skip) from the results. The default is 0, which means to not offset any rows.

dnstable_query_set_aggregated() sets if the results from queries should be aggregated. The default is true for aggregated results.

dnstable_query_set_timeout() sets the maximum time spent in dnstable_iter_next() before returning dnstable_res_timeout.

dnstable_query_set_deadline() sets an absolute deadline after which dnstable_iter_next() will return dnstable_res_timeout.

dnstable_query_set_case_sensitive() specifies that query parameters should be treated as case-sensitive. The default is false.

For hostnames added after the call to dnstable_query_set_case_sensitive(), case is preserved.

Call to dnstable_query_set_case_sensitive() has no effect after a call to dnstable_query_set_data().

dnstable_query_set_data() specifies the main search parameter and is required. Its meaning depends on the query type.

For DNSTABLE_QUERY_TYPE_RRSET queries, the search parameter is the RRset owner name. Left- and right- hand wildcards are permitted.

For DNSTABLE_QUERY_TYPE_RDATA_NAME queries, the search parameter is the domain name in the record data. Left- and right- hand wildcards are permitted.

For DNSTABLE_QUERY_TYPE_RDATA_IP queries, the search parameter is an IP address, IP prefix, or IP range. Both IPv4 and IPv6 are supported. If the search parameter contains a "/" character it will be treated as an IP prefix. If it contains a "-" character it will be treated as an IP range. Otherwise, it will be treated as an address.

For DNSTABLE_QUERY_TYPE_RDATA_RAW queries, the search parameter is a hexadecimal string which will be directly compared against record data values.

NAME

SYNOPSIS

DESCRIPTION

dnstable_query_set_...() functions

SEE ALSO