[adns] / src / adns.h

/**/

#ifndef ADNS_H_INCLUDED
#define ADNS_H_INCLUDED

#include <sys/socket.h>
#include <netinet/in.h>

typedef struct adns__state *adns_state;
typedef struct adns__query *adns_query;

typedef enum {
  adns_if_noenv=      0x0001, /* do not look at environment */
  adns_if_noerrprint= 0x0002, /* never print output to stderr */
  adns_if_debug=      0x0004, /* print debugging output to stderr */
} adns_initflags;

typedef enum {
  adns_f_search=     0x0001, /* use the searchlist */
  adns_f_usevc=      0x0002, /* use a virtual circuit (TCP connection) */
  adns_f_anyquote=   0x0004,
} adns_queryflags;

typedef enum {
  adns__rrttype_mask=  0x0fff,
  adns__qtf_deref=     0x1000, /* dereference domains and produce extra data */
  adns__qtf_mailconv=  0x2000, /* put @ between first and second labels */
  adns_r_none=              0,
  adns_r_a=                 1,
  adns_r_ns_raw=            2,
  adns_r_ns=                   adns_r_ns_raw|adns__qtf_deref,
  adns_r_cname=             5,
  adns_r_soa_raw=           6,
  adns_r_soa=                  adns_r_soa_raw|adns__qtf_mailconv,
  adns_r_null=             10,
  adns_r_ptr_raw=          12,
  adns_r_ptr=                  adns_r_ptr_raw|adns__qtf_deref,
  adns_r_hinfo=            13,  
  adns_r_mx_raw=           15,
  adns_r_mx=                   adns_r_mx_raw|adns__qtf_deref,
  adns_r_txt=              16,
  adns_r_rp_raw=           17,
  adns_r_rp=                   adns_r_rp_raw|adns__qtf_mailconv
} adns_rrtype;

/* In queries without qtf_anyquote, all domains must have standard
 * legal syntax.  In queries _with_ qtf_anyquote, domains in the query
 * or response may contain any characters, quoted according to
 * RFC1035 5.1.  On input to adns, the char* is a pointer to the
 * interior of a " delimited string, except that " may appear in it,
 * and on output, the char* is a pointer to a string which would be
 * legal either inside or outside " delimiters, and any characters
 * not usually legal in domain names will be quoted as \X
 * (if the character is 33-126 except \ and ") or \DDD.
 *
 * Do not ask for records containing mailboxes without
 * specifying qtf_mailconv or qtf_anyquote.
 */

typedef enum {
  adns_s_ok,
  adns_s_notresponding,
  adns_s_serverfailure,
  adns_s_unknownqtype,
  adns_s_remoteerror,
  adns_s_max_tempfail= 99,
  adns_s_nxdomain,
  adns_s_norecord,
  adns_s_invaliddomain
} adns_status;

/* In dereferenced answers, multiple addresses show up as multiple
 * answers with all the dm pointers being the same.  If no
 * address is available (permanent failure) then INADDR_NONE is
 * used.
 */

struct adns_answer {
  adns_status status;
  char *cname; /* always NULL if query was for CNAME records */
  adns_rrtype type;
  int nrrs;
  union {
    struct in_addr inaddr[1];                                          /* a */
    char (*str)[1];                     /* ns_raw, cname, ptr, ptr_raw, txt */
    struct { char *dm; struct in_addr addr; } dmaddr;                 /* ns */
    struct { char *a, *b; } strpair[1];                /* hinfo, rp, rp_raw */
    struct { int pref; char *dm; struct in_addr addr; } intdmaddr[1]; /* mx */
    struct { int pref; char *str; } intstr[1]; /* mx_raw */
    struct {
      char *ns0, *rp;
      unsigned long serial, refresh, retry, expire, minimum;
    } soa[1]; /* soa, soa_raw */
    /* NULL is empty */
  } rrs;
};

