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_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_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