[or-cvs] r9087: Document all structures and (non-exported) functions. Extern (in tor/trunk: . doc src/or)
nickm at seul.org
nickm at seul.org
Tue Dec 12 02:57:03 UTC 2006
Author: nickm
Date: 2006-12-11 21:57:02 -0500 (Mon, 11 Dec 2006)
New Revision: 9087
Modified:
tor/trunk/
tor/trunk/doc/TODO
tor/trunk/src/or/eventdns.c
tor/trunk/src/or/eventdns.h
Log:
r11498 at Kushana: nickm | 2006-12-11 21:40:24 -0500
Document all structures and (non-exported) functions. External documentation will probably wind up being a manpage, hopefully written by somebody else.
Property changes on: tor/trunk
___________________________________________________________________
svk:merge ticket from /tor/branches/eventdns [r11498] on c95137ef-5f19-0410-b913-86e773d04f59
Modified: tor/trunk/doc/TODO
===================================================================
--- tor/trunk/doc/TODO 2006-12-12 02:56:54 UTC (rev 9086)
+++ tor/trunk/doc/TODO 2006-12-12 02:57:02 UTC (rev 9087)
@@ -95,8 +95,8 @@
- Teach evdns about ipv6.
- Make evdns use windows strerror equivalents.
- Teach evdns to be able to listen for requests to be processed.
- . Design interface.
- - Rename stuff; current names suck.
+ o Design interface.
+ o Rename stuff; current names suck.
o Design backend.
. Implement
o Listen for questions
Modified: tor/trunk/src/or/eventdns.c
===================================================================
--- tor/trunk/src/or/eventdns.c 2006-12-12 02:56:54 UTC (rev 9086)
+++ tor/trunk/src/or/eventdns.c 2006-12-12 02:57:02 UTC (rev 9087)
@@ -382,52 +382,68 @@
static struct request *req_head = NULL, *req_waiting_head = NULL;
static struct nameserver *server_head = NULL;
+// Represents a local port where we're listening for DNS requests. Right now,
+// only UDP is supported.
struct evdns_server_port {
- int socket;
- int refcnt;
- char choaked;
- char closing;
- evdns_request_callback_fn_type user_callback;
- void *user_data;
- struct event event;
+ int socket; // socket we use to read queries and write replies.
+ int refcnt; // reference count.
+ char choaked; // Are we currently blocked from writing?
+ char closing; // Are we trying to close this port, pending writes?
+ evdns_request_callback_fn_type user_callback; // Fn to handle requests
+ void *user_data; // Opaque pointer passed to user_callback
+ struct event event; // Read/write event
+ // circular list of replies that we want to write.
struct server_request *pending_replies;
};
-struct server_request_item {
- struct server_request_item *next;
- char *name;
- unsigned int type : 16;
- unsigned int class : 16;
- int ttl;
- unsigned is_name : 1;
- int datalen : 31;
- void *data;
+// Represents part of a reply being built. (That is, a single RR.)
+struct server_reply_item {
+ struct server_reply_item *next; // next item in sequence.
+ char *name; // name part of the RR
+ u16 type : 16; // The RR type
+ u16 class : 16; // The RR class (usually CLASS_INET)
+ u32 ttl; // The RR TTL
+ char is_name; // True iff data is a label
+ u16 datalen; // Length of data; -1 if data is a label
+ void *data; // The contents of the RR
};
+// Represents a request that we've received as a DNS server, and holds
+// the components of the reply as we're constructing it.
struct server_request {
+ // Pointers to the next and previous entries on the list of replies
+ // that we're waiting to write. Only set if we have tried to respond
+ // and gotten EAGAIN.
struct server_request *next_pending;
struct server_request *prev_pending;
- u16 trans_id;
- struct evdns_server_port *port;
- struct sockaddr_storage addr;
- socklen_t addrlen;
+ u16 trans_id; // Transaction id.
+ struct evdns_server_port *port; // Which port received this request on?
+ struct sockaddr_storage addr; // Where to send the response
+ socklen_t addrlen; // length of addr
- int n_answer;
- int n_authority;
- int n_additional;
+ int n_answer; // how many answer RRs have been set?
+ int n_authority; // how many authority RRs have been set?
+ int n_additional; // how many additional RRs have been set?
- struct server_request_item *answer;
- struct server_request_item *authority;
- struct server_request_item *additional;
+ struct server_reply_item *answer; // linked list of answer RRs
+ struct server_reply_item *authority; // linked list of authority RRs
+ struct server_reply_item *additional; // linked list of additional RRs
+ // Constructed response. Only set once we're ready to send a reply.
+ // Once this is set, the RR fields are cleared, and no more should be set.
char *response;
size_t response_len;
+ // Caller-visible fields: flags, questions.
struct evdns_server_request base;
};
+
+// helper macro
#define OFFSET_OF(st, member) ((off_t) (((char*)&((st*)0)->member)-(char*)0))
+// Given a pointer to an evdns_server_request, get the corresponding
+// server_request.
#define TO_SERVER_REQUEST(base_ptr) \
((struct server_request*) \
(((char*)(base_ptr) - OFFSET_OF(struct server_request, base))))
@@ -1044,6 +1060,9 @@
#undef GET16
#undef GET8
+// Parse a raw request (packet,length) sent to a nameserver port (port) from
+// a DNS client (addr,addrlen), and if it's well-formed, call the corresponding
+// callback.
static int
request_parse(u8 *packet, int length, struct evdns_server_port *port, struct sockaddr *addr, socklen_t addrlen)
{
@@ -1058,6 +1077,7 @@
u16 trans_id, flags, questions, answers, authority, additional;
struct server_request *server_req = NULL;
+ // Get the header fields
GET16(trans_id);
GET16(flags);
GET16(questions);
@@ -1101,7 +1121,7 @@
server_req->base.questions[server_req->base.nquestions++] = q;
}
- // Do nothing with rest of packet -- safe?
+ // Ignore answers, authority, and additional.
server_req->port = port;
port->refcnt++;
@@ -1122,7 +1142,6 @@
#undef GET16
#undef GET8
-
// Try to choose a strong transaction id which isn't already in flight
static u16
transaction_id_pick(void) {
@@ -1222,6 +1241,8 @@
}
}
+// Read a packet from a DNS client on a server port s, parse it, and
+// act accordingly.
static void
server_port_read(struct evdns_server_port *s) {
u8 packet[1500];
@@ -1244,6 +1265,7 @@
}
}
+// Try to write all pending replies on a given DNS server port.
static void
server_port_flush(struct evdns_server_port *port)
{
@@ -1257,10 +1279,13 @@
return;
log(EVDNS_LOG_WARN, "Error %s (%d) while writing response to port; dropping", strerror(err), err);
}
- if (server_request_free(req))
+ if (server_request_free(req)) {
+ // we released the last reference to req->port.
return;
+ }
}
+ // We have no more pending requests; stop listening for 'writeable' events.
(void) event_del(&port->event);
event_set(&port->event, port->socket, EV_READ | EV_PERSIST,
server_port_ready_callback, port);
@@ -1323,20 +1348,24 @@
}
/* This is an inefficient representation; only use it via the dnslabel_table_*
- * functions. */
+ * functions, so that is can be safely replaced with something smarter later. */
#define MAX_LABELS 128
+// Structures used to implement name compression
struct dnslabel_entry { char *v; int pos; };
struct dnslabel_table {
- int n_labels;
+ int n_labels; // number of current entries
+ // map from name to position in message
struct dnslabel_entry labels[MAX_LABELS];
};
+// Initialize dnslabel_table.
static void
dnslabel_table_init(struct dnslabel_table *table)
{
table->n_labels = 0;
}
+// Free all storage held by table, but not the table itself.
static void
dnslabel_clear(struct dnslabel_table *table)
{
@@ -1346,6 +1375,8 @@
table->n_labels = 0;
}
+// return the position of the label in the current message, or -1 if the label
+// hasn't been used yet.
static int
dnslabel_table_get_pos(const struct dnslabel_table *table, const char *label)
{
@@ -1357,6 +1388,7 @@
return -1;
}
+// remember that we've used the label at position pos
static int
dnslabel_table_add(struct dnslabel_table *table, const char *label, int pos)
{
@@ -1530,11 +1562,11 @@
evdns_server_request_add_reply(struct evdns_server_request *_req, int section, const char *name, int type, int class, int ttl, int datalen, int is_name, const char *data)
{
struct server_request *req = TO_SERVER_REQUEST(_req);
- struct server_request_item **itemp, *item;
+ struct server_reply_item **itemp, *item;
int *countp;
if (req->response) /* have we already answered? */
- return -1;
+ return (-1);
switch (section) {
case EVDNS_ANSWER_SECTION:
@@ -1550,12 +1582,12 @@
countp = &req->n_additional;
break;
default:
- return -1;
+ return (-1);
}
while (*itemp) {
itemp = &((*itemp)->next);
}
- item = malloc(sizeof(struct server_request_item));
+ item = malloc(sizeof(struct server_reply_item));
if (!item)
return -1;
item->next = NULL;
@@ -1684,7 +1716,7 @@
/* Add answer, authority, and additional sections. */
for (i=0; i<3; ++i) {
- struct server_request_item *item;
+ struct server_reply_item *item;
if (i==0)
item = req->answer;
else if (i==1)
@@ -1789,10 +1821,11 @@
return 0;
}
+// Free all storage held by RRs in req.
static void
server_request_free_answers(struct server_request *req)
{
- struct server_request_item *victim, *next, **list;
+ struct server_reply_item *victim, *next, **list;
int i;
for (i = 0; i < 3; ++i) {
if (i==0)
@@ -1814,6 +1847,7 @@
}
}
+// Free all storage held by req, and remove links to it.
// return true iff we just wound up freeing the server_port.
static int
server_request_free(struct server_request *req)
@@ -1853,6 +1887,7 @@
return (0);
}
+// Free all storage held by an evdns_server_port. Only called when
static void
server_port_free(struct evdns_server_port *port)
{
@@ -2986,7 +3021,8 @@
{
int i, r;
(void)data;
- /* dummy; give 192.168.11.11 as an answer for all A questions. */
+ /* dummy; give 192.168.11.11 as an answer for all A questions,
+ * give foo.bar.example.com as an answer for all PTR questions. */
for (i = 0; i < req->nquestions; ++i) {
u32 ans = htonl(0xc0a80b0bUL);
if (req->questions[i]->type == EVDNS_TYPE_A &&
Modified: tor/trunk/src/or/eventdns.h
===================================================================
--- tor/trunk/src/or/eventdns.h 2006-12-12 02:56:54 UTC (rev 9086)
+++ tor/trunk/src/or/eventdns.h 2006-12-12 02:57:02 UTC (rev 9087)
@@ -75,6 +75,8 @@
#define DNS_NO_SEARCH 1
+/* Structures and functions used to implement a DNS server. */
+
struct evdns_server_request {
int flags;
int nquestions;
More information about the tor-commits
mailing list