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

(trunk libT) improved API documentation / commenting for doxygen

This commit is contained in:
Charles Kerr 2010-01-01 22:13:27 +00:00
parent 1fec2fb2d0
commit e61e0fcd3d
6 changed files with 263 additions and 131 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
libtransmission/platform.h
View File

@ -52,20 +52,35 @@ const char * tr_getTorrentDir( const tr_session * );
const char * tr_getClutchDir( const tr_session * );
tr_thread* tr_threadNew( void ( *func )(void *),
void * arg );
/***
****
***/
int tr_amInThread( const tr_thread * );
/** @brief Instantiate a new process thread */
tr_thread* tr_threadNew( void ( *func )(void *), void * arg );
tr_lock * tr_lockNew( void );
/** @brief Return nonzero if this function is being called from `thread'
@param thread the thread being tested */
int tr_amInThread( const tr_thread * );
void tr_lockFree( tr_lock * );
/***
****
***/
void tr_lockLock( tr_lock * );
/** @brief Create a new thread mutex object */
tr_lock * tr_lockNew( void );
void tr_lockUnlock( tr_lock * );
/** @brief Destroy a thread mutex object */
void tr_lockFree( tr_lock * );
int tr_lockHave( const tr_lock * );
/** @brief Attempt to lock a thread mutex object */
void tr_lockLock( tr_lock * );
/** @brief Unlock a thread mutex object */
void tr_lockUnlock( tr_lock * );
/** @brief return nonzero if the specified lock is locked */
int tr_lockHave( const tr_lock * );
#ifdef WIN32
void * mmap( void *ptr,

8
libtransmission/ptrarray.c
View File

@ -68,14 +68,6 @@ tr_ptrArrayNth( tr_ptrArray* t,
return t->items[i];
}
void*
tr_ptrArrayBack( tr_ptrArray* t )
{
assert( t->n_items > 0 );
return tr_ptrArrayNth( t, t->n_items - 1 );
}
int
tr_ptrArrayInsert( tr_ptrArray * t,
void * ptr,

76
libtransmission/ptrarray.h
View File

@ -39,58 +39,84 @@ typedef void ( *PtrArrayForeachFunc )( void * );
extern const tr_ptrArray TR_PTR_ARRAY_INIT;
void tr_ptrArrayDestruct( tr_ptrArray*, PtrArrayForeachFunc func );
/** @brief Destructor to free a tr_ptrArray's internal memory */
void tr_ptrArrayDestruct( tr_ptrArray*, PtrArrayForeachFunc func );
void tr_ptrArrayForeach( tr_ptrArray * array,
PtrArrayForeachFunc func );
/** @brief Iterate through each item in a tr_ptrArray */
void tr_ptrArrayForeach( tr_ptrArray * array,
PtrArrayForeachFunc func );
/** @brief Return the nth item in a tr_ptrArray
@return the nth item in a tr_ptrArray */
void* tr_ptrArrayNth( tr_ptrArray * array,
int nth );
void* tr_ptrArrayBack( tr_ptrArray * array );
/** @brief Remove the last item from the array and return it
@return the pointer that's been removed from the array
@see tr_ptrArrayBack() */
void* tr_ptrArrayPop( tr_ptrArray * array );
void** tr_ptrArrayPeek( tr_ptrArray * array,
int * size );
/** @brief Return the last item in a tr_ptrArray
@return the last item in a tr_ptrArray, or NULL if the array is empty
@see tr_ptrArrayPop() */
static inline void* tr_ptrArrayBack( tr_ptrArray * array )
{
return array->n_items > 0 ? tr_ptrArrayNth( array, array->n_items - 1 )
: NULL;
}
static TR_INLINE void tr_ptrArrayClear( tr_ptrArray * a ) { a->n_items = 0; }
int tr_ptrArrayInsert( tr_ptrArray * array,
void * insertMe,
int pos );
/** @brief Peek at the array pointer and its size, for easy iteration */
void** tr_ptrArrayPeek( tr_ptrArray * array, int * size );
static TR_INLINE int tr_ptrArrayAppend( tr_ptrArray * array, void * appendMe )
static inline void tr_ptrArrayClear( tr_ptrArray * a ) { a->n_items = 0; }
/** @brief Insert a pointer into the array at the specified position
@return the index of the stored pointer */
int tr_ptrArrayInsert( tr_ptrArray * array, void * insertMe, int pos );
/** @brief Append a pointer into the array */
static inline int tr_ptrArrayAppend( tr_ptrArray * array, void * appendMe )
{
return tr_ptrArrayInsert( array, appendMe, -1 );
}
void* tr_ptrArrayPop( tr_ptrArray * array );
static TR_INLINE void** tr_ptrArrayBase( const tr_ptrArray * a )
static inline void** tr_ptrArrayBase( const tr_ptrArray * a )
{
return a->items;
}
static TR_INLINE int tr_ptrArraySize( const tr_ptrArray * a )
/** @brief Return the number of items in the array
@return the number of items in the array */
static inline int tr_ptrArraySize( const tr_ptrArray * a )
{
return a->n_items;
}
static TR_INLINE tr_bool tr_ptrArrayEmpty( const tr_ptrArray * a )
/** @brief Return True if the array has no pointers
@return True if the array has no pointers */
static inline tr_bool tr_ptrArrayEmpty( const tr_ptrArray * a )
{
return tr_ptrArraySize(a) == 0;
}
int tr_ptrArrayInsertSorted( tr_ptrArray * array,
void * value,
int compare(const void*, const void*) );
/** @brief Insert a pointer into the array at the position determined by the sort function
@return the index of the stored pointer */
int tr_ptrArrayInsertSorted( tr_ptrArray * array,
void * value,
int compare(const void*, const void*) );
void* tr_ptrArrayRemoveSorted( tr_ptrArray * array,
void * value,
int compare(const void*, const void*) );
/** @brief Remove a pointer from an array sorted by the specified sort function
@return the matching pointer, or NULL if no match was found */
void* tr_ptrArrayRemoveSorted( tr_ptrArray * array,
void * value,
int compare(const void*, const void*) );
void* tr_ptrArrayFindSorted( tr_ptrArray * array,
const void * key,
int compare(const void*, const void*) );
/** @brief Find a pointer from an array sorted by the specified sort function
@return the matching pointer, or NULL if no match was found */
void* tr_ptrArrayFindSorted( tr_ptrArray * array,
const void * key,
int compare(const void*, const void*) );
/* @} */
#endif

22
libtransmission/tr-getopt.h
View File

@ -22,6 +22,7 @@ extern "C" {
* @{
*/
/** @brief Similar to optind, this is the current index into argv */
extern int tr_optind;
typedef struct tr_option
@ -49,18 +50,19 @@ enum
};
/**
* @return TR_GETOPT_DONE, TR_GETOPT_ERR, TR_GETOPT_UNK,
* or the matching tr_option's `val' field
* @brief similar to getopt()
* @return TR_GETOPT_DONE, TR_GETOPT_ERR, TR_GETOPT_UNK, or the matching tr_option's `val' field
*/
int tr_getopt( const char * summary,
int argc,
const char ** argv,
const tr_option * opts,
const char ** setme_optarg );
int tr_getopt( const char * summary,
int argc,
const char ** argv,
const tr_option * opts,
const char ** setme_optarg );
void tr_getopt_usage( const char * appName,
const char * description,
const tr_option * opts );
/** @brief prints the `Usage' help section to stdout */
void tr_getopt_usage( const char * appName,
const char * description,
const tr_option * opts );
#ifdef __cplusplus
} /* extern "C" */

67
libtransmission/transmission.h
View File

@ -55,9 +55,7 @@ extern "C" {
#endif
#if defined(WIN32) && defined(_MSC_VER)
#define TR_INLINE __inline
#else
#define TR_INLINE inline
#define inline __inline
#endif
#define SHA_DIGEST_LENGTH 20
@ -303,9 +301,11 @@ tr_session * tr_sessionInit( const char * tag,
tr_bool messageQueueingEnabled,
struct tr_benc * settings );
/** @brief Update a session's settings from a benc dictionary like to the one used in tr_sessionInit() */
void tr_sessionSet( tr_session * session,
struct tr_benc * settings );
/** @brief Rescan the blocklists directory and reload whatever blocklist files are found there */
void tr_sessionReloadBlocklists( tr_session * session );
@ -852,35 +852,37 @@ tr_ctorMode;
struct tr_benc;
/* it's okay to use NULL here if you're only parsing the torrent.
* @see tr_torrentParse() */
tr_ctor* tr_ctorNew( const tr_session * session_or_NULL );
/** @brief Create a new torrent constructor object used to instantiate a tr_torrent
@param session the tr_session. NULL is allowed if you're only calling tr_torrentParse() rather than tr_torrentNew()
@see tr_torrentNew(), tr_torrentParse() */
tr_ctor* tr_ctorNew( const tr_session * session_or_NULL );
void tr_ctorFree( tr_ctor * ctor );
/** @brief Free a torrent constructor object */
void tr_ctorFree( tr_ctor * ctor );
void tr_ctorSetDeleteSource( tr_ctor * ctor,
tr_bool doDelete );
/** @brief Set whether or not to delete the source .torrent file when a torrent is added. (Default: False) */
void tr_ctorSetDeleteSource( tr_ctor * ctor, tr_bool doDelete );
int tr_ctorSetMagnet( tr_ctor * ctor,
const char * url );
/** @brief Set the link for creating a tr_torrent from a magnet link */
int tr_ctorSetMagnet( tr_ctor * ctor, const char * magnet_link );
int tr_ctorSetMetainfo( tr_ctor * ctor,
const uint8_t * metainfo,
size_t len );
/** @brief Set the constructor's metainfo from a raw benc already in memory */
int tr_ctorSetMetainfo( tr_ctor * ctor, const uint8_t * metainfo, size_t len );
int tr_ctorSetMetainfoFromFile( tr_ctor * ctor,
const char * filename );
/** @brief Set the constructor's metainfo from a local .torrent file */
int tr_ctorSetMetainfoFromFile( tr_ctor * ctor, const char * filename );
int tr_ctorSetMetainfoFromHash( tr_ctor * ctor,
const char * hashString );
/**
* @brief Set the constructor's metainfo from an already-existing file in tr_getTorrentDir().
*
* This is used by the mac client on startup to pick and choose which existing torrents to load
*/
int tr_ctorSetMetainfoFromHash( tr_ctor * ctor, const char * hashString );
/** Set the maximum number of peers this torrent can connect to.
(Default: 50) */
void tr_ctorSetPeerLimit( tr_ctor * ctor,
tr_ctorMode mode,
uint16_t peerLimit );
/** @brief Set the maximum number of peers this torrent can connect to. (Default: 50) */
void tr_ctorSetPeerLimit( tr_ctor * ctor, tr_ctorMode mode, uint16_t peerLimit );
/** Set the download folder for the torrent being added with this ctor.
/** @brief Set the download folder for the torrent being added with this ctor.
@see tr_ctorSetDownloadDir()
@see tr_sessionInit() */
void tr_ctorSetDownloadDir( tr_ctor * ctor,
@ -903,41 +905,50 @@ void tr_ctorSetPaused( tr_ctor * ctor,
tr_ctorMode mode,
tr_bool isPaused );
/** @brief Set the priorities for files in a torrent */
void tr_ctorSetFilePriorities( tr_ctor * ctor,
const tr_file_index_t * files,
tr_file_index_t fileCount,
tr_priority_t priority );
/** @brief Set the download flag for files in a torrent */
void tr_ctorSetFilesWanted( tr_ctor * ctor,
const tr_file_index_t * fileIndices,
tr_file_index_t fileCount,
tr_bool wanted );
/** @brief Get this peer constructor's peer limit */
int tr_ctorGetPeerLimit( const tr_ctor * ctor,
tr_ctorMode mode,
uint16_t * setmeCount );
/** @brief Get the "isPaused" flag from this peer constructor */
int tr_ctorGetPaused( const tr_ctor * ctor,
tr_ctorMode mode,
tr_bool * setmeIsPaused );
/** @brief Get the download path from this peer constructor */
int tr_ctorGetDownloadDir( const tr_ctor * ctor,
tr_ctorMode mode,
const char ** setmeDownloadDir );
/** @brief Get the incomplete directory from this peer constructor */
int tr_ctorGetIncompleteDir( const tr_ctor * ctor,
const char ** setmeIncompleteDir );
/** @brief Get the metainfo from this peer constructor */
int tr_ctorGetMetainfo( const tr_ctor * ctor,
const struct tr_benc ** setme );
/** @brief Get the "delete .torrent file" flag from this peer constructor */
int tr_ctorGetDeleteSource( const tr_ctor * ctor,
tr_bool * setmeDoDelete );
/** @brief Get the tr_session poiner from this peer constructor */
tr_session* tr_ctorGetSession( const tr_ctor * ctor );
/* returns NULL if tr_ctorSetMetainfoFromFile() wasn't used */
/** @brief Get the .torrent file that this ctor's metainfo came from, or NULL if tr_ctorSetMetainfoFromFile() wasn't used */
const char* tr_ctorGetSourceFile( const tr_ctor * ctor );
typedef enum
@ -1581,7 +1592,7 @@ struct tr_info
tr_bool isMultifile;
};
static TR_INLINE tr_bool tr_torrentHasMetadata( const tr_torrent * tor )
static inline tr_bool tr_torrentHasMetadata( const tr_torrent * tor )
{
return tr_torrentInfo( tor )->fileCount > 0;
}
@ -1805,10 +1816,10 @@ void tr_torrentSetDoneDate( tr_torrent * torrent, time_t doneDate );
/** @} */
/** @brief Sanity checker to test that the direction is TR_UP or TR_DOWN */
static TR_INLINE tr_bool tr_isDirection( tr_direction d ) { return d==TR_UP || d==TR_DOWN; }
static inline tr_bool tr_isDirection( tr_direction d ) { return d==TR_UP || d==TR_DOWN; }
/** @brief Sanity checker to test that a bool is TRUE or FALSE */
static TR_INLINE tr_bool tr_isBool( tr_bool b ) { return b==1 || b==0; }
static inline tr_bool tr_isBool( tr_bool b ) { return b==1 || b==0; }
#ifdef __cplusplus
}

190
libtransmission/utils.h
View File

@ -120,17 +120,15 @@ void tr_msgInit( void );
extern int messageLevel;
static TR_INLINE tr_bool tr_msgLoggingIsActive( int level )
static inline tr_bool tr_msgLoggingIsActive( int level )
{
return messageLevel >= level;
}
void tr_msg( const char * file,
int line,
int level,
const char * torrent,
const char * fmt,
... ) TR_GNUC_PRINTF( 5, 6 );
void tr_msg( const char * file, int line,
int level,
const char * torrent,
const char * fmt, ... ) TR_GNUC_PRINTF( 5, 6 );
#define tr_nerr( n, ... ) \
do { \
@ -202,8 +200,11 @@ char* tr_getLogTimeStr( char * buf,
int buflen ) TR_GNUC_NONNULL(1);
int tr_wildmat( const char * text,
const char * pattern ) TR_GNUC_NONNULL(1,2);
/**
* @brief Rich Salz's classic implementation of shell-style pattern matching for ?, \, [], and * characters.
* @return 1 if the pattern matches, 0 if it doesn't, or -1 if an error occured
*/
int tr_wildmat( const char * text, const char * pattern ) TR_GNUC_NONNULL(1,2);
/** @brief Portability wrapper for basename() that uses the system implementation if available */
char* tr_basename( const char * path ) TR_GNUC_MALLOC;
@ -214,14 +215,13 @@ char* tr_dirname( const char * path ) TR_GNUC_MALLOC;
/**
* @brief Portability wrapper for mkdir()
*
* a portability wrapper around mkdir().
* A portability wrapper around mkdir().
* On WIN32, the `permissions' argument is unused.
*
* @return zero on success, or -1 if an error occurred
* (in which case errno is set appropriately).
*/
int tr_mkdir( const char * path,
int permissions ) TR_GNUC_NONNULL(1);
int tr_mkdir( const char * path, int permissions ) TR_GNUC_NONNULL(1);
/**
* Like mkdir, but makes parent directories as needed.
@ -236,7 +236,8 @@ int tr_mkdirp( const char * path, int permissions ) TR_GNUC_NONNULL(1);
* @brief Loads a file and returns its contents.
* On failure, NULL is returned and errno is set.
*/
uint8_t* tr_loadFile( const char * filename, size_t * size ) TR_GNUC_MALLOC TR_GNUC_NONNULL(1);
uint8_t* tr_loadFile( const char * filename, size_t * size ) TR_GNUC_MALLOC
TR_GNUC_NONNULL(1);
/** @brief build a filename from a series of elements using the
@ -246,19 +247,31 @@ char* tr_buildPath( const char * first_element, ... ) TR_GNUC_NULL_TERMINATED
struct event;
void tr_timerAdd( struct event * timer, int seconds, int microseconds );
/**
* @brief Convenience wrapper around timer_add() to have a timer wake up in a number of seconds and microseconds
* @param timer
* @param seconds
* @param microseconds
*/
void tr_timerAdd( struct event * timer, int seconds, int microseconds ) TR_GNUC_NONNULL(1);
void tr_timerAddMsec( struct event * timer, int milliseconds );
/**
* @brief Convenience wrapper around timer_add() to have a timer wake up in a number of milliseconds
* @param timer
* @param milliseconds
*/
void tr_timerAddMsec( struct event * timer, int milliseconds ) TR_GNUC_NONNULL(1);
/** @brief return the current date in milliseconds */
uint64_t tr_date( void );
uint64_t tr_date( void );
/** @brief wait the specified number of milliseconds */
void tr_wait( uint64_t delay_milliseconds );
/** @brief sleep the specified number of milliseconds */
void tr_wait( uint64_t delay_milliseconds );
/**
* @brief make a copy of 'str' whose non-utf8 content has been corrected or stripped
* @return a newly-allocated string that must be freed with tr_free()
* @param str the string to make a clean copy of
* @param len the length of the string to copy. If -1, the entire string is used.
* @param err if an error occurs and err is non-NULL, it's set to TRUE.
@ -283,20 +296,32 @@ char* tr_utf8clean( const char * str, int len, tr_bool * err ) TR_GNUC_MALLOC;
****
***/
static TR_INLINE void* tr_malloc( size_t size )
/** @brief Portability wrapper around malloc() in which `0' is a safe argument */
static inline void* tr_malloc( size_t size )
{
return size ? malloc( size ) : NULL;
}
static TR_INLINE void* tr_malloc0( size_t size )
/** @brief Portability wrapper around calloc() in which `0' is a safe argument */
static inline void* tr_malloc0( size_t size )
{
return size ? calloc( 1, size ) : NULL;
}
static TR_INLINE void tr_free( void * p )
/** @brief Portability wrapper around free() in which `NULL' is a safe argument */
static inline void tr_free( void * p )
{
if( p != NULL )
free( p );
}
static TR_INLINE void* tr_memdup( const void * src, int byteCount )
/**
* @brief make a newly-allocated copy of a chunk of memory
* @param src the memory to copy
* @param byteCount the number of bytes to copy
* @return a newly-allocated copy of `src' that can be freed with tr_free()
*/
static inline void* tr_memdup( const void * src, int byteCount )
{
return memcpy( tr_malloc( byteCount ), src, byteCount );
}
@ -310,16 +335,25 @@ static TR_INLINE void* tr_memdup( const void * src, int byteCount )
#define tr_renew( struct_type, mem, n_structs ) \
( (struct_type *) realloc ( ( mem ), ( (size_t) sizeof ( struct_type ) ) * ( ( size_t) ( n_structs ) ) ) )
/** @param in is a void* so that callers can pass in both signed & unsigned without a cast */
/**
* @brief make a newly-allocated copy of a substring
* @param in is a void* so that callers can pass in both signed & unsigned without a cast
* @param len length of the substring to copy. if a length less than zero is passed in, strlen( len ) is used
* @return a newly-allocated copy of `in' that can be freed with tr_free()
*/
char* tr_strndup( const void * in, int len ) TR_GNUC_MALLOC;
/** @param in is a void* so that callers can pass in both signed & unsigned without a cast */
static TR_INLINE char* tr_strdup( const void * in )
/**
* @brief make a newly-allocated copy of a string
* @param in is a void* so that callers can pass in both signed & unsigned without a cast
* @return a newly-allocated copy of `in' that can be freed with tr_free()
*/
static inline char* tr_strdup( const void * in )
{
return tr_strndup( in, in ? strlen( (const char *) in ) : 0 );
}
/* @brief same argument list as bsearch() */
/** @brief similar to bsearch() but returns the index of the lower bound */
int tr_lowerBound( const void * key,
const void * base,
size_t nmemb,
@ -328,16 +362,28 @@ int tr_lowerBound( const void * key,
tr_bool * exact_match ) TR_GNUC_HOT TR_GNUC_NONNULL(1,5,6);
char* tr_strdup_printf( const char * fmt,
... ) TR_GNUC_PRINTF( 1, 2 ) TR_GNUC_MALLOC;
/**
* @brief sprintf() a string into a newly-allocated buffer large enough to hold it
* @return a newly-allocated string that can be freed with tr_free()
*/
char* tr_strdup_printf( const char * fmt, ... ) TR_GNUC_PRINTF( 1, 2 )
TR_GNUC_MALLOC;
char* tr_base64_encode( const void * input,
int inlen,
int * outlen ) TR_GNUC_MALLOC;
/**
* @brief Translate a block of bytes into base64
* @return a newly-allocated string that can be freed with tr_free()
*/
char* tr_base64_encode( const void * input,
int inlen,
int * outlen ) TR_GNUC_MALLOC;
char* tr_base64_decode( const void * input,
int inlen,
int * outlen ) TR_GNUC_MALLOC;
/**
* @brief Translate a block of bytes from base64 into raw form
* @return a newly-allocated string that can be freed with tr_free()
*/
char* tr_base64_decode( const void * input,
int inlen,
int * outlen ) TR_GNUC_MALLOC;
/** @brief Portability wrapper for strlcpy() that uses the system implementation if available */
size_t tr_strlcpy( char * dst, const void * src, size_t siz );
@ -346,6 +392,8 @@ size_t tr_strlcpy( char * dst, const void * src, size_t siz );
int tr_snprintf( char * buf, size_t buflen,
const char * fmt, ... ) TR_GNUC_PRINTF( 3, 4 ) TR_GNUC_NONNULL(1,3);
/** @brief Convenience wrapper around strerorr() guaranteed to not return NULL
@param errno */
const char* tr_strerror( int );
/** @brief strips leading and trailing whitspace from a string
@ -362,33 +410,60 @@ const char* tr_memmem( const char * haystack, size_t haystack_len,
typedef void ( tr_set_func )( void * element, void * userData );
void tr_set_compare( const void * a, size_t aCount,
const void * b, size_t bCount,
int compare( const void * a, const void * b ),
size_t elementSize,
tr_set_func in_a_cb,
tr_set_func in_b_cb,
tr_set_func in_both_cb,
void * userData );
/**
* @brief find the differences and commonalities in two sorted sets
* @param a the first set
* @param aCount the number of elements in the set 'a'
* @param b the second set
* @param bCount the number of elements in the set 'b'
* @param compare the sorting method for both sets
* @param elementSize the sizeof the element in the two sorted sets
* @param in_a called for items in set 'a' but not set 'b'
* @param in_b called for items in set 'b' but not set 'a'
* @param in_both called for items that are in both sets
* @param userData user data passed along to in_a, in_b, and in_both
*/
void tr_set_compare( const void * a, size_t aCount,
const void * b, size_t bCount,
int compare( const void * a, const void * b ),
size_t elementSize,
tr_set_func in_a_cb,
tr_set_func in_b_cb,
tr_set_func in_both_cb,
void * userData );
void tr_sha1_to_hex( char * out,
const uint8_t * sha1 ) TR_GNUC_NONNULL(1,2);
void tr_sha1_to_hex( char * out, const uint8_t * sha1 ) TR_GNUC_NONNULL(1,2);
void tr_hex_to_sha1( uint8_t * out,
const char * hex ) TR_GNUC_NONNULL(1,2);
void tr_hex_to_sha1( uint8_t * out, const char * hex ) TR_GNUC_NONNULL(1,2);
/** @brief return TRUE if the url is a http, https, or ftp url that Transmission understands */
tr_bool tr_httpIsValidURL( const char * url ) TR_GNUC_NONNULL(1);
/** @brief parse a URL into its component parts
@return zero on success or an error number if an error occurred */
int tr_httpParseURL( const char * url,
int url_len,
char ** setme_host,
int * setme_port,
char ** setme_path ) TR_GNUC_NONNULL(1);
char ** setme_host,
int * setme_port,
char ** setme_path ) TR_GNUC_NONNULL(1);
/** @brief return TR_RATIO_NA, TR_RATIO_INF, or a number in [0..1]
@return TR_RATIO_NA, TR_RATIO_INF, or a number in [0..1] */
double tr_getRatio( double numerator, double denominator );
int* tr_parseNumberRange( const char * str, int str_len, int * setmeCount ) TR_GNUC_MALLOC TR_GNUC_NONNULL(1);
/**
* @brief Given a string like "1-4" or "1-4,6,9,14-51", this returns a
* newly-allocated array of all the integers in the set.
* @return a newly-allocated array of integers that must be freed with tr_free(),
* or NULL if a fragment of the string can't be parsed.
*
* For example, "5-8" will return [ 5, 6, 7, 8 ] and setmeCount will be 4.
*/
int* tr_parseNumberRange( const char * str,
int str_len,
int * setmeCount ) TR_GNUC_MALLOC TR_GNUC_NONNULL(1);
/* truncate a double value at a given number of decimal places.
@ -421,7 +496,7 @@ struct tm * tr_localtime_r( const time_t *_clock, struct tm *_result );
int tr_moveFile( const char * oldpath, const char * newpath,
tr_bool * renamed ) TR_GNUC_NONNULL(1,2);
static TR_INLINE void tr_removeElementFromArray( void * array,
static inline void tr_removeElementFromArray( void * array,
int index_to_remove,
size_t sizeof_element,
size_t nmemb )
@ -439,8 +514,19 @@ static TR_INLINE void tr_removeElementFromArray( void * array,
extern time_t transmission_now;
static TR_INLINE time_t tr_time( void ) { return transmission_now; }
/**
* @brief very inexpensive form of time(NULL)
* @return the current epoch time in seconds
*
* This function returns a second counter that is updated once per second.
* If something blocks the libtransmission thread for more than a second,
* that counter may be thrown off, so this function is not guaranteed
* to always be accurate. However, it is *much* faster when 100% accuracy
* isn't needed
*/
static inline time_t tr_time( void ) { return transmission_now; }
/** @brief Private libtransmission function to update the second counter used by tr_time() */
void tr_timeUpdate( time_t now );
/***