Commit 167d266d authored by Nick Mathewson's avatar Nick Mathewson 🐻
Browse files

Documentation and conformance for WRA_* returns.

shahn: "Add some documentation for the WRA_* family of functions, also make
sure that (hopefully) all functions that return was_router_added_t
don't return ints directly and that they don't refer to integers in
their documentation anymore."

svn:r17731
parent 1e666bfc
......@@ -653,13 +653,8 @@ dirserv_add_multiple_descriptors(const char *desc, uint8_t purpose,
* the list of server descriptors. Set *<b>msg</b> to a message that should be
* passed back to the origin of this descriptor.
*
* Return 2 if descriptor is well-formed and accepted;
* 1 if well-formed and accepted but origin should hear *msg;
* 0 if well-formed but redundant with one we already have;
* -1 if it is rejected and origin should hear *msg;
* Return the status of the operation
*
* This function is only called when fresh descriptors are posted, not when
* we re-load the cache.
*/
......@@ -684,7 +679,7 @@ dirserv_add_descriptor(routerinfo_t *ri, const char **msg)
ri->cache_info.signed_descriptor_body,
ri->cache_info.signed_descriptor_len, *msg);
routerinfo_free(ri);
return -1;
return ROUTER_AUTHDIR_REJECTS;
}
/* Check whether this descriptor is semantically identical to the last one
......@@ -704,7 +699,7 @@ dirserv_add_descriptor(routerinfo_t *ri, const char **msg)
ri->cache_info.signed_descriptor_body,
ri->cache_info.signed_descriptor_len, *msg);
routerinfo_free(ri);
return 0;
return ROUTER_WAS_NOT_NEW;
}
if (control_event_is_interesting(EVENT_AUTHDIR_NEWDESCS)) {
/* Make a copy of desc, since router_add_to_routerlist might free
......
......@@ -4385,19 +4385,25 @@ typedef enum was_router_added_t {
static int WRA_WAS_ADDED(was_router_added_t s);
static int WRA_WAS_OUTDATED(was_router_added_t s);
static int WRA_WAS_REJECTED(was_router_added_t s);
/**DOCDOC*/
/** Return true iff the descriptor was added. It might still be necessary to
* check whether the descriptor generator should be notified.
*/
static INLINE int
WRA_WAS_ADDED(was_router_added_t s) {
return s == ROUTER_ADDED_SUCCESSFULLY || s == ROUTER_ADDED_NOTIFY_GENERATOR;
}
/**DOCDOC*/
/** Return true iff the descriptor was not added because it was either:
* - not in the consensus
* - neither in the consensus nor in any networkstatus document
* - it was outdated.
*/
static INLINE int WRA_WAS_OUTDATED(was_router_added_t s)
{
return (s == ROUTER_WAS_NOT_NEW ||
s == ROUTER_NOT_IN_CONSENSUS ||
s == ROUTER_NOT_IN_CONSENSUS_OR_NETWORKSTATUS);
}
/**DOCDOC*/
/** Return true iff the descriptor rejected because it was malformed. */
static INLINE int WRA_WAS_REJECTED(was_router_added_t s)
{
return (s == ROUTER_AUTHDIR_REJECTS);
......
......@@ -2904,16 +2904,7 @@ router_set_status(const char *digest, int up)
* <b>router</b> after subsequent calls with other routerinfo's -- they
* might cause the original routerinfo to get freed.
*
* Returns >= 0 if the router was added; less than 0 if it was not.
*
* If we're returning non-zero, then assign to *<b>msg</b> a static string
* describing the reason for not liking the routerinfo.
*
* If the return value is less than -1, there was a problem with the
* routerinfo. If the return value is equal to -1, then the routerinfo was
* fine, but out-of-date. If the return value is equal to 1, the
* routerinfo was accepted, but we should notify the generator of the
* descriptor using the message *<b>msg</b>.
* Returns the status for the operation.
*
* If <b>from_cache</b>, this descriptor came from our disk cache. If
* <b>from_fetch</b>, we received it in response to a request we made.
......@@ -3068,8 +3059,8 @@ router_add_to_routerlist(routerinfo_t *router, const char **msg,
}
/** Insert <b>ei</b> into the routerlist, or free it. Other arguments are
* as for router_add_to_routerlist(). Return true iff we actually inserted
* it.
* as for router_add_to_routerlist(). Return ROUTER_ADDED_SUCCESSFULLY iff
* we actually inserted it, ROUTER_BAD_EI otherwise.
*/
was_router_added_t
router_add_extrainfo_to_routerlist(extrainfo_t *ei, const char **msg,
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment