mirror
/
transmission
mirror of https://github.com/transmission/transmission
1
0
Fork 0
Code Issues Releases Wiki Activity

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

This commit is contained in:
Charles Kerr 2010-01-19 19:37:00 +00:00
parent 6c0f78ffd8
commit 9eb07e9b16
17 changed files with 110 additions and 89 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
libtransmission/announcer.c
View File

@ -353,10 +353,7 @@ trackerFree( void * vtracker )
struct tr_torrent_tiers;
/**
* A group of trackers in a single tier,
* as per the multitracker spec
*/
/** @brief A group of trackers in a single tier, as per the multitracker spec */
typedef struct
{
tr_ptrArray trackers; /* tr_tracker_item */
@ -469,8 +466,9 @@ tierAddTracker( tr_announcer * announcer,
****
***/
/*
* per-torrent info.
/**
* @brief Opaque, per-torrent data structure for tracker announce information
*
* this opaque data structure can be found in tr_torrent.tiers
*/
typedef struct tr_torrent_tiers

1
libtransmission/announcer.h
View File

@ -36,6 +36,7 @@ typedef enum
}
TrackerEventType;
/** @brief Notification object to tell listeners about announce or scrape occurences */
typedef struct
{
/* what type of event this is */

2
libtransmission/bencode.c
View File

@ -1176,6 +1176,7 @@ tr_bencFree( tr_benc * val )
****
***/
/** @brief Implementation helper class for tr_bencToBuffer(TR_FMT_JSON) */
struct ParentState
{
int bencType;
@ -1183,6 +1184,7 @@ struct ParentState
int childCount;
};
/** @brief Implementation helper class for tr_bencToBuffer(TR_FMT_JSON) */
struct jsonWalk
{
tr_bool doIndent;

19
libtransmission/bencode.h
View File

@ -198,12 +198,24 @@ tr_bool tr_bencDictFindRaw( tr_benc *, const char * key,
****
***/
/** @brief Get an int64_t from a variant object
@return TRUE if successful, or FALSE if the variant could not be represented as an int64_t */
tr_bool tr_bencGetInt( const tr_benc * val, int64_t * setme );
/** @brief Get an string from a variant object
@return TRUE if successful, or FALSE if the variant could not be represented as a string */
tr_bool tr_bencGetStr( const tr_benc * val, const char ** setme );
/** @brief Get a boolean from a variant object
@return TRUE if successful, or FALSE if the variant could not be represented as a boolean */
tr_bool tr_bencGetBool( const tr_benc * val, tr_bool * setme );
/** @brief Get a floating-point number from a variant object
@return TRUE if successful, or FALSE if the variant could not be represented as a floating-point number */
tr_bool tr_bencGetReal( const tr_benc * val, double * setme );
static inline tr_bool tr_bencIsType ( const tr_benc * b, int type ) { return ( b != NULL ) && ( b->type == type ); }
static inline tr_bool tr_bencIsInt ( const tr_benc * b ) { return tr_bencIsType( b, TR_TYPE_INT ); }
static inline tr_bool tr_bencIsDict ( const tr_benc * b ) { return tr_bencIsType( b, TR_TYPE_DICT ); }
static inline tr_bool tr_bencIsList ( const tr_benc * b ) { return tr_bencIsType( b, TR_TYPE_LIST ); }
@ -211,16 +223,13 @@ static inline tr_bool tr_bencIsString( const tr_benc * b ) { return tr_bencIsTyp
static inline tr_bool tr_bencIsBool ( const tr_benc * b ) { return tr_bencIsType( b, TR_TYPE_BOOL ); }
static inline tr_bool tr_bencIsReal ( const tr_benc * b ) { return tr_bencIsType( b, TR_TYPE_REAL ); }
/**
*** Treat these as private -- they're only made public here
*** so that the unit tests can find them
**/
/** @brief Private function that's exposed here only for unit tests */
int tr_bencParseInt( const uint8_t * buf,
const uint8_t * bufend,
const uint8_t ** setme_end,
int64_t * setme_val );
/** @brief Private function that's exposed here only for unit tests */
int tr_bencParseStr( const uint8_t * buf,
const uint8_t * bufend,
const uint8_t ** setme_end,

1
libtransmission/bitfield.h
View File

@ -20,6 +20,7 @@
#include "transmission.h"
#include "utils.h" /* tr_new0 */
/** @brief Implementation of the BitTorrent spec's Bitfield array of bits */
typedef struct tr_bitfield
{
uint8_t * bits;

2
libtransmission/bitset.h
View File

@ -22,7 +22,7 @@
#include "transmission.h"
#include "bitfield.h"
/** This like a tr_bitfield, but supports haveAll and haveNone */
/** @brief like a tr_bitfield, but supports haveAll and haveNone */
typedef struct tr_bitset
{
tr_bool haveAll;

1
libtransmission/clients.h
View File

@ -18,6 +18,7 @@
#define TR_CLIENTS_H
/**
* @brief parse a peer-id into a human-readable client name and version number
* @ingroup utils
*/
void tr_clientForId( char * buf, size_t buflen, const void * peer_id );

1
libtransmission/crypto.c
View File

@ -86,6 +86,7 @@ static const uint8_t dh_P[PRIME_LEN] =
static const uint8_t dh_G[] = { 2 };
/** @brief Holds state information for encrypted peer communications */
struct tr_crypto
{
RC4_KEY dec_key;

66
libtransmission/crypto.h
View File

@ -28,36 +28,25 @@
struct evbuffer;
/**
* @addtogroup utils Utilities
* @{
*/
*** @addtogroup peers
*** @{
**/
typedef struct tr_crypto tr_crypto;
/**
***
**/
tr_crypto* tr_cryptoNew( const uint8_t * torrentHash,
int isIncoming );
/** @brief create a new tr_crypto object */
tr_crypto* tr_cryptoNew( const uint8_t * torrentHash, int isIncoming );
/** @brief destroy an existing tr_crypto object */
void tr_cryptoFree( tr_crypto * crypto );
/**
***
**/
void tr_cryptoSetTorrentHash( tr_crypto * crypto,
const uint8_t * torrentHash );
void tr_cryptoSetTorrentHash( tr_crypto * crypto, const uint8_t * torrentHash );
const uint8_t* tr_cryptoGetTorrentHash( const tr_crypto * crypto );
int tr_cryptoHasTorrentHash( const tr_crypto * crypto );
/**
***
**/
const uint8_t* tr_cryptoComputeSecret( tr_crypto * crypto,
const uint8_t * peerPublicKey );
@ -71,10 +60,6 @@ void tr_cryptoDecrypt( tr_crypto * crypto,
const void * buf_in,
void * buf_out );
/**
***
**/
void tr_cryptoEncryptInit( tr_crypto * crypto );
void tr_cryptoEncrypt( tr_crypto * crypto,
@ -82,17 +67,26 @@ void tr_cryptoEncrypt( tr_crypto * crypto,
const void * buf_in,
void * buf_out );
void tr_sha1( uint8_t * setme,
const void * content1,
int content1_len,
... ) TR_GNUC_NULL_TERMINATED;
/** @brief Returns a random number in the range of [0...n) */
int tr_cryptoRandInt( int n );
/* @} */
/**
* @brief Returns a vaguely random number in the range of [0...n).
*** @addtogroup utils Utilities
*** @{
**/
/** @brief generate a SHA1 hash from one or more chunks of memory */
void tr_sha1( uint8_t * setme,
const void * content1,
int content1_len,
... ) TR_GNUC_NULL_TERMINATED;
/** @brief returns a random number in the range of [0...n) */
int tr_cryptoRandInt( int n );
/**
* @brief returns a pseudorandom number in the range of [0...n)
*
* This is faster, BUT WEAKER, than tr_cryptoRandInt() and never
* be used in sensitive cases.
@ -100,12 +94,14 @@ int tr_cryptoRandInt( int n );
*/
int tr_cryptoWeakRandInt( int n );
/** @brief Fills a buffer with random bytes */
void tr_cryptoRandBuf( void * buf, size_t len );
/** @brief fill a buffer with random bytes */
void tr_cryptoRandBuf( void * buf, size_t len );
char* tr_ssha1( const void * plaintext );
/** @brief generate a SSHA password from its plaintext source */
char* tr_ssha1( const void * plaintext );
tr_bool tr_ssha1_matches( const char * source, const char * pass );
/** @brief Validate a test password against the a ssha1 password */
tr_bool tr_ssha1_matches( const char * ssha1, const char * pass );
/* @} */

1
libtransmission/peer-mgr.c
View File

@ -160,6 +160,7 @@ struct weighted_piece
int16_t requestCount;
};
/** @brief Opaque, per-torrent data structure for peer connection information */
typedef struct tr_torrent_peers
{
tr_ptrArray outgoingHandshakes; /* tr_handshake */

5
libtransmission/platform.c
View File

@ -78,6 +78,7 @@ tr_areThreadsEqual( tr_thread_id a,
#endif
}
/** @brief portability wrapper around OS-dependent threads */
struct tr_thread
{
void ( * func )( void * );
@ -142,6 +143,7 @@ tr_threadNew( void ( *func )(void *),
**** LOCKS
***/
/** @brief portability wrapper around OS-dependent thread mutexes */
struct tr_lock
{
int depth;
@ -378,8 +380,7 @@ migrateFiles( const tr_session * session )
}
void
tr_setConfigDir( tr_session * session,
const char * configDir )
tr_setConfigDir( tr_session * session, const char * configDir )
{
char * path;

53
libtransmission/platform.h
View File

@ -34,28 +34,38 @@
#define MAX_STACK_ARRAY_SIZE 7168
/**
* @addtogroup tr_session Session
* @{
*/
/**
* @brief invoked by tr_sessionInit() to set up the locations of the resume, torrent, and clutch directories.
* @see tr_getResumeDir()
* @see tr_getTorrentDir()
* @see tr_getClutchDir()
*/
void tr_setConfigDir( tr_session * session, const char * configDir );
/** @brief return the directory where .resume files are stored */
const char * tr_getResumeDir( const tr_session * );
/** @brief return the directory where .torrent files are stored */
const char * tr_getTorrentDir( const tr_session * );
/** @brief return the directory where Clutch's web ui files are kept */
const char * tr_getClutchDir( const tr_session * );
/** @} */
/**
* @addtogroup utils Utilities
* @{
*/
typedef struct tr_lock tr_lock;
typedef struct tr_thread tr_thread;
void tr_setConfigDir( tr_session * session,
const char * configDir );
const char * tr_getResumeDir( const tr_session * );
const char * tr_getTorrentDir( const tr_session * );
const char * tr_getClutchDir( const tr_session * );
/***
****
***/
/** @brief Instantiate a new process thread */
tr_thread* tr_threadNew( void ( *func )(void *), void * arg );
@ -67,6 +77,8 @@ int tr_amInThread( const tr_thread * );
****
***/
typedef struct tr_lock tr_lock;
/** @brief Create a new thread mutex object */
tr_lock * tr_lockNew( void );
@ -83,16 +95,9 @@ void tr_lockUnlock( tr_lock * );
int tr_lockHave( const tr_lock * );
#ifdef WIN32
void * mmap( void *ptr,
long size,
long prot,
long type,
long handle,
long arg );
long munmap( void *ptr,
long size );
void * mmap( void *ptr, long size, long prot, long type, long handle, long arg );
long munmap( void *ptr, long size );
#endif
/* @} */

4
libtransmission/session.c
View File

@ -576,8 +576,10 @@ onNowTimer( int foo UNUSED, short bar UNUSED, void * vsession )
if( usec > max ) usec = max;
if( usec < min ) usec = min;
tr_timerAdd( session->nowTimer, 0, usec );
/* update libtransmission's epoch time */
tr_timeUpdate( tv.tv_sec );
/* fprintf( stderr, "time %zu sec, %zu microsec\n", (size_t)tr_time(), (size_t)tv.tv_usec ); */
/* fprintf( stderr, "time %zu sec, %zu microsec\n", (size_t)tr_time(), (size_t)tv.tv_usec ); */
}
static void loadBlocklists( tr_session * session );

1
libtransmission/stats.c
View File

@ -23,6 +23,7 @@
static struct tr_session_stats STATS_INIT = { 0.0f, 0, 0, 0, 0, 0 };
/** @brief Opaque, per-session data structure for bandwidth use statistics */
struct tr_stats_handle
{
tr_session_stats single;

1
libtransmission/torrent.h
View File

@ -134,6 +134,7 @@ void tr_torrentSetVerifyState( tr_torrent * tor,
struct tr_incomplete_metadata;
/** @brief Torrent object */
struct tr_torrent
{
tr_session * session;

30
libtransmission/transmission.h
View File

@ -340,7 +340,7 @@ void tr_sessionSetDownloadDir( tr_session * session, const char * downloadDir );
const char * tr_sessionGetDownloadDir( const tr_session * session );
/**
* @brief Set the per-session incomplete download folder.
* @brief set the per-session incomplete download folder.
*
* When you add a new torrent and the session's incomplete directory is enabled,
* the new torrent will start downloading into that directory, and then be moved
@ -360,10 +360,13 @@ const char * tr_sessionGetDownloadDir( const tr_session * session );
*/
void tr_sessionSetIncompleteDir( tr_session * session, const char * dir );
/** @brief get the per-session incomplete download folder */
const char* tr_sessionGetIncompleteDir( const tr_session * session );
/** @brief enable or disable use of the incomplete download folder */
void tr_sessionSetIncompleteDirEnabled( tr_session * session, tr_bool );
/** @brief get whether or not the incomplete download folder is enabled */
tr_bool tr_sessionIsIncompleteDirEnabled( const tr_session * session );
@ -378,6 +381,7 @@ tr_bool tr_sessionIsIncompleteDirEnabled( const tr_session * session );
*/
void tr_sessionSetIncompleteFileNamingEnabled( tr_session * session, tr_bool );
/** @brief return whether or filenames will have ".part" at the end until they're complete */
tr_bool tr_sessionIsIncompleteFileNamingEnabled( const tr_session * session );
/**
@ -538,6 +542,7 @@ void tr_sessionSetProxyPassword( tr_session * session,
***
**/
/** @brief Used by tr_sessionGetStats() and tr_sessionGetCumulativeStats() to give bandwidth statistics */
typedef struct tr_session_stats
{
float ratio; /* TR_RATIO_INF, TR_RATIO_NA, or total up/down */
@ -549,23 +554,21 @@ typedef struct tr_session_stats
}
tr_session_stats;
/* stats from the current session. */
void tr_sessionGetStats( const tr_session * session,
tr_session_stats * setme );
/** @brief Get bandwidth use statistics about the current session */
void tr_sessionGetStats( const tr_session * session, tr_session_stats * setme );
/* stats from the current and past sessions. */
void tr_sessionGetCumulativeStats( const tr_session * session,
tr_session_stats * setme );
/** @brief Get cumulative bandwidth use statistics for the current and past sessions */
void tr_sessionGetCumulativeStats( const tr_session * session, tr_session_stats * setme );
void tr_sessionClearStats( tr_session * session );
void tr_sessionClearStats( tr_session * session );
/**
* Set whether or not torrents are allowed to do peer exchanges.
* @brief Set whether or not torrents are allowed to do peer exchanges.
*
* PEX is always disabled in private torrents regardless of this.
* In public torrents, PEX is enabled by default.
*/
void tr_sessionSetPexEnabled( tr_session * session,
tr_bool isEnabled );
void tr_sessionSetPexEnabled( tr_session * session, tr_bool isEnabled );
tr_bool tr_sessionIsPexEnabled( const tr_session * session );
@ -1639,10 +1642,7 @@ typedef enum
}
tr_stat_errtype;
/**
* @brief Describes a torrent's status
* @see tr_torrentStat()
*/
/** @brief Used by tr_torrentStat() to tell clients about a torrent's state and statistics */
typedef struct tr_stat
{
/** The torrent's unique Id.

1
libtransmission/utils.h
View File

@ -519,6 +519,7 @@ static inline void tr_removeElementFromArray( void * array,
****
***/
/** @brief Private libtransmission variable that's visible only for inlining in tr_time() */
extern time_t transmission_now;
/**