Commit c6d4a00c authored by Roger Dingledine's avatar Roger Dingledine
Browse files

more doxygen markup

plenty more remains


svn:r1824
parent b384c5a1
/* Copyright 2001,2002,2003 Roger Dingledine, Matej Pfajfar. */ /* Copyright 2001 Matej Pfajfar, 2001-2004 Roger Dingledine. */
/* See LICENSE for licensing information */ /* See LICENSE for licensing information */
/* $Id$ */ /* $Id$ */
...@@ -13,8 +13,8 @@ ...@@ -13,8 +13,8 @@
struct buf_t { struct buf_t {
uint32_t magic; /**< Magic cookie for debugging: Must be set to BUFFER_MAGIC */ uint32_t magic; /**< Magic cookie for debugging: Must be set to BUFFER_MAGIC */
char *mem; /**< Storage for data in the buffer */ char *mem; /**< Storage for data in the buffer */
size_t len; /**< Maximum amount of data that 'mem' can hold. */ size_t len; /**< Maximum amount of data that <b>mem</b> can hold. */
size_t datalen; /**< Number of bytes currently in 'mem'. */ size_t datalen; /**< Number of bytes currently in <b>mem</b>. */
}; };
/** Size, in bytes, for newly allocated buffers. Should be a power of 2. */ /** Size, in bytes, for newly allocated buffers. Should be a power of 2. */
...@@ -26,7 +26,7 @@ struct buf_t { ...@@ -26,7 +26,7 @@ struct buf_t {
* than this size. */ * than this size. */
#define MIN_BUF_SHRINK_SIZE (16*1024) #define MIN_BUF_SHRINK_SIZE (16*1024)
/** Change a buffer's capacity. new_capacity must be \<= buf->datalen. */ /** Change a buffer's capacity. <b>new_capacity</b> must be \<= buf->datalen. */
static INLINE void buf_resize(buf_t *buf, size_t new_capacity) static INLINE void buf_resize(buf_t *buf, size_t new_capacity)
{ {
tor_assert(buf->datalen <= new_capacity); tor_assert(buf->datalen <= new_capacity);
...@@ -35,7 +35,7 @@ static INLINE void buf_resize(buf_t *buf, size_t new_capacity) ...@@ -35,7 +35,7 @@ static INLINE void buf_resize(buf_t *buf, size_t new_capacity)
buf->len = new_capacity; buf->len = new_capacity;
} }
/** If the buffer is not large enough to hold "capacity" bytes, resize /** If the buffer is not large enough to hold <b>capacity</b> bytes, resize
* it so that it can. (The new size will be a power of 2 times the old * it so that it can. (The new size will be a power of 2 times the old
* size.) * size.)
*/ */
...@@ -82,7 +82,7 @@ static INLINE void buf_shrink_if_underfull(buf_t *buf) { ...@@ -82,7 +82,7 @@ static INLINE void buf_shrink_if_underfull(buf_t *buf) {
buf_resize(buf, new_len); buf_resize(buf, new_len);
} }
/** Remove the first 'n' bytes from buf. /** Remove the first <b>n</b> bytes from buf.
*/ */
static INLINE void buf_remove_from_front(buf_t *buf, size_t n) { static INLINE void buf_remove_from_front(buf_t *buf, size_t n) {
tor_assert(buf->datalen >= n); tor_assert(buf->datalen >= n);
...@@ -91,8 +91,8 @@ static INLINE void buf_remove_from_front(buf_t *buf, size_t n) { ...@@ -91,8 +91,8 @@ static INLINE void buf_remove_from_front(buf_t *buf, size_t n) {
buf_shrink_if_underfull(buf); buf_shrink_if_underfull(buf);
} }
/** Find the first instance of the str_len byte string 'sr' on the /** Find the first instance of the str_len byte string <b>str</b> on the
* buf_len byte string 'bufstr'. Strings are not necessary * buf_len byte string <b>bufstr</b>. Strings are not necessary
* NUL-terminated. If none exists, return -1. Otherwise, return index * NUL-terminated. If none exists, return -1. Otherwise, return index
* of the first character in bufstr _after_ the first instance of str. * of the first character in bufstr _after_ the first instance of str.
*/ */
...@@ -116,7 +116,7 @@ static int find_mem_in_mem(const char *str, int str_len, ...@@ -116,7 +116,7 @@ static int find_mem_in_mem(const char *str, int str_len,
return -1; return -1;
} }
/** Create and return a new buf with capacity 'size'. /** Create and return a new buf with capacity <b>size</b>.
*/ */
buf_t *buf_new_with_capacity(size_t size) { buf_t *buf_new_with_capacity(size_t size) {
buf_t *buf; buf_t *buf;
...@@ -137,33 +137,33 @@ buf_t *buf_new() ...@@ -137,33 +137,33 @@ buf_t *buf_new()
return buf_new_with_capacity(INITIAL_BUF_SIZE); return buf_new_with_capacity(INITIAL_BUF_SIZE);
} }
/** Remove all data from 'buf' */ /** Remove all data from <b>buf</b> */
void buf_clear(buf_t *buf) void buf_clear(buf_t *buf)
{ {
buf->datalen = 0; buf->datalen = 0;
} }
/** Return the number of bytes stored in 'buf' */ /** Return the number of bytes stored in <b>buf</b> */
size_t buf_datalen(const buf_t *buf) size_t buf_datalen(const buf_t *buf)
{ {
return buf->datalen; return buf->datalen;
} }
/** Return the maximum bytes that can be stored in 'buf' before buf /** Return the maximum bytes that can be stored in <b>buf</b> before buf
* needs to resize. */ * needs to resize. */
size_t buf_capacity(const buf_t *buf) size_t buf_capacity(const buf_t *buf)
{ {
return buf->len; return buf->len;
} }
/** For testing only: Return a pointer to the raw memory stored in 'buf'. /** For testing only: Return a pointer to the raw memory stored in <b>buf</b>.
*/ */
const char *_buf_peek_raw_buffer(const buf_t *buf) const char *_buf_peek_raw_buffer(const buf_t *buf)
{ {
return buf->mem; return buf->mem;
} }
/** Release storage held by 'buf'. /** Release storage held by <b>buf</b>.
*/ */
void buf_free(buf_t *buf) { void buf_free(buf_t *buf) {
assert_buf_ok(buf); assert_buf_ok(buf);
...@@ -172,9 +172,9 @@ void buf_free(buf_t *buf) { ...@@ -172,9 +172,9 @@ void buf_free(buf_t *buf) {
tor_free(buf); tor_free(buf);
} }
/** Read from socket s, writing onto end of buf. Read at most /** Read from socket <b>s</s>, writing onto end of <b>buf</b>. Read at most
* 'at_most' bytes, resizing the buffer as necessary. If read() * <b>at_most</b> bytes, resizing the buffer as necessary. If read()
* returns 0, set *reached_eof to 1 and return 0. Return -1 on error; * returns 0, set <b>*reached_eof</b> to 1 and return 0. Return -1 on error;
* else return the number of bytes read. Return 0 if read() would * else return the number of bytes read. Return 0 if read() would
* block. * block.
*/ */
...@@ -247,17 +247,14 @@ int read_to_buf_tls(tor_tls *tls, size_t at_most, buf_t *buf) { ...@@ -247,17 +247,14 @@ int read_to_buf_tls(tor_tls *tls, size_t at_most, buf_t *buf) {
return r; return r;
} }
/** Write data from 'buf' to the socket 's'. Write at most /** Write data from <b>buf</b> to the socket <b>s</b>. Write at most
* *buf_flushlen bytes, and decrement *buf_flushlen by the number of * <b>*buf_flushlen</b> bytes, decrement <b>*buf_flushlen</b> by
* bytes actually written. Return the number of bytes written on * the number of bytes actually written, and remove the written bytes
* success, -1 on failure. Return 0 if write() would block. * from the buffer. Return the number of bytes written on success,
* -1 on failure. Return 0 if write() would block.
*/ */
int flush_buf(int s, buf_t *buf, int *buf_flushlen) int flush_buf(int s, buf_t *buf, int *buf_flushlen)
{ {
/* push from buf onto s
* then memmove to front of buf
* return -1 or how many bytes you just flushed */
int write_result; int write_result;
assert_buf_ok(buf); assert_buf_ok(buf);
...@@ -306,7 +303,9 @@ int flush_buf_tls(tor_tls *tls, buf_t *buf, int *buf_flushlen) ...@@ -306,7 +303,9 @@ int flush_buf_tls(tor_tls *tls, buf_t *buf, int *buf_flushlen)
return r; return r;
} }
/** Append string_len bytes from 'string' to the end of 'buf'. /** Append <b>string_len</b> bytes from <b>string</b> to the end of
* <b>buf</b>.
*
* Return the new length of the buffer on success, -1 on failure. * Return the new length of the buffer on success, -1 on failure.
*/ */
int write_to_buf(const char *string, int string_len, buf_t *buf) { int write_to_buf(const char *string, int string_len, buf_t *buf) {
...@@ -329,9 +328,8 @@ int write_to_buf(const char *string, int string_len, buf_t *buf) { ...@@ -329,9 +328,8 @@ int write_to_buf(const char *string, int string_len, buf_t *buf) {
return buf->datalen; return buf->datalen;
} }
/** Remove <b>string_len</b> bytes from the front of <b>buf</b>, and store them
/* Remove string_len bytes from the front of 'buf', and store them * into <b>string</b>. Return the new buffer size. <b>string_len</b> must be \<=
* into 'string'. Return the new buffer size. string_len must be <=
* the number of bytes on the buffer. * the number of bytes on the buffer.
*/ */
int fetch_from_buf(char *string, size_t string_len, buf_t *buf) { int fetch_from_buf(char *string, size_t string_len, buf_t *buf) {
...@@ -350,15 +348,15 @@ int fetch_from_buf(char *string, size_t string_len, buf_t *buf) { ...@@ -350,15 +348,15 @@ int fetch_from_buf(char *string, size_t string_len, buf_t *buf) {
return buf->datalen; return buf->datalen;
} }
/** There is a (possibly incomplete) http statement on *buf, of the /** There is a (possibly incomplete) http statement on <b>buf</b>, of the
* form "\%s\\r\\n\\r\\n\%s", headers, body. (body may contain nuls.) * form "\%s\\r\\n\\r\\n\%s", headers, body. (body may contain nuls.)
* If a) the headers include a Content-Length field and all bytes in * If a) the headers include a Content-Length field and all bytes in
* the body are present, or b) there's no Content-Length field and * the body are present, or b) there's no Content-Length field and
* all headers are present, then: * all headers are present, then:
* *
* - strdup headers into *headers_out, and nul-terminate it. * - strdup headers into <b>*headers_out</b>, and nul-terminate it.
* - memdup body into *body_out, and nul-terminate it. * - memdup body into <b>*body_out</b>, and nul-terminate it.
* - Then remove them from buf, and return 1. * - Then remove them from <b>buf</b>, and return 1.
* *
* - If headers or body is NULL, discard that part of the buf. * - If headers or body is NULL, discard that part of the buf.
* - If a headers or body doesn't fit in the arg, return -1. * - If a headers or body doesn't fit in the arg, return -1.
...@@ -427,7 +425,7 @@ int fetch_from_buf_http(buf_t *buf, ...@@ -427,7 +425,7 @@ int fetch_from_buf_http(buf_t *buf,
return 1; return 1;
} }
/** There is a (possibly incomplete) socks handshake on buf, of one /** There is a (possibly incomplete) socks handshake on <b>buf</b>, of one
* of the forms * of the forms
* - socks4: "socksheader username\\0" * - socks4: "socksheader username\\0"
* - socks4a: "socksheader username\\0 destaddr\\0" * - socks4a: "socksheader username\\0 destaddr\\0"
...@@ -435,16 +433,16 @@ int fetch_from_buf_http(buf_t *buf, ...@@ -435,16 +433,16 @@ int fetch_from_buf_http(buf_t *buf,
* - socks5 phase two: "version command 0 addresstype..." * - socks5 phase two: "version command 0 addresstype..."
* If it's a complete and valid handshake, and destaddr fits in * If it's a complete and valid handshake, and destaddr fits in
* MAX_SOCKS_ADDR_LEN bytes, then pull the handshake off the buf, * MAX_SOCKS_ADDR_LEN bytes, then pull the handshake off the buf,
* assign to req, and return 1. * assign to <b>req</b>, and return 1.
* *
* If it's invalid or too big, return -1. * If it's invalid or too big, return -1.
* *
* Else it's not all there yet, leave buf alone and return 0. * Else it's not all there yet, leave buf alone and return 0.
* *
* If you want to specify the socks reply, write it into req->reply * If you want to specify the socks reply, write it into <b>req->reply</b>
* and set req->replylen, else leave req->replylen alone. * and set <b>req->replylen</b>, else leave <b>req->replylen</b> alone.
* *
* If returning 0 or -1, req->address and req->port are undefined. * If returning 0 or -1, <b>req->address</b> and <b>req->port</b> are undefined.
*/ */
int fetch_from_buf_socks(buf_t *buf, socks_request_t *req) { int fetch_from_buf_socks(buf_t *buf, socks_request_t *req) {
unsigned char len; unsigned char len;
...@@ -618,7 +616,7 @@ int fetch_from_buf_socks(buf_t *buf, socks_request_t *req) { ...@@ -618,7 +616,7 @@ int fetch_from_buf_socks(buf_t *buf, socks_request_t *req) {
} }
} }
/** Log an error and exit if 'buf' is corrupted. /** Log an error and exit if <b>buf</b> is corrupted.
*/ */
void assert_buf_ok(buf_t *buf) void assert_buf_ok(buf_t *buf)
{ {
...@@ -628,7 +626,6 @@ void assert_buf_ok(buf_t *buf) ...@@ -628,7 +626,6 @@ void assert_buf_ok(buf_t *buf)
tor_assert(buf->datalen <= buf->len); tor_assert(buf->datalen <= buf->len);
} }
/* /*
Local Variables: Local Variables:
mode:c mode:c
......
...@@ -2,26 +2,31 @@ ...@@ -2,26 +2,31 @@
/* See LICENSE for licensing information */ /* See LICENSE for licensing information */
/* $Id$ */ /* $Id$ */
/**
* \file command.c
* \brief Functions for processing incoming cells
**/
#include "or.h" #include "or.h"
extern or_options_t options; /* command-line and config-file options */ extern or_options_t options; /**< command-line and config-file options */
/* keep statistics about how many of each type of cell we've received */ /** keep statistics about how many of each type of cell we've received */
unsigned long stats_n_padding_cells_processed = 0; unsigned long stats_n_padding_cells_processed = 0;
unsigned long stats_n_create_cells_processed = 0; unsigned long stats_n_create_cells_processed = 0;
unsigned long stats_n_created_cells_processed = 0; unsigned long stats_n_created_cells_processed = 0;
unsigned long stats_n_relay_cells_processed = 0; unsigned long stats_n_relay_cells_processed = 0;
unsigned long stats_n_destroy_cells_processed = 0; unsigned long stats_n_destroy_cells_processed = 0;
/* These are the main four functions for processing cells */ /** These are the main four functions for processing cells */
static void command_process_create_cell(cell_t *cell, connection_t *conn); static void command_process_create_cell(cell_t *cell, connection_t *conn);
static void command_process_created_cell(cell_t *cell, connection_t *conn); static void command_process_created_cell(cell_t *cell, connection_t *conn);
static void command_process_relay_cell(cell_t *cell, connection_t *conn); static void command_process_relay_cell(cell_t *cell, connection_t *conn);
static void command_process_destroy_cell(cell_t *cell, connection_t *conn); static void command_process_destroy_cell(cell_t *cell, connection_t *conn);
/* This is a wrapper function around the actual function that processes /** This is a wrapper function around the actual function that processes the
* 'cell' that just arrived on 'conn'. Increment *time by the number of * <b>cell</b> that just arrived on <b>conn</b>. Increment <b>*time</b>
* microseconds used by the call to *func(cell, conn). * by the number of microseconds used by the call to <b>*func(cell, conn)</b>.
*/ */
static void command_time_process_cell(cell_t *cell, connection_t *conn, int *time, static void command_time_process_cell(cell_t *cell, connection_t *conn, int *time,
void (*func)(cell_t *, connection_t *)) { void (*func)(cell_t *, connection_t *)) {
...@@ -41,7 +46,7 @@ static void command_time_process_cell(cell_t *cell, connection_t *conn, int *tim ...@@ -41,7 +46,7 @@ static void command_time_process_cell(cell_t *cell, connection_t *conn, int *tim
*time += time_passed; *time += time_passed;
} }
/* Process a cell that was just received on conn. Keep internal /** Process a <b>cell</b> that was just received on <b>conn</b>. Keep internal
* statistics about how many of each cell we've processed so far * statistics about how many of each cell we've processed so far
* this second, and the total number of microseconds it took to * this second, and the total number of microseconds it took to
* process each type of cell. * process each type of cell.
...@@ -107,7 +112,7 @@ void command_process_cell(cell_t *cell, connection_t *conn) { ...@@ -107,7 +112,7 @@ void command_process_cell(cell_t *cell, connection_t *conn) {
} }
} }
/* Process a 'create' cell that just arrived from conn. Make a new circuit /** Process a 'create' <b>cell</b> that just arrived from <b>conn</b>. Make a new circuit
* with the p_circ_id specified in cell. Put the circuit in state * with the p_circ_id specified in cell. Put the circuit in state
* onionskin_pending, and pass the onionskin to the cpuworker. Circ will * onionskin_pending, and pass the onionskin to the cpuworker. Circ will
* get picked up again when the cpuworker finishes decrypting it. * get picked up again when the cpuworker finishes decrypting it.
...@@ -137,9 +142,9 @@ static void command_process_create_cell(cell_t *cell, connection_t *conn) { ...@@ -137,9 +142,9 @@ static void command_process_create_cell(cell_t *cell, connection_t *conn) {
log_fn(LOG_DEBUG,"success: handed off onionskin."); log_fn(LOG_DEBUG,"success: handed off onionskin.");
} }
/* Process a 'created' cell that just arrived from conn. Find the circuit /** Process a 'created' <b>cell</b> that just arrived from <b>conn</b>. Find the circuit
* that it's intended for. If you're not the origin of the circuit, package * that it's intended for. If we're not the origin of the circuit, package
* the 'created' cell in an 'extended' relay cell and pass it back. If you * the 'created' cell in an 'extended' relay cell and pass it back. If we
* are the origin of the circuit, send it to circuit_finish_handshake() to * are the origin of the circuit, send it to circuit_finish_handshake() to
* finish processing keys, and then call circuit_send_next_onion_skin() to * finish processing keys, and then call circuit_send_next_onion_skin() to
* extend to the next hop in the circuit if necessary. * extend to the next hop in the circuit if necessary.
...@@ -180,7 +185,7 @@ static void command_process_created_cell(cell_t *cell, connection_t *conn) { ...@@ -180,7 +185,7 @@ static void command_process_created_cell(cell_t *cell, connection_t *conn) {
} }
} }
/* Process a 'relay' cell that just arrived from conn. Make sure /** Process a 'relay' <b>cell</b> that just arrived from <b>conn</b>. Make sure
* it came in with a recognized circ_id. Pass it on to * it came in with a recognized circ_id. Pass it on to
* circuit_receive_relay_cell() for actual processing. * circuit_receive_relay_cell() for actual processing.
*/ */
...@@ -216,8 +221,8 @@ static void command_process_relay_cell(cell_t *cell, connection_t *conn) { ...@@ -216,8 +221,8 @@ static void command_process_relay_cell(cell_t *cell, connection_t *conn) {
} }
} }
/* Process a 'destroy' cell that just arrived from conn. Find the /** Process a 'destroy' <b>cell</b> that just arrived from
* circ that it refers to (if any). * <b>conn</b>. Find the circ that it refers to (if any).
* *
* If the circ is in state * If the circ is in state
* onionskin_pending, then call onion_pending_remove() to remove it * onionskin_pending, then call onion_pending_remove() to remove it
......
...@@ -2,17 +2,23 @@ ...@@ -2,17 +2,23 @@
/* See LICENSE for licensing information */ /* See LICENSE for licensing information */
/* $Id$ */ /* $Id$ */
/**
* \file connection_or.c
* \brief Functions to handle OR connections, TLS handshaking, and
* cells on the network.
**/
#include "or.h" #include "or.h"
extern or_options_t options; /* command-line and config-file options */ extern or_options_t options; /**< command-line and config-file options */
static int connection_tls_finish_handshake(connection_t *conn); static int connection_tls_finish_handshake(connection_t *conn);
static int connection_or_process_cells_from_inbuf(connection_t *conn); static int connection_or_process_cells_from_inbuf(connection_t *conn);
/**************************************************************/ /**************************************************************/
/* Pack the cell_t host-order structure 'src' into network-order /** Pack the cell_t host-order structure <b>src</b> into network-order
* in the buffer 'dest'. See tor-spec.txt for details about the * in the buffer <b>dest</b>. See tor-spec.txt for details about the
* wire format. * wire format.
*/ */
static void cell_pack(char *dest, const cell_t *src) { static void cell_pack(char *dest, const cell_t *src) {
...@@ -21,8 +27,8 @@ static void cell_pack(char *dest, const cell_t *src) { ...@@ -21,8 +27,8 @@ static void cell_pack(char *dest, const cell_t *src) {
memcpy(dest+3, src->payload, CELL_PAYLOAD_SIZE); memcpy(dest+3, src->payload, CELL_PAYLOAD_SIZE);
} }
/* Unpack the network-order buffer 'src' into a host-order /** Unpack the network-order buffer <b>src</b> into a host-order
* cell_t structure 'dest'. * cell_t structure <b>dest</b>.
*/ */
static void cell_unpack(cell_t *dest, const char *src) { static void cell_unpack(cell_t *dest, const char *src) {
dest->circ_id = ntohs(*(uint16_t*)(src)); dest->circ_id = ntohs(*(uint16_t*)(src));
...@@ -30,9 +36,7 @@ static void cell_unpack(cell_t *dest, const char *src) { ...@@ -30,9 +36,7 @@ static void cell_unpack(cell_t *dest, const char *src) {
memcpy(dest->payload, src+3, CELL_PAYLOAD_SIZE); memcpy(dest->payload, src+3, CELL_PAYLOAD_SIZE);
} }
/**************************************************************/ /** Handle any new bytes that have come in on connection <b>conn</b>.
/* Handle any new bytes that have come in on connection 'conn'.
* If conn is in 'open' state, hand it to * If conn is in 'open' state, hand it to
* connection_or_process_cells_from_inbuf() * connection_or_process_cells_from_inbuf()
* (else do nothing). * (else do nothing).
...@@ -52,7 +56,7 @@ int connection_or_process_inbuf(connection_t *conn) { ...@@ -52,7 +56,7 @@ int connection_or_process_inbuf(connection_t *conn) {
return connection_or_process_cells_from_inbuf(conn); return connection_or_process_cells_from_inbuf(conn);
} }
/* Connection 'conn' has finished writing and has no bytes left on /** Connection <b>conn</b> has finished writing and has no bytes left on
* its outbuf. * its outbuf.
* *
* If it's in state 'connecting', then take a look at the socket, and * If it's in state 'connecting', then take a look at the socket, and
...@@ -68,7 +72,8 @@ int connection_or_finished_flushing(connection_t *conn) { ...@@ -68,7 +72,8 @@ int connection_or_finished_flushing(connection_t *conn) {
switch(conn->state) { switch(conn->state) {
case OR_CONN_STATE_CONNECTING: case OR_CONN_STATE_CONNECTING:
if (getsockopt(conn->s, SOL_SOCKET, SO_ERROR, (void*)&e, &len) < 0) { /* not yet */ if (getsockopt(conn->s, SOL_SOCKET, SO_ERROR, (void*)&e, &len) < 0) {
/* not yet */
if(!ERRNO_IS_CONN_EINPROGRESS(tor_socket_errno(conn->s))) { if(!ERRNO_IS_CONN_EINPROGRESS(tor_socket_errno(conn->s))) {
log_fn(LOG_DEBUG,"in-progress connect failed. Removing."); log_fn(LOG_DEBUG,"in-progress connect failed. Removing.");
connection_mark_for_close(conn,0); connection_mark_for_close(conn,0);
...@@ -97,9 +102,7 @@ int connection_or_finished_flushing(connection_t *conn) { ...@@ -97,9 +102,7 @@ int connection_or_finished_flushing(connection_t *conn) {
} }
} }
/*********************/ /** Initialize <b>conn</b> to include all the relevant data from <b>router</b>.
/* Initialize conn to include all the relevant data from router.
* This function is called either from connection_or_connect(), if * This function is called either from connection_or_connect(), if
* we initiated the connect, or from connection_tls_finish_handshake() * we initiated the connect, or from connection_tls_finish_handshake()
* if the other side initiated it. * if the other side initiated it.
...@@ -115,11 +118,11 @@ connection_or_init_conn_from_router(connection_t *conn, routerinfo_t *router) { ...@@ -115,11 +118,11 @@ connection_or_init_conn_from_router(connection_t *conn, routerinfo_t *router) {
conn->address = tor_strdup(router->address); conn->address = tor_strdup(router->address);
} }
/* Launch a new OR connection to 'router'. /** Launch a new OR connection to <b>router</b>.
* *
* If router is me, do nothing. If we're already connected to router, * If <b>router</b> is me, do nothing. If we're already connected to <b>router</b>,
* return that connection. If the connect is in progress, set conn's * return that connection. If the connect is in progress, set conn's
* state to 'connecting' and return. If connect to router succeeds, call * state to 'connecting' and return. If connect to <b>router</b> succeeds, call
* connection_tls_start_handshake() on it. * connection_tls_start_handshake() on it.
* *
* This function is called from router_retry_connections(), for * This function is called from router_retry_connections(), for
...@@ -170,13 +173,13 @@ connection_t *connection_or_connect(routerinfo_t *router) { ...@@ -170,13 +173,13 @@ connection_t *connection_or_connect(routerinfo_t *router) {
return NULL; return NULL;
} }
/* Begin the tls handshake with conn. 'receiving' is 0 if we initiated /** Begin the tls handshake with <b>conn</b>. <b>receiving</b> is 0 if
* the connection, else it's 1. * we initiated the connection, else it's 1.
* *
* Assign a new tls object to conn->tls, begin reading on conn, and pass * Assign a new tls object to conn->tls, begin reading on <b>conn</b>, and pass
* conn to connection_tls_continue_handshake(). * <b>conn</b> to connection_tls_continue_handshake().
* *
* Return -1 if conn is broken, else return 0. * Return -1 if <b>conn</b> is broken, else return 0.
*/ */
int connection_tls_start_handshake(connection_t *conn, int receiving) { int connection_tls_start_handshake(connection_t *conn, int receiving) {
conn->state = OR_CONN_STATE_HANDSHAKING; conn->state = OR_CONN_STATE_HANDSHAKING;
...@@ -193,10 +196,10 @@ int connection_tls_start_handshake(connection_t *conn, int receiving) { ...@@ -193,10 +196,10 @@ int connection_tls_start_handshake(connection_t *conn, int receiving) {
return 0; return 0;
} }
/* Move forward with the tls handshake. If it finishes, hand /** Move forward with the tls handshake. If it finishes, hand
* conn to connection_tls_finish_handshake(). * <b>conn</b> to connection_tls_finish_handshake().
* *
* Return -1 if conn is broken, else return 0. * Return -1 if <b>conn</b> is broken, else return 0.
*/ */
int connection_tls_continue_handshake(connection_t *conn) { int connection_tls_continue_handshake(connection_t *conn) {
switch(tor_tls_handshake(conn->tls)) { switch(tor_tls_handshake(conn->tls)) {
...@@ -217,7 +220,7 @@ int connection_tls_continue_handshake(connection_t *conn) { ...@@ -217,7 +220,7 @@ int connection_tls_continue_handshake(connection_t *conn) {
return 0; return 0;
} }
/* The tls handshake is finished. /** The tls handshake is finished.
* *
* Make sure we are happy with the person we just handshaked with: * Make sure we are happy with the person we just handshaked with:
* If it's an OP (that is, it has no certificate), make sure I'm an OR. * If it's an OP (that is, it has no certificate), make sure I'm an OR.
...@@ -301,7 +304,7 @@ connection_tls_finish_handshake(connection_t *conn) { ...@@ -301,7 +304,7 @@ connection_tls_finish_handshake(connection_t *conn) {
return 0; return 0;
} }
/* Pack 'cell' into wire-format, and write it onto conn's outbuf. */ /** Pack <b>cell</b> into wire-format, and write it onto <b>conn</b>'s outbuf. */
void connection_or_write_cell_to_buf(const cell_t *cell, connection_t *conn) { void connection_or_write_cell_to_buf(const cell_t *cell, connection_t *conn) {