Changeset 9965


Ignore:
Timestamp:
Jan 19, 2010, 7:37:00 PM (13 years ago)
Author:
charles
Message:

(trunk) No code changes here... filling in some of the blanks in the "peers" and "utils" doxygen groups' documentation.

Location:
trunk/libtransmission
Files:
17 edited

Legend:

Unmodified
Added
Removed

  • trunk/libtransmission/announcer.c

    r9928 r9965  
    354354struct tr_torrent_tiers;
    355355
    356 /**
    357  * A group of trackers in a single tier,
    358  * as per the multitracker spec
    359  */
     356/** @brief A group of trackers in a single tier, as per the multitracker spec */
    360357typedef struct
    361358{
    … …  
    470467***/
    471468
    472 /*
    473  * per-torrent info.
     469/**
     470 * @brief Opaque, per-torrent data structure for tracker announce information
     471 *
    474472 * this opaque data structure can be found in tr_torrent.tiers
    475473 */

  • trunk/libtransmission/announcer.h

    r9890 r9965  
    3737TrackerEventType;
    3838
     39/** @brief Notification object to tell listeners about announce or scrape occurences */
    3940typedef struct
    4041{

  • trunk/libtransmission/bencode.c

    r9868 r9965  
    11771177***/
    11781178
     1179/** @brief Implementation helper class for tr_bencToBuffer(TR_FMT_JSON) */
    11791180struct ParentState
    11801181{
    … …  
    11841185};
    11851186
     1187/** @brief Implementation helper class for tr_bencToBuffer(TR_FMT_JSON) */
    11861188struct jsonWalk
    11871189{

  • trunk/libtransmission/bencode.h

    r9868 r9965  
    199199***/
    200200
     201/** @brief Get an int64_t from a variant object
     202    @return TRUE if successful, or FALSE if the variant could not be represented as an int64_t  */
    201203tr_bool   tr_bencGetInt( const tr_benc * val, int64_t * setme );
     204
     205/** @brief Get an string from a variant object
     206    @return TRUE if successful, or FALSE if the variant could not be represented as a string  */
    202207tr_bool   tr_bencGetStr( const tr_benc * val, const char ** setme );
     208
     209/** @brief Get a boolean from a variant object
     210    @return TRUE if successful, or FALSE if the variant could not be represented as a boolean  */
    203211tr_bool   tr_bencGetBool( const tr_benc * val, tr_bool * setme );
     212
     213/** @brief Get a floating-point number from a variant object
     214    @return TRUE if successful, or FALSE if the variant could not be represented as a floating-point number  */
    204215tr_bool   tr_bencGetReal( const tr_benc * val, double * setme );
    205216
    206217static inline tr_bool tr_bencIsType  ( const tr_benc * b, int type ) { return ( b != NULL ) && ( b->type == type ); }
     218
    207219static inline tr_bool tr_bencIsInt   ( const tr_benc * b ) { return tr_bencIsType( b, TR_TYPE_INT ); }
    208220static inline tr_bool tr_bencIsDict  ( const tr_benc * b ) { return tr_bencIsType( b, TR_TYPE_DICT ); }
    … …  
    212224static inline tr_bool tr_bencIsReal  ( const tr_benc * b ) { return tr_bencIsType( b, TR_TYPE_REAL ); }
    213225
    214 /**
    215 ***  Treat these as private -- they're only made public here
    216 ***  so that the unit tests can find them
    217 **/
    218 
     226/** @brief Private function that's exposed here only for unit tests */
    219227int tr_bencParseInt( const uint8_t *  buf,
    220228                     const uint8_t *  bufend,
    … …  
    222230                     int64_t *        setme_val );
    223231
     232/** @brief Private function that's exposed here only for unit tests */
    224233int tr_bencParseStr( const uint8_t *  buf,
    225234                     const uint8_t *  bufend,

  • trunk/libtransmission/bitfield.h

    r9931 r9965  
    2121#include "utils.h" /* tr_new0 */
    2222
     23/** @brief Implementation of the BitTorrent spec's Bitfield array of bits */
    2324typedef struct tr_bitfield
    2425{

  • trunk/libtransmission/bitset.h

    r9934 r9965  
    2323#include "bitfield.h"
    2424
    25 /** This like a tr_bitfield, but supports haveAll and haveNone */
     25/** @brief like a tr_bitfield, but supports haveAll and haveNone */
    2626typedef struct tr_bitset
    2727{

  • trunk/libtransmission/clients.h

    r9868 r9965  
    1919
    2020/**
     21 * @brief parse a peer-id into a human-readable client name and version number
    2122 * @ingroup utils
    2223 */

  • trunk/libtransmission/crypto.c

    r9868 r9965  
    8787static const uint8_t dh_G[] = { 2 };
    8888
     89/** @brief Holds state information for encrypted peer communications */
    8990struct tr_crypto
    9091{

  • trunk/libtransmission/crypto.h

    r9891 r9965  
    2929
    3030/**
    31  * @addtogroup utils Utilities
    32  * @{
    33  */
     31*** @addtogroup peers
     32*** @{
     33**/
    3434
    3535typedef struct tr_crypto tr_crypto;
    3636
    37 /**
    38 ***
    39 **/
     37/** @brief create a new tr_crypto object */
     38tr_crypto*  tr_cryptoNew( const uint8_t * torrentHash, int isIncoming );
    4039
    41 tr_crypto*     tr_cryptoNew( const uint8_t * torrentHash,
    42                              int             isIncoming );
    43 
     40/** @brief destroy an existing tr_crypto object */
    4441void           tr_cryptoFree( tr_crypto * crypto );
    4542
    46 /**
    47 ***
    48 **/
    4943
    50 void           tr_cryptoSetTorrentHash( tr_crypto *     crypto,
    51                                         const uint8_t * torrentHash );
     44void tr_cryptoSetTorrentHash( tr_crypto * crypto, const uint8_t * torrentHash );
    5245
    5346const uint8_t* tr_cryptoGetTorrentHash( const tr_crypto * crypto );
    5447
    5548int            tr_cryptoHasTorrentHash( const tr_crypto * crypto );
    56 
    57 /**
    58 ***
    59 **/
    6049
    6150const uint8_t* tr_cryptoComputeSecret( tr_crypto *     crypto,
    … …  
    7261                                 void *       buf_out );
    7362
    74 /**
    75 ***
    76 **/
    77 
    7863void           tr_cryptoEncryptInit( tr_crypto * crypto );
    7964
    … …  
    8368                                 void *       buf_out );
    8469
    85 void           tr_sha1( uint8_t *    setme,
    86                         const void * content1,
    87                         int          content1_len,
    88                         ... ) TR_GNUC_NULL_TERMINATED;
     70/* @} */
     71
     72/**
     73*** @addtogroup utils Utilities
     74*** @{
     75**/
    8976
    9077
    91 /** @brief Returns a random number in the range of [0...n) */
    92 int            tr_cryptoRandInt( int n );
     78/** @brief generate a SHA1 hash from one or more chunks of memory */
     79void tr_sha1( uint8_t    * setme,
     80              const void * content1,
     81              int          content1_len,
     82              ... ) TR_GNUC_NULL_TERMINATED;
     83
     84
     85/** @brief returns a random number in the range of [0...n) */
     86int tr_cryptoRandInt( int n );
    9387
    9488/**
    95  * @brief Returns a vaguely random number in the range of [0...n).
     89 * @brief returns a pseudorandom number in the range of [0...n)
    9690 *
    9791 * This is faster, BUT WEAKER, than tr_cryptoRandInt() and never
    … …  
    10195int            tr_cryptoWeakRandInt( int n );
    10296
    103 /** @brief Fills a buffer with random bytes */
    104 void           tr_cryptoRandBuf( void * buf, size_t len );
     97/** @brief fill a buffer with random bytes */
     98void  tr_cryptoRandBuf( void * buf, size_t len );
    10599
    106 char*          tr_ssha1( const void * plaintext );
     100/** @brief generate a SSHA password from its plaintext source */
     101char*  tr_ssha1( const void * plaintext );
    107102
    108 tr_bool        tr_ssha1_matches( const char * source, const char * pass );
     103/** @brief Validate a test password against the a ssha1 password */
     104tr_bool tr_ssha1_matches( const char * ssha1, const char * pass );
    109105
    110106/* @} */

  • trunk/libtransmission/peer-mgr.c

    r9920 r9965  
    161161};
    162162
     163/** @brief Opaque, per-torrent data structure for peer connection information */
    163164typedef struct tr_torrent_peers
    164165{

  • trunk/libtransmission/platform.c

    r9868 r9965  
    7979}
    8080
     81/** @brief portability wrapper around OS-dependent threads */
    8182struct tr_thread
    8283{
    … …  
    143144***/
    144145
     146/** @brief portability wrapper around OS-dependent thread mutexes */
    145147struct tr_lock
    146148{
    … …  
    379381
    380382void
    381 tr_setConfigDir( tr_session * session,
    382                  const char * configDir )
     383tr_setConfigDir( tr_session * session, const char * configDir )
    383384{
    384385    char * path;

  • trunk/libtransmission/platform.h

    r9931 r9965  
    3636
    3737/**
     38 * @addtogroup tr_session Session
     39 * @{
     40 */
     41
     42/**
     43 * @brief invoked by tr_sessionInit() to set up the locations of the resume, torrent, and clutch directories.
     44 * @see tr_getResumeDir()
     45 * @see tr_getTorrentDir()
     46 * @see tr_getClutchDir()
     47 */
     48void tr_setConfigDir( tr_session * session, const char * configDir );
     49
     50/** @brief return the directory where .resume files are stored */
     51const char * tr_getResumeDir( const tr_session * );
     52
     53/** @brief return the directory where .torrent files are stored */
     54const char * tr_getTorrentDir( const tr_session * );
     55
     56/** @brief return the directory where Clutch's web ui files are kept */
     57const char * tr_getClutchDir( const tr_session * );
     58
     59/** @} */
     60
     61
     62/**
    3863 * @addtogroup utils Utilities
    3964 * @{
    4065 */
    4166
    42 typedef struct tr_lock   tr_lock;
    4367typedef struct tr_thread tr_thread;
    44 
    45 void                tr_setConfigDir( tr_session * session,
    46                                      const char * configDir );
    47 
    48 const char *        tr_getResumeDir( const tr_session * );
    49 
    50 const char *        tr_getTorrentDir( const tr_session * );
    51 
    52 const char *        tr_getClutchDir( const tr_session * );
    53 
    54 
    55 /***
    56 ****
    57 ***/
    5868
    5969/** @brief Instantiate a new process thread */
    … …  
    6777****
    6878***/
     79
     80typedef struct tr_lock tr_lock;
    6981
    7082/** @brief Create a new thread mutex object */
    … …  
    8496
    8597#ifdef WIN32
    86 void *              mmap( void *ptr,
    87                           long  size,
    88                           long  prot,
    89                           long  type,
    90                           long  handle,
    91                           long  arg );
     98void * mmap( void *ptr, long  size, long  prot, long  type, long  handle, long  arg );
    9299
    93 long                munmap( void *ptr,
    94                             long  size );
    95 
     100long munmap( void *ptr, long  size );
    96101#endif
    97102

  • trunk/libtransmission/session.c

    r9932 r9965  
    577577    if( usec < min ) usec = min;
    578578    tr_timerAdd( session->nowTimer, 0, usec );
     579
     580    /* update libtransmission's epoch time */
    579581    tr_timeUpdate( tv.tv_sec );
    580     /* fprintf( stderr, "time %zu sec, %zu microsec\n", (size_t)tr_time(), (size_t)tv.tv_usec );  */
     582    /* fprintf( stderr, "time %zu sec, %zu microsec\n", (size_t)tr_time(), (size_t)tv.tv_usec ); */
    581583}
    582584

  • trunk/libtransmission/stats.c

    r9868 r9965  
    2424static struct tr_session_stats STATS_INIT = { 0.0f, 0, 0, 0, 0, 0 };
    2525
     26/** @brief Opaque, per-session data structure for bandwidth use statistics */
    2627struct tr_stats_handle
    2728{

  • trunk/libtransmission/torrent.h

    r9868 r9965  
    135135struct tr_incomplete_metadata;
    136136
     137/** @brief Torrent object */
    137138struct tr_torrent
    138139{

  • trunk/libtransmission/transmission.h

    r9928 r9965  
    341341
    342342/**
    343  * @brief Set the per-session incomplete download folder.
     343 * @brief set the per-session incomplete download folder.
    344344 *
    345345 * When you add a new torrent and the session's incomplete directory is enabled,
    … …  
    361361void tr_sessionSetIncompleteDir( tr_session * session, const char * dir );
    362362
     363/** @brief get the per-session incomplete download folder */
    363364const char* tr_sessionGetIncompleteDir( const tr_session * session );
    364365
     366/** @brief enable or disable use of the incomplete download folder */
    365367void tr_sessionSetIncompleteDirEnabled( tr_session * session, tr_bool );
    366368
     369/** @brief get whether or not the incomplete download folder is enabled */
    367370tr_bool tr_sessionIsIncompleteDirEnabled( const tr_session * session );
    368371
    … …  
    379382void tr_sessionSetIncompleteFileNamingEnabled( tr_session * session, tr_bool );
    380383
     384/** @brief return whether or filenames will have ".part" at the end until they're complete */
    381385tr_bool tr_sessionIsIncompleteFileNamingEnabled( const tr_session * session );
    382386
    … …  
    539543**/
    540544
     545/** @brief Used by tr_sessionGetStats() and tr_sessionGetCumulativeStats() to give bandwidth statistics */
    541546typedef struct tr_session_stats
    542547{
    … …  
    550555tr_session_stats;
    551556
    552 /* stats from the current session. */
    553 void               tr_sessionGetStats( const tr_session * session,
    554                                        tr_session_stats * setme );
    555 
    556 /* stats from the current and past sessions. */
    557 void               tr_sessionGetCumulativeStats( const tr_session * session,
    558                                                  tr_session_stats * setme );
    559 
    560 void               tr_sessionClearStats( tr_session * session );
    561 
    562 /**
    563  * Set whether or not torrents are allowed to do peer exchanges.
     557/** @brief Get bandwidth use statistics about the current session */
     558void tr_sessionGetStats( const tr_session * session, tr_session_stats * setme );
     559
     560/** @brief Get cumulative bandwidth use statistics for the current and past sessions */
     561void tr_sessionGetCumulativeStats( const tr_session * session, tr_session_stats * setme );
     562
     563void tr_sessionClearStats( tr_session * session );
     564
     565/**
     566 * @brief Set whether or not torrents are allowed to do peer exchanges.
     567 *
    564568 * PEX is always disabled in private torrents regardless of this.
    565569 * In public torrents, PEX is enabled by default.
    566570 */
    567 void               tr_sessionSetPexEnabled( tr_session  * session,
    568                                             tr_bool       isEnabled );
     571void tr_sessionSetPexEnabled( tr_session  * session, tr_bool isEnabled );
    569572
    570573tr_bool            tr_sessionIsPexEnabled( const tr_session * session );
    … …  
    16401643tr_stat_errtype;
    16411644
    1642 /**
    1643  * @brief Describes a torrent's status
    1644  * @see tr_torrentStat()
    1645  */
     1645/** @brief Used by tr_torrentStat() to tell clients about a torrent's state and statistics */
    16461646typedef struct tr_stat
    16471647{

  • trunk/libtransmission/utils.h

    r9891 r9965  
    520520***/
    521521
     522/** @brief Private libtransmission variable that's visible only for inlining in tr_time() */
    522523extern time_t transmission_now;
    523524
Note: See TracChangeset for help on using the changeset viewer.