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

src/or/dirserv.c

+3 −8
Original line number Diff line number Diff line
@@ -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

src/or/or.h

+9 −3
Original line number Diff line number Diff line
@@ -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);

src/or/routerlist.c

+3 −12
Original line number Diff line number Diff line
@@ -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,