Changeset 9845


Ignore:
Timestamp:
Jan 1, 2010, 10:13:27 PM (12 years ago)
Author:
charles
Message:

(trunk libT) improved API documentation / commenting for doxygen

Location:
trunk/libtransmission
Files:
6 edited

Legend:

Unmodified
Added
Removed
  • trunk/libtransmission/platform.h

    r9765 r9845  
    5353
    5454
    55 tr_thread*          tr_threadNew( void   ( *func )(void *),
    56                                   void * arg );
     55/***
     56****
     57***/
    5758
    58 int                 tr_amInThread( const tr_thread * );
     59/** @brief Instantiate a new process thread */
     60tr_thread* tr_threadNew( void ( *func )(void *), void * arg );
    5961
    60 tr_lock *           tr_lockNew( void );
     62/** @brief Return nonzero if this function is being called from `thread'
     63    @param thread the thread being tested */
     64int tr_amInThread( const tr_thread * );
    6165
    62 void                tr_lockFree( tr_lock * );
     66/***
     67****
     68***/
    6369
    64 void                tr_lockLock( tr_lock * );
     70/** @brief Create a new thread mutex object */
     71tr_lock * tr_lockNew( void );
    6572
    66 void                tr_lockUnlock( tr_lock * );
     73/** @brief Destroy a thread mutex object */
     74void tr_lockFree( tr_lock * );
    6775
    68 int                 tr_lockHave( const tr_lock * );
     76/** @brief Attempt to lock a thread mutex object */
     77void tr_lockLock( tr_lock * );
     78
     79/** @brief Unlock a thread mutex object */
     80void tr_lockUnlock( tr_lock * );
     81
     82/** @brief return nonzero if the specified lock is locked */
     83int tr_lockHave( const tr_lock * );
    6984
    7085#ifdef WIN32
  • trunk/libtransmission/ptrarray.c

    r9836 r9845  
    6767
    6868    return t->items[i];
    69 }
    70 
    71 void*
    72 tr_ptrArrayBack( tr_ptrArray* t )
    73 {
    74     assert( t->n_items > 0 );
    75 
    76     return tr_ptrArrayNth( t, t->n_items - 1 );
    7769}
    7870
  • trunk/libtransmission/ptrarray.h

    r9671 r9845  
    4040extern const tr_ptrArray TR_PTR_ARRAY_INIT;
    4141
    42 void          tr_ptrArrayDestruct( tr_ptrArray*, PtrArrayForeachFunc func );
     42/** @brief Destructor to free a tr_ptrArray's internal memory */
     43void tr_ptrArrayDestruct( tr_ptrArray*, PtrArrayForeachFunc func );
    4344
    44 void          tr_ptrArrayForeach( tr_ptrArray         * array,
    45                                   PtrArrayForeachFunc   func );
     45/** @brief Iterate through each item in a tr_ptrArray */
     46void tr_ptrArrayForeach( tr_ptrArray         * array,
     47                         PtrArrayForeachFunc   func );
    4648
     49/** @brief Return the nth item in a tr_ptrArray
     50    @return the nth item in a tr_ptrArray */
    4751void*         tr_ptrArrayNth( tr_ptrArray   * array,
    4852                              int             nth );
    4953
    50 void*         tr_ptrArrayBack( tr_ptrArray  * array );
     54/** @brief Remove the last item from the array and return it
     55    @return the pointer that's been removed from the array
     56    @see tr_ptrArrayBack() */
     57void* tr_ptrArrayPop( tr_ptrArray * array );
    5158
    52 void**        tr_ptrArrayPeek( tr_ptrArray  * array,
    53                                int          * size );
     59/** @brief Return the last item in a tr_ptrArray
     60    @return the last item in a tr_ptrArray, or NULL if the array is empty
     61    @see tr_ptrArrayPop() */
     62static inline void* tr_ptrArrayBack( tr_ptrArray * array )
     63{
     64    return array->n_items > 0 ? tr_ptrArrayNth( array, array->n_items - 1 )
     65                              : NULL;
     66}
    5467
    55 static TR_INLINE void  tr_ptrArrayClear( tr_ptrArray * a ) { a->n_items = 0; }
    5668
    57 int           tr_ptrArrayInsert( tr_ptrArray * array,
    58                                  void        * insertMe,
    59                                  int           pos );
     69/** @brief Peek at the array pointer and its size, for easy iteration */
     70void** tr_ptrArrayPeek( tr_ptrArray * array, int * size );
    6071
    61 static TR_INLINE int tr_ptrArrayAppend( tr_ptrArray * array, void * appendMe )
     72static inline void  tr_ptrArrayClear( tr_ptrArray * a ) { a->n_items = 0; }
     73
     74/** @brief Insert a pointer into the array at the specified position
     75    @return the index of the stored pointer */
     76int tr_ptrArrayInsert( tr_ptrArray * array, void * insertMe, int pos );
     77
     78/** @brief Append a pointer into the array */
     79static inline int tr_ptrArrayAppend( tr_ptrArray * array, void * appendMe )
    6280{
    6381    return tr_ptrArrayInsert( array, appendMe, -1 );
    6482}
    6583
    66 void*         tr_ptrArrayPop( tr_ptrArray    * array );
    67 
    68 static TR_INLINE void** tr_ptrArrayBase( const tr_ptrArray * a )
     84static inline void** tr_ptrArrayBase( const tr_ptrArray * a )
    6985{
    7086    return a->items;
    7187}
    7288
    73 static TR_INLINE int tr_ptrArraySize( const tr_ptrArray *  a )
     89/** @brief Return the number of items in the array
     90    @return the number of items in the array */
     91static inline int tr_ptrArraySize( const tr_ptrArray *  a )
    7492{
    7593    return a->n_items;
    7694}
    7795
    78 static TR_INLINE tr_bool tr_ptrArrayEmpty( const tr_ptrArray * a )
     96/** @brief Return True if the array has no pointers
     97    @return True if the array has no pointers */
     98static inline tr_bool tr_ptrArrayEmpty( const tr_ptrArray * a )
    7999{
    80100    return tr_ptrArraySize(a) == 0;
    81101}
    82102
    83 int           tr_ptrArrayInsertSorted( tr_ptrArray * array,
    84                                        void        * value,
    85                                        int compare(const void*, const void*) );
     103/** @brief Insert a pointer into the array at the position determined by the sort function
     104    @return the index of the stored pointer */
     105int tr_ptrArrayInsertSorted( tr_ptrArray * array,
     106                             void        * value,
     107                             int compare(const void*, const void*) );
    86108
    87 void*         tr_ptrArrayRemoveSorted( tr_ptrArray * array,
    88                                        void        * value,
    89                                        int compare(const void*, const void*) );
     109/** @brief Remove a pointer from an array sorted by the specified sort function
     110    @return the matching pointer, or NULL if no match was found */
     111void* tr_ptrArrayRemoveSorted( tr_ptrArray * array,
     112                               void        * value,
     113                               int compare(const void*, const void*) );
    90114
    91 void*         tr_ptrArrayFindSorted( tr_ptrArray * array,
    92                                      const void  * key,
    93                                      int compare(const void*, const void*) );
     115/** @brief Find a pointer from an array sorted by the specified sort function
     116    @return the matching pointer, or NULL if no match was found */
     117void* tr_ptrArrayFindSorted( tr_ptrArray * array,
     118                             const void  * key,
     119                             int compare(const void*, const void*) );
    94120
    95121/* @} */
  • trunk/libtransmission/tr-getopt.h

    r9671 r9845  
    2323 */
    2424
     25/** @brief Similar to optind, this is the current index into argv */
    2526extern int tr_optind;
    2627
     
    5051
    5152/**
    52  * @return TR_GETOPT_DONE, TR_GETOPT_ERR, TR_GETOPT_UNK,
    53  *         or the matching tr_option's `val' field
     53 * @brief similar to getopt()
     54 * @return TR_GETOPT_DONE, TR_GETOPT_ERR, TR_GETOPT_UNK, or the matching tr_option's `val' field
    5455 */
    55 int  tr_getopt( const char *      summary,
    56                 int               argc,
    57                 const char **    argv,
    58                 const tr_option * opts,
    59                 const char **    setme_optarg );
     56int  tr_getopt( const char       * summary,
     57                int                argc,
     58                const char      ** argv,
     59                const tr_option  * opts,
     60                const char      ** setme_optarg );
    6061
    61 void tr_getopt_usage( const char *      appName,
    62                       const char *      description,
    63                       const tr_option * opts );
     62/** @brief prints the `Usage' help section to stdout */
     63void tr_getopt_usage( const char       * appName,
     64                      const char       * description,
     65                      const tr_option  * opts );
    6466
    6567#ifdef __cplusplus
  • trunk/libtransmission/transmission.h

    r9817 r9845  
    5656
    5757#if defined(WIN32) && defined(_MSC_VER)
    58  #define TR_INLINE __inline
    59 #else
    60  #define TR_INLINE inline
     58 #define inline __inline
    6159#endif
    6260
     
    304302                             struct tr_benc * settings );
    305303
     304/** @brief Update a session's settings from a benc dictionary like to the one used in tr_sessionInit() */
    306305void tr_sessionSet( tr_session      * session,
    307306                    struct tr_benc  * settings );
    308307
     308/** @brief Rescan the blocklists directory and reload whatever blocklist files are found there */
    309309void tr_sessionReloadBlocklists( tr_session * session );
    310310
     
    853853struct tr_benc;
    854854
    855 /* it's okay to use NULL here if you're only parsing the torrent.
    856  * @see tr_torrentParse() */
    857 tr_ctor*    tr_ctorNew( const tr_session * session_or_NULL );
    858 
    859 void        tr_ctorFree( tr_ctor * ctor );
    860 
    861 void        tr_ctorSetDeleteSource( tr_ctor * ctor,
    862                                     tr_bool   doDelete );
    863 
    864 int         tr_ctorSetMagnet( tr_ctor * ctor,
    865                               const char * url );
    866 
    867 int         tr_ctorSetMetainfo( tr_ctor *       ctor,
    868                                 const uint8_t * metainfo,
    869                                 size_t          len );
    870 
    871 int         tr_ctorSetMetainfoFromFile( tr_ctor *    ctor,
    872                                         const char * filename );
    873 
    874 int         tr_ctorSetMetainfoFromHash( tr_ctor *    ctor,
    875                                         const char * hashString );
    876 
    877 /** Set the maximum number of peers this torrent can connect to.
    878     (Default: 50) */
    879 void        tr_ctorSetPeerLimit( tr_ctor *   ctor,
    880                                  tr_ctorMode mode,
    881                                  uint16_t    peerLimit  );
    882 
    883 /** Set the download folder for the torrent being added with this ctor.
     855/** @brief Create a new torrent constructor object used to instantiate a tr_torrent
     856    @param session the tr_session.  NULL is allowed if you're only calling tr_torrentParse() rather than tr_torrentNew()
     857    @see tr_torrentNew(), tr_torrentParse() */
     858tr_ctor* tr_ctorNew( const tr_session * session_or_NULL );
     859
     860/** @brief Free a torrent constructor object */
     861void  tr_ctorFree( tr_ctor * ctor );
     862
     863/** @brief Set whether or not to delete the source .torrent file when a torrent is added. (Default: False) */
     864void  tr_ctorSetDeleteSource( tr_ctor * ctor, tr_bool doDelete );
     865
     866/** @brief Set the link for creating a tr_torrent from a magnet link */
     867int tr_ctorSetMagnet( tr_ctor * ctor, const char * magnet_link );
     868
     869/** @brief Set the constructor's metainfo from a raw benc already in memory */
     870int tr_ctorSetMetainfo( tr_ctor * ctor, const uint8_t * metainfo, size_t len );
     871
     872/** @brief Set the constructor's metainfo from a local .torrent file */
     873int tr_ctorSetMetainfoFromFile( tr_ctor * ctor, const char * filename );
     874
     875/**
     876 * @brief Set the constructor's metainfo from an already-existing file in tr_getTorrentDir().
     877 *
     878 * This is used by the mac client on startup to pick and choose which existing torrents to load
     879 */
     880int tr_ctorSetMetainfoFromHash( tr_ctor * ctor, const char * hashString );
     881
     882/** @brief Set the maximum number of peers this torrent can connect to. (Default: 50) */
     883void tr_ctorSetPeerLimit( tr_ctor * ctor, tr_ctorMode mode, uint16_t peerLimit  );
     884
     885/** @brief Set the download folder for the torrent being added with this ctor.
    884886    @see tr_ctorSetDownloadDir()
    885887    @see tr_sessionInit() */
     
    904906                              tr_bool        isPaused );
    905907
     908/** @brief Set the priorities for files in a torrent */
    906909void        tr_ctorSetFilePriorities( tr_ctor                * ctor,
    907910                                      const tr_file_index_t  * files,
     
    909912                                      tr_priority_t            priority );
    910913
     914/** @brief Set the download flag for files in a torrent */
    911915void        tr_ctorSetFilesWanted( tr_ctor                * ctor,
    912916                                   const tr_file_index_t  * fileIndices,
     
    915919
    916920
     921/** @brief Get this peer constructor's peer limit */
    917922int         tr_ctorGetPeerLimit( const tr_ctor * ctor,
    918923                                 tr_ctorMode     mode,
    919924                                 uint16_t *      setmeCount );
    920925
     926/** @brief Get the "isPaused" flag from this peer constructor */
    921927int         tr_ctorGetPaused( const tr_ctor * ctor,
    922928                              tr_ctorMode     mode,
    923929                              tr_bool       * setmeIsPaused );
    924930
     931/** @brief Get the download path from this peer constructor */
    925932int         tr_ctorGetDownloadDir( const tr_ctor  * ctor,
    926933                                   tr_ctorMode      mode,
    927934                                   const char    ** setmeDownloadDir );
    928935
     936/** @brief Get the incomplete directory from this peer constructor */
    929937int         tr_ctorGetIncompleteDir( const tr_ctor  * ctor,
    930938                                     const char    ** setmeIncompleteDir );
    931939
     940/** @brief Get the metainfo from this peer constructor */
    932941int         tr_ctorGetMetainfo( const tr_ctor         * ctor,
    933942                                const struct tr_benc ** setme );
    934943
     944/** @brief Get the "delete .torrent file" flag from this peer constructor */
    935945int         tr_ctorGetDeleteSource( const tr_ctor  * ctor,
    936946                                    tr_bool        * setmeDoDelete );
    937947
     948/** @brief Get the tr_session poiner from this peer constructor */
    938949tr_session* tr_ctorGetSession( const tr_ctor * ctor );
    939950
    940 /* returns NULL if tr_ctorSetMetainfoFromFile() wasn't used */
     951/** @brief Get the .torrent file that this ctor's metainfo came from, or NULL if tr_ctorSetMetainfoFromFile() wasn't used */
    941952const char* tr_ctorGetSourceFile( const tr_ctor * ctor );
    942953
     
    15821593};
    15831594
    1584 static TR_INLINE tr_bool tr_torrentHasMetadata( const tr_torrent * tor )
     1595static inline tr_bool tr_torrentHasMetadata( const tr_torrent * tor )
    15851596{
    15861597    return tr_torrentInfo( tor )->fileCount > 0;
     
    18061817
    18071818/** @brief Sanity checker to test that the direction is TR_UP or TR_DOWN */
    1808 static TR_INLINE tr_bool tr_isDirection( tr_direction d ) { return d==TR_UP || d==TR_DOWN; }
     1819static inline tr_bool tr_isDirection( tr_direction d ) { return d==TR_UP || d==TR_DOWN; }
    18091820
    18101821/** @brief Sanity checker to test that a bool is TRUE or FALSE */
    1811 static TR_INLINE tr_bool tr_isBool( tr_bool b ) { return b==1 || b==0; }
     1822static inline tr_bool tr_isBool( tr_bool b ) { return b==1 || b==0; }
    18121823
    18131824#ifdef __cplusplus
  • trunk/libtransmission/utils.h

    r9833 r9845  
    121121extern int messageLevel;
    122122
    123 static TR_INLINE tr_bool tr_msgLoggingIsActive( int level )
     123static inline tr_bool tr_msgLoggingIsActive( int level )
    124124{
    125125    return messageLevel >= level;
    126126}
    127127
    128 void           tr_msg( const char * file,
    129                        int          line,
    130                        int          level,
    131                        const char * torrent,
    132                        const char * fmt,
    133                        ... ) TR_GNUC_PRINTF( 5, 6 );
     128void tr_msg( const char * file, int line,
     129             int level,
     130             const char * torrent,
     131             const char * fmt, ... ) TR_GNUC_PRINTF( 5, 6 );
    134132
    135133#define tr_nerr( n, ... ) \
     
    203201
    204202
    205 int            tr_wildmat( const char * text,
    206                            const char * pattern ) TR_GNUC_NONNULL(1,2);
     203/**
     204 * @brief Rich Salz's classic implementation of shell-style pattern matching for ?, \, [], and * characters.
     205 * @return 1 if the pattern matches, 0 if it doesn't, or -1 if an error occured
     206 */
     207int tr_wildmat( const char * text, const char * pattern ) TR_GNUC_NONNULL(1,2);
    207208
    208209/** @brief Portability wrapper for basename() that uses the system implementation if available */
     
    215216 * @brief Portability wrapper for mkdir()
    216217 *
    217  * a portability wrapper around mkdir().
     218 * A portability wrapper around mkdir().
    218219 * On WIN32, the `permissions' argument is unused.
    219220 *
     
    221222 * (in which case errno is set appropriately).
    222223 */
    223 int            tr_mkdir( const char * path,
    224                          int          permissions ) TR_GNUC_NONNULL(1);
     224int tr_mkdir( const char * path, int permissions ) TR_GNUC_NONNULL(1);
    225225
    226226/**
     
    237237 * On failure, NULL is returned and errno is set.
    238238 */
    239 uint8_t* tr_loadFile( const char * filename, size_t * size ) TR_GNUC_MALLOC TR_GNUC_NONNULL(1);
     239uint8_t* tr_loadFile( const char * filename, size_t * size ) TR_GNUC_MALLOC
     240                                                             TR_GNUC_NONNULL(1);
    240241
    241242
     
    247248struct event;
    248249
    249 void tr_timerAdd( struct event * timer, int seconds, int microseconds );
    250 
    251 void tr_timerAddMsec( struct event * timer, int milliseconds );
     250/**
     251 * @brief Convenience wrapper around timer_add() to have a timer wake up in a number of seconds and microseconds
     252 * @param timer
     253 * @param seconds
     254 * @param microseconds
     255 */
     256void tr_timerAdd( struct event * timer, int seconds, int microseconds ) TR_GNUC_NONNULL(1);
     257
     258/**
     259 * @brief Convenience wrapper around timer_add() to have a timer wake up in a number of milliseconds
     260 * @param timer
     261 * @param milliseconds
     262 */
     263void tr_timerAddMsec( struct event * timer, int milliseconds ) TR_GNUC_NONNULL(1);
    252264
    253265
    254266/** @brief return the current date in milliseconds */
    255 uint64_t       tr_date( void );
    256 
    257 /** @brief wait the specified number of milliseconds */
    258 void           tr_wait( uint64_t delay_milliseconds );
     267uint64_t tr_date( void );
     268
     269/** @brief sleep the specified number of milliseconds */
     270void tr_wait( uint64_t delay_milliseconds );
    259271
    260272/**
    261273 * @brief make a copy of 'str' whose non-utf8 content has been corrected or stripped
     274 * @return a newly-allocated string that must be freed with tr_free()
    262275 * @param str the string to make a clean copy of
    263276 * @param len the length of the string to copy.  If -1, the entire string is used.
     
    284297***/
    285298
    286 static TR_INLINE void* tr_malloc( size_t size )
     299/** @brief Portability wrapper around malloc() in which `0' is a safe argument */
     300static inline void* tr_malloc( size_t size )
    287301{
    288302    return size ? malloc( size ) : NULL;
    289303}
    290 static TR_INLINE void* tr_malloc0( size_t size )
     304
     305/** @brief Portability wrapper around calloc() in which `0' is a safe argument */
     306static inline void* tr_malloc0( size_t size )
    291307{
    292308    return size ? calloc( 1, size ) : NULL;
    293309}
    294 static TR_INLINE void tr_free( void * p )
     310
     311/** @brief Portability wrapper around free() in which `NULL' is a safe argument */
     312static inline void tr_free( void * p )
    295313{
    296314    if( p != NULL )
    297315        free( p );
    298316}
    299 static TR_INLINE void* tr_memdup( const void * src, int byteCount )
     317
     318/**
     319 * @brief make a newly-allocated copy of a chunk of memory
     320 * @param src the memory to copy
     321 * @param byteCount the number of bytes to copy
     322 * @return a newly-allocated copy of `src' that can be freed with tr_free()
     323 */
     324static inline void* tr_memdup( const void * src, int byteCount )
    300325{
    301326    return memcpy( tr_malloc( byteCount ), src, byteCount );
     
    311336    ( (struct_type *) realloc ( ( mem ), ( (size_t) sizeof ( struct_type ) ) * ( ( size_t) ( n_structs ) ) ) )
    312337
    313 /** @param in is a void* so that callers can pass in both signed & unsigned without a cast */
     338/**
     339 * @brief make a newly-allocated copy of a substring
     340 * @param in is a void* so that callers can pass in both signed & unsigned without a cast
     341 * @param len length of the substring to copy.  if a length less than zero is passed in, strlen( len ) is used
     342 * @return a newly-allocated copy of `in' that can be freed with tr_free()
     343 */
    314344char* tr_strndup( const void * in, int len ) TR_GNUC_MALLOC;
    315345
    316 /** @param in is a void* so that callers can pass in both signed & unsigned without a cast */
    317 static TR_INLINE char* tr_strdup( const void * in )
     346/**
     347 * @brief make a newly-allocated copy of a string
     348 * @param in is a void* so that callers can pass in both signed & unsigned without a cast
     349 * @return a newly-allocated copy of `in' that can be freed with tr_free()
     350 */
     351static inline char* tr_strdup( const void * in )
    318352{
    319353    return tr_strndup( in, in ? strlen( (const char *) in ) : 0 );
    320354}
    321355
    322 /* @brief same argument list as bsearch() */
     356/** @brief similar to bsearch() but returns the index of the lower bound */
    323357int tr_lowerBound( const void * key,
    324358                   const void * base,
     
    329363
    330364
    331 char*       tr_strdup_printf( const char * fmt,
    332                               ... )  TR_GNUC_PRINTF( 1, 2 ) TR_GNUC_MALLOC;
    333 
    334 char*       tr_base64_encode( const void * input,
    335                               int          inlen,
    336                               int *        outlen ) TR_GNUC_MALLOC;
    337 
    338 char*       tr_base64_decode( const void * input,
    339                               int          inlen,
    340                               int *        outlen ) TR_GNUC_MALLOC;
     365/**
     366 * @brief sprintf() a string into a newly-allocated buffer large enough to hold it
     367 * @return a newly-allocated string that can be freed with tr_free()
     368 */
     369char* tr_strdup_printf( const char * fmt, ... ) TR_GNUC_PRINTF( 1, 2 )
     370                                                TR_GNUC_MALLOC;
     371
     372/**
     373 * @brief Translate a block of bytes into base64
     374 * @return a newly-allocated string that can be freed with tr_free()
     375 */
     376char* tr_base64_encode( const void * input,
     377                        int          inlen,
     378                        int        * outlen ) TR_GNUC_MALLOC;
     379
     380/**
     381 * @brief Translate a block of bytes from base64 into raw form
     382 * @return a newly-allocated string that can be freed with tr_free()
     383 */
     384char* tr_base64_decode( const void * input,
     385                        int          inlen,
     386                        int        * outlen ) TR_GNUC_MALLOC;
    341387
    342388/** @brief Portability wrapper for strlcpy() that uses the system implementation if available */
     
    347393                 const char * fmt, ... ) TR_GNUC_PRINTF( 3, 4 ) TR_GNUC_NONNULL(1,3);
    348394
     395/** @brief Convenience wrapper around strerorr() guaranteed to not return NULL
     396    @param errno */
    349397const char* tr_strerror( int );
    350398
     
    363411typedef void ( tr_set_func )( void * element, void * userData );
    364412
    365 void        tr_set_compare( const void * a, size_t aCount,
    366                             const void * b, size_t bCount,
    367                             int compare( const void * a, const void * b ),
    368                             size_t elementSize,
    369                             tr_set_func in_a_cb,
    370                             tr_set_func in_b_cb,
    371                             tr_set_func in_both_cb,
    372                             void * userData );
    373 
    374 void tr_sha1_to_hex( char * out,
    375                      const uint8_t * sha1 ) TR_GNUC_NONNULL(1,2);
    376 
    377 void tr_hex_to_sha1( uint8_t * out,
    378                      const char * hex ) TR_GNUC_NONNULL(1,2);
    379 
    380 
     413/**
     414 * @brief find the differences and commonalities in two sorted sets
     415 * @param a the first set
     416 * @param aCount the number of elements in the set 'a'
     417 * @param b the second set
     418 * @param bCount the number of elements in the set 'b'
     419 * @param compare the sorting method for both sets
     420 * @param elementSize the sizeof the element in the two sorted sets
     421 * @param in_a called for items in set 'a' but not set 'b'
     422 * @param in_b called for items in set 'b' but not set 'a'
     423 * @param in_both called for items that are in both sets
     424 * @param userData user data passed along to in_a, in_b, and in_both
     425 */
     426void tr_set_compare( const void * a, size_t aCount,
     427                     const void * b, size_t bCount,
     428                     int compare( const void * a, const void * b ),
     429                     size_t elementSize,
     430                     tr_set_func in_a_cb,
     431                     tr_set_func in_b_cb,
     432                     tr_set_func in_both_cb,
     433                     void * userData );
     434
     435void tr_sha1_to_hex( char * out, const uint8_t * sha1 ) TR_GNUC_NONNULL(1,2);
     436
     437void tr_hex_to_sha1( uint8_t * out, const char * hex ) TR_GNUC_NONNULL(1,2);
     438
     439
     440/** @brief return TRUE if the url is a http, https, or ftp url that Transmission understands */
    381441tr_bool tr_httpIsValidURL( const char * url ) TR_GNUC_NONNULL(1);
    382442
     443/** @brief parse a URL into its component parts
     444    @return zero on success or an error number if an error occurred */
    383445int  tr_httpParseURL( const char * url,
    384446                      int          url_len,
    385                       char **      setme_host,
    386                       int *        setme_port,
    387                       char **      setme_path ) TR_GNUC_NONNULL(1);
    388 
     447                      char      ** setme_host,
     448                      int        * setme_port,
     449                      char      ** setme_path ) TR_GNUC_NONNULL(1);
     450
     451
     452/** @brief return TR_RATIO_NA, TR_RATIO_INF, or a number in [0..1]
     453    @return TR_RATIO_NA, TR_RATIO_INF, or a number in [0..1] */
    389454double tr_getRatio( double numerator, double denominator );
    390455
    391 int* tr_parseNumberRange( const char * str, int str_len, int * setmeCount ) TR_GNUC_MALLOC TR_GNUC_NONNULL(1);
     456/**
     457 * @brief Given a string like "1-4" or "1-4,6,9,14-51", this returns a
     458 *        newly-allocated array of all the integers in the set.
     459 * @return a newly-allocated array of integers that must be freed with tr_free(),
     460 *         or NULL if a fragment of the string can't be parsed.
     461 *
     462 * For example, "5-8" will return [ 5, 6, 7, 8 ] and setmeCount will be 4.
     463 */
     464int* tr_parseNumberRange( const char * str,
     465                          int str_len,
     466                          int * setmeCount ) TR_GNUC_MALLOC TR_GNUC_NONNULL(1);
    392467
    393468
     
    422497                 tr_bool * renamed ) TR_GNUC_NONNULL(1,2);
    423498
    424 static TR_INLINE void tr_removeElementFromArray( void   * array,
     499static inline void tr_removeElementFromArray( void   * array,
    425500                                                 int      index_to_remove,
    426501                                                 size_t   sizeof_element,
     
    440515extern time_t transmission_now;
    441516
    442 static TR_INLINE time_t tr_time( void ) { return transmission_now; }
    443 
     517/**
     518 * @brief very inexpensive form of time(NULL)
     519 * @return the current epoch time in seconds
     520 *
     521 * This function returns a second counter that is updated once per second.
     522 * If something blocks the libtransmission thread for more than a second,
     523 * that counter may be thrown off, so this function is not guaranteed
     524 * to always be accurate.  However, it is *much* faster when 100% accuracy
     525 * isn't needed
     526 */
     527static inline time_t tr_time( void ) { return transmission_now; }
     528
     529/** @brief Private libtransmission function to update the second counter used by tr_time() */
    444530void tr_timeUpdate( time_t now );
    445531
Note: See TracChangeset for help on using the changeset viewer.