From e61e0fcd3d4595014764d9c41351fff41215d790 Mon Sep 17 00:00:00 2001 From: Charles Kerr Date: Fri, 1 Jan 2010 22:13:27 +0000 Subject: [PATCH] (trunk libT) improved API documentation / commenting for doxygen --- libtransmission/platform.h | 31 ++++-- libtransmission/ptrarray.c | 8 -- libtransmission/ptrarray.h | 80 +++++++++----- libtransmission/tr-getopt.h | 22 ++-- libtransmission/transmission.h | 67 +++++++----- libtransmission/utils.h | 190 ++++++++++++++++++++++++--------- 6 files changed, 265 insertions(+), 133 deletions(-) diff --git a/libtransmission/platform.h b/libtransmission/platform.h index 2824f1e88..1d8fc1267 100644 --- a/libtransmission/platform.h +++ b/libtransmission/platform.h @@ -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, diff --git a/libtransmission/ptrarray.c b/libtransmission/ptrarray.c index 1506cc7c7..8dfc956b0 100644 --- a/libtransmission/ptrarray.c +++ b/libtransmission/ptrarray.c @@ -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, diff --git a/libtransmission/ptrarray.h b/libtransmission/ptrarray.h index 05bf1cc21..40b28023f 100644 --- a/libtransmission/ptrarray.h +++ b/libtransmission/ptrarray.h @@ -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; +} + + +/** @brief Peek at the array pointer and its size, for easy iteration */ +void** tr_ptrArrayPeek( tr_ptrArray * array, int * size ); -static TR_INLINE void tr_ptrArrayClear( tr_ptrArray * a ) { a->n_items = 0; } +static inline void tr_ptrArrayClear( tr_ptrArray * a ) { a->n_items = 0; } -int tr_ptrArrayInsert( tr_ptrArray * array, - void * insertMe, - int pos ); +/** @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 ); -static TR_INLINE int tr_ptrArrayAppend( tr_ptrArray * array, void * appendMe ) +/** @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*) ); - -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 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*) ); + +/** @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*) ); + +/** @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 diff --git a/libtransmission/tr-getopt.h b/libtransmission/tr-getopt.h index 0d9ba24eb..69683e001 100644 --- a/libtransmission/tr-getopt.h +++ b/libtransmission/tr-getopt.h @@ -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" */ diff --git a/libtransmission/transmission.h b/libtransmission/transmission.h index 686370e91..db6e39788 100644 --- a/libtransmission/transmission.h +++ b/libtransmission/transmission.h @@ -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 } diff --git a/libtransmission/utils.h b/libtransmission/utils.h index 032139c78..ad16b3a87 100644 --- a/libtransmission/utils.h +++ b/libtransmission/utils.h @@ -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 ); /*** -- 2.40.0