/* Memory management:
 *  adns_state and adns_query are actually pointers to malloc'd state;
 *  On submission questions are copied, including the owner domain;
 *  Answers are malloc'd as a single piece of memory.
 * query_io:
 *  Must always be non-null pointer;
 *  If *query_io is 0 to start with then any query may be returned;
 *  If *query_io is !0 adns_query then only that query may be returned.
 * Errors:
 *  Return values are 0 or an errno value;
 *  Seriously fatal system errors (eg, failure to create sockets,
 *  malloc failure, etc.) return errno values;
 *  Other errors (nameserver failure, timed out connections, &c)
 *  are returned in the status field of the answer.  If status is
 *  nonzero then nrrs will be 0, otherwise it will be >0.
 *  type will always be the type requested;
 *  If no (appropriate) requests are done adns_query returns EWOULDBLOCK;
 *  If no requests are outstanding adns_query and adns_wait return ESRCH;
 *  If malloc failure occurs during internal allocation or processing
 *  ands_query, _wait and _answer set *answer to 0.
 */

int adns_init(adns_state *newstate_r, adns_initflags flags);

int adns_synchronous(adns_state ads,
		     const char *owner,
		     adns_rrtype type,
		     int flags,
		     struct adns_answer *answer);

int adns_submit(adns_state ads,
		const char *owner,
		adns_rrtype type,
		int flags,
		void *context,
		adns_query *query_r);

int adns_check(adns_state ads,
	       adns_query *query_io,
	       struct adns_answer *answer,
	       void *context_r);

int adns_wait(adns_state ads,
	      adns_query *query_io,
	      struct adns_answer *answer,
	      void *context_r);

int adns_cancel(adns_state ads, adns_query query);

int adns_finish(adns_state);

void adns_interest(adns_state, fd_set *readfds_mod,
		   fd_set *writefds_mod, fd_set *exceptfds_mod,
		   int *maxfd_mod, struct timeval **tv_mod, struct timeval *tv_buf);
/* You may call this with *_mod=0 to allow adns to have flow-of-control
 * briefly, or with *fds_mod=*maxfd_mod=0 but tv_mod!=0 if you are
 * not going to sleep, or with all !=0 if you are going to sleep.
 * If tv_mod!=0 and *tv_mod=0 then tv_buf must be !0 and *tv_buf is irrelevant
 * and may be overwritten (and *tv_mod set to tv_buf); otherwise tv_buf is ignored.
 */

int adns_callback(adns_state, fd_set readfds, fd_set writefds,
		  fd_set exceptfds, int maxfd);
/* For select-driven programs, this allows adns to know which fd's are relevant,
 * so that it doesn't need to make syscalls on others of its fd's.  It's a kind
 * of limited flow-of-control allowance.  It will return how many adns fd's were
 * in the set, so you can tell if your select handling code is missing things.
 */

/* Example expected/legal calling sequences:
 *  adns_init
 *  adns_submit 1
 *  adns_submit 2
 *  adns_submit 3
 *  adns_wait 1
 *  adns_check 3 -> EWOULDBLOCK
 *  adns_wait 2
 *  adns_wait 3
 *  ....
 *  adns_finish
 *
 *  adns_init
 *  adns_submit ...
 *  loop {
 *   adns_check
 *   adns_interest
 *   select
 *   adns_callback
 *   other things
 *  }
 */

#endif
Commit	Line	Data
a17d3a1d	1	/**/
	2
	3	#ifndef ADNS_H_INCLUDED
	4	#define ADNS_H_INCLUDED
	5
964344fc	6	#include <sys/socket.h>
	7	#include <netinet/in.h>
	8
	9	typedef struct adns__state *adns_state;
	10	typedef struct adns__query *adns_query;
a17d3a1d	11
	12	typedef enum {
	13	adns_if_noenv= 0x0001, /* do not look at environment */
	14	adns_if_noerrprint= 0x0002, /* never print output to stderr */
	15	adns_if_debug= 0x0004, /* print debugging output to stderr */
	16	} adns_initflags;
	17
	18	typedef enum {
	19	adns_f_search= 0x0001, /* use the searchlist */
	20	adns_f_usevc= 0x0002, /* use a virtual circuit (TCP connection) */
964344fc	21	adns_f_anyquote= 0x0004,
a17d3a1d	22	} adns_queryflags;
	23
	24	typedef enum {
964344fc	25	adns__rrttype_mask= 0x0fff,
	26	adns__qtf_deref= 0x1000, /* dereference domains and produce extra data */
	27	adns__qtf_mailconv= 0x2000, /* put @ between first and second labels */
	28	adns_r_none= 0,
	29	adns_r_a= 1,
	30	adns_r_ns_raw= 2,
	31	adns_r_ns= adns_r_ns_raw\|adns__qtf_deref,
	32	adns_r_cname= 5,
	33	adns_r_soa_raw= 6,
	34	adns_r_soa= adns_r_soa_raw\|adns__qtf_mailconv,
	35	adns_r_null= 10,
	36	adns_r_ptr_raw= 12,
	37	adns_r_ptr= adns_r_ptr_raw\|adns__qtf_deref,
	38	adns_r_hinfo= 13,
	39	adns_r_mx_raw= 15,
	40	adns_r_mx= adns_r_mx_raw\|adns__qtf_deref,
	41	adns_r_txt= 16,
	42	adns_r_rp_raw= 17,
	43	adns_r_rp= adns_r_rp_raw\|adns__qtf_mailconv
a17d3a1d	44	} adns_rrtype;
a17d3a1d	45
964344fc	46	/* In queries without qtf_anyquote, all domains must have standard
	47	* legal syntax. In queries _with_ qtf_anyquote, domains in the query
	48	* or response may contain any characters, quoted according to
	49	* RFC1035 5.1. On input to adns, the char* is a pointer to the
	50	* interior of a " delimited string, except that " may appear in it,
	51	* and on output, the char* is a pointer to a string which would be
	52	* legal either inside or outside " delimiters, and any characters
	53	* not usually legal in domain names will be quoted as \X
	54	* (if the character is 33-126 except \ and ") or \DDD.
	55	*
	56	* Do not ask for records containing mailboxes without
	57	* specifying qtf_mailconv or qtf_anyquote.
	58	*/
	59
a17d3a1d	60	typedef enum {
	61	adns_s_ok,
	62	adns_s_notresponding,
	63	adns_s_serverfailure,
	64	adns_s_unknownqtype,
	65	adns_s_remoteerror,
	66	adns_s_max_tempfail= 99,
	67	adns_s_nxdomain,
	68	adns_s_norecord,
	69	adns_s_invaliddomain
	70	} adns_status;
	71
	72	/* In dereferenced answers, multiple addresses show up as multiple
	73	* answers with all the dm pointers being the same. If no
	74	* address is available (permanent failure) then INADDR_NONE is
964344fc	75	* used.
964344fc	76	*/
a17d3a1d	77
	78	struct adns_answer {
	79	adns_status status;
	80	char cname; / always NULL if query was for CNAME records */
	81	adns_rrtype type;
	82	int nrrs;
	83	union {
	84	struct in_addr inaddr[1]; /* a */
	85	char (str)[1]; / ns_raw, cname, ptr, ptr_raw, txt */
	86	struct { char dm; struct in_addr addr; } dmaddr; / ns */
	87	struct { char a, b; } strpair[1]; /* hinfo, rp, rp_raw */
	88	struct { int pref; char dm; struct in_addr addr; } intdmaddr[1]; / mx */
	89	struct { int pref; char str; } intstr[1]; / mx_raw */
	90	struct {
	91	char ns0, rp;
	92	unsigned long serial, refresh, retry, expire, minimum;
	93	} soa[1]; /* soa, soa_raw */
	94	/* NULL is empty */
	95	} rrs;
	96	};
	97
	98	/* Memory management:
	99	* adns_state and adns_query are actually pointers to malloc'd state;
	100	* On submission questions are copied, including the owner domain;
	101	* Answers are malloc'd as a single piece of memory.
	102	* query_io:
	103	* Must always be non-null pointer;
	104	* If *query_io is 0 to start with then any query may be returned;
	105	* If *query_io is !0 adns_query then only that query may be returned.
	106	* Errors:
	107	* Return values are 0 or an errno value;
	108	* Seriously fatal system errors (eg, failure to create sockets,
	109	* malloc failure, etc.) return errno values;
	110	* Other errors (nameserver failure, timed out connections, &c)
	111	* are returned in the status field of the answer. If status is
	112	* nonzero then nrrs will be 0, otherwise it will be >0.
	113	* type will always be the type requested;
	114	* If no (appropriate) requests are done adns_query returns EWOULDBLOCK;
	115	* If no requests are outstanding adns_query and adns_wait return ESRCH;
	116	* If malloc failure occurs during internal allocation or processing
	117	* ands_query, _wait and _answer set *answer to 0.
	118	*/
	119
964344fc	120	int adns_init(adns_state *newstate_r, adns_initflags flags);
a17d3a1d	121
	122	int adns_synchronous(adns_state ads,
	123	const char *owner,
	124	adns_rrtype type,
	125	int flags,
	126	struct adns_answer *answer);
	127
	128	int adns_submit(adns_state ads,
	129	const char *owner,
	130	adns_rrtype type,
	131	int flags,
	132	void *context,
964344fc	133	adns_query *query_r);
a17d3a1d	134
964344fc	135	int adns_check(adns_state ads,
a17d3a1d	136	adns_query *query_io,
	137	struct adns_answer *answer,
	138	void *context_r);
	139
	140	int adns_wait(adns_state ads,
	141	adns_query *query_io,
	142	struct adns_answer *answer,
964344fc	143	void *context_r);
a17d3a1d	144
	145	int adns_cancel(adns_state ads, adns_query query);
	146
	147	int adns_finish(adns_state);
	148
964344fc	149	void adns_interest(adns_state, fd_set *readfds_mod,
	150	fd_set writefds_mod, fd_set exceptfds_mod,
	151	int maxfd_mod, struct timeval tv_mod, struct timeval tv_buf);
	152	/* You may call this with *_mod=0 to allow adns to have flow-of-control
	153	* briefly, or with fds_mod=maxfd_mod=0 but tv_mod!=0 if you are
	154	* not going to sleep, or with all !=0 if you are going to sleep.
	155	* If tv_mod!=0 and tv_mod=0 then tv_buf must be !0 and tv_buf is irrelevant
	156	* and may be overwritten (and *tv_mod set to tv_buf); otherwise tv_buf is ignored.
	157	*/
	158
	159	int adns_callback(adns_state, fd_set readfds, fd_set writefds,
	160	fd_set exceptfds, int maxfd);
	161	/* For select-driven programs, this allows adns to know which fd's are relevant,
	162	* so that it doesn't need to make syscalls on others of its fd's. It's a kind
	163	* of limited flow-of-control allowance. It will return how many adns fd's were
	164	* in the set, so you can tell if your select handling code is missing things.
	165	*/
a17d3a1d	166
	167	/* Example expected/legal calling sequences:
	168	* adns_init
	169	* adns_submit 1
	170	* adns_submit 2
	171	* adns_submit 3
	172	* adns_wait 1
964344fc	173	* adns_check 3 -> EWOULDBLOCK
a17d3a1d	174	* adns_wait 2
	175	* adns_wait 3
	176	* ....
	177	* adns_finish
	178	*
	179	* adns_init
	180	* adns_submit ...
	181	* loop {
964344fc	182	* adns_check
a17d3a1d	183	* adns_interest
	184	* select
	185	* adns_callback
	186	* other things
	187	* }
	188	*/
	189
	190	#endif