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

(trunk libT) more documentation and doxygen markup

This commit is contained in:
Charles Kerr 2010-01-06 00:18:33 +00:00
parent 182cbb8b90
commit 0d91f3cadf
8 changed files with 109 additions and 87 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
libtransmission/crypto.h
View File

@ -88,16 +88,19 @@ void tr_sha1( uint8_t * setme,
... ) TR_GNUC_NULL_TERMINATED;
/** Returns a random number in the range of [0...n) */
/** @brief Returns a random number in the range of [0...n) */
int tr_cryptoRandInt( int n );
/** Returns a vaguely random number in the range of [0...n).
This is faster -- BUT WEAKER -- than tr_cryptoRandInt()
and should only be used when tr_cryptoRandInt() is too
slow, and NEVER in sensitive cases */
/**
* @brief Returns a vaguely random number in the range of [0...n).
*
* This is faster, BUT WEAKER, than tr_cryptoRandInt() and never
* be used in sensitive cases.
* @see tr_cryptoRandInt()
*/
int tr_cryptoWeakRandInt( int n );
/** Fills a buffer with random bytes */
/** @brief Fills a buffer with random bytes */
void tr_cryptoRandBuf( void * buf, size_t len );
char* tr_ssha1( const void * plaintext );

5
libtransmission/ggets.h
View File

@ -39,7 +39,10 @@
extern "C" {
#endif
/** @ingroup utils */
/**
* @brief read a line from a file and place it in a newly-allocated string
* @ingroup utils
*/
int fggets( char* *ln, FILE * f );
#define ggets( ln ) fggets( ln, stdin )

2
libtransmission/list.c
View File

@ -177,7 +177,7 @@ __tr_list_insert( struct __tr_list * list,
prev->next = list;
}
void
static void
__tr_list_splice( struct __tr_list * prev,
struct __tr_list * next)
{

124
libtransmission/list.h
View File

@ -17,8 +17,14 @@
#ifndef TR_LIST_H
#define TR_LIST_H
/**
* @addtogroup utils Utilities
* @{
*/
#include "transmission.h" /* inline */
/** @brief simple list structure similar to glib's GList */
typedef struct tr_list
{
void * data;
@ -30,43 +36,79 @@ tr_list;
typedef int ( *TrListCompareFunc )( const void * a, const void * b );
typedef void ( *TrListForeachFunc )( void * );
/**
* @brief return the number of items in the list
* @return the number of items in the list
*/
int tr_list_size( const tr_list * list );
void tr_list_free( tr_list ** list,
TrListForeachFunc data_free_func );
/**
* @brief free the specified list and set its pointer to NULL
* @param list pointer to the list to be freed
* @param func optional function to invoke on each item in the list
*/
void tr_list_free( tr_list ** list, TrListForeachFunc data_free_func );
void tr_list_append( tr_list ** list,
void * data );
/**
* @brief append an item to the specified list
* @param list pointer to the list
* @param item the item to append
*/
void tr_list_append( tr_list ** list, void * data );
void tr_list_prepend( tr_list ** list,
void * data );
/**
* @brief prepend an item to the specified list
* @param list pointer to the list
* @param item the item to prepend
*/
void tr_list_prepend( tr_list ** list, void * data );
void* tr_list_pop_front( tr_list ** list );
/**
* @brief remove the next item in the list
* @return the next item in the list, or NULL if the list is empty
* @param list pointer to the list
*/
void* tr_list_pop_front( tr_list ** list );
void* tr_list_remove_data( tr_list ** list,
const void * data );
/**
* @brief remove the list's node that contains the specified data pointer
* @param list pointer to the list
* @param data data to remove
* @return the removed data pointer, or NULL if no match was found
*/
void* tr_list_remove_data( tr_list ** list, const void * data );
/**
* @brief remove the list's node that compares equal to "b" when compared with "compare_func"
* @param list pointer to the list
* @param b the comparison key
* @param compare_func the comparison function. The arguments passed to it will be the list's pointers and the comparison key "b"
* @return the removed data pointer, or NULL if no match was found
*/
void* tr_list_remove( tr_list ** list,
const void * b,
TrListCompareFunc compare_func );
/**
* @brief find the list node whose data that compares equal to "b" when compared with "compare_func"
* @param list pointer to the list
* @param b the comparison key
* @param compare_func the comparison function. The arguments passed to it will be the list's pointers and the comparison key "b"
* @return the matching list node, or NULL if not match was found
*/
tr_list* tr_list_find( tr_list * list,
const void * b,
TrListCompareFunc compare_func );
/*
* Double-linked list with easy memory management and fast
* insert/remove operations
*/
/** @brief Double-linked list with easy memory management and fast insert/remove operations */
struct __tr_list
{
struct __tr_list * next, * prev;
};
/**
* Given a __tr_list node that's embedded in a struct, returns a pointer to the struct.
* @brief Given a __tr_list node that's embedded in a struct, returns a pointer to the struct.
* @param ptr pointer to the embedded __tr_list
* @param type struct type that has contains the __tr_list
* @param field the name of the struct's _tr_list field
@ -77,11 +119,7 @@ typedef int ( *__tr_list_cmp_t ) ( const void * a, const void * b );
typedef void ( *__tr_list_free_t )( void * );
/**
* __tr_list_init()
*
* Init @head as an empty list.
*/
/** @brief Init @head as an empty list. */
static inline void
__tr_list_init( struct __tr_list * head )
{
@ -89,55 +127,25 @@ __tr_list_init( struct __tr_list * head )
}
/**
* __tr_list_insert()
*
* Insert @list between @prev and @next.
*/
/** @brief Insert @list between @prev and @next. */
void
__tr_list_insert( struct __tr_list * list,
struct __tr_list * prev,
struct __tr_list * next);
/**
* __tr_list_splice()
*
* Connect @prev with @next, removing any nodes that were
* in between.
*/
void
__tr_list_splice( struct __tr_list * prev,
struct __tr_list * next);
/**
* __tr_list_append()
*
* Append @list to the end of @head.
*/
/** @brief Append @list to the end of @head. */
static inline void
__tr_list_append( struct __tr_list * head,
struct __tr_list * list)
__tr_list_append( struct __tr_list * head, struct __tr_list * list)
{
__tr_list_insert( list, head->prev, head );
}
/** @brief Remove @head from the list it is in. */
void __tr_list_remove( struct __tr_list * head );
/**
* __tr_list_remove()
*
* Remove @head from the list it is in.
*/
void
__tr_list_remove( struct __tr_list * head );
/**
* __tr_list_destroy()
*
* Destroy the list and free all nodes
*/
void
__tr_list_destroy( struct __tr_list * head,
__tr_list_free_t func);
/** @brief Destroy the list and free all nodes */
void __tr_list_destroy( struct __tr_list * head, __tr_list_free_t func );
/* @} */
#endif /* TR_LIST_H */

2
libtransmission/ptrarray.h
View File

@ -25,7 +25,7 @@
*/
/**
* A simple pointer array that resizes itself dynamically.
* @brief simple pointer array that resizes itself dynamically.
*/
typedef struct tr_ptrArray
{

1
libtransmission/session.h
View File

@ -41,6 +41,7 @@ struct tr_bandwidth;
struct tr_bindsockets;
struct tr_fdInfo;
/** @brief handle to an active libtransmission session */
struct tr_session
{
tr_bool isPortRandom;

2
libtransmission/transmission.h
View File

@ -1635,7 +1635,7 @@ typedef enum
tr_stat_errtype;
/**
* The current status of a torrent.
* @brief Describes a torrent's status
* @see tr_torrentStat()
*/
typedef struct tr_stat

45
libtransmission/utils.h
View File

@ -188,7 +188,8 @@ void tr_msg( const char * file, int line,
FILE* tr_getLog( void );
tr_bool tr_deepLoggingIsActive( void );
/** @brief return true if deep logging has been enabled by the user; false otherwise */
tr_bool tr_deepLoggingIsActive( void );
void tr_deepLog( const char * file,
int line,
@ -196,8 +197,8 @@ void tr_deepLog( const char * file,
const char * fmt,
... ) TR_GNUC_PRINTF( 4, 5 ) TR_GNUC_NONNULL(1,4);
char* tr_getLogTimeStr( char * buf,
int buflen ) TR_GNUC_NONNULL(1);
/** @brief set the buffer with the current time formatted for deep logging. */
char* tr_getLogTimeStr( char * buf, int buflen ) TR_GNUC_NONNULL(1);
/**
@ -466,18 +467,20 @@ int* tr_parseNumberRange( const char * str,
int * setmeCount ) TR_GNUC_MALLOC TR_GNUC_NONNULL(1);
/* truncate a double value at a given number of decimal places.
this can be used to prevent a printf() call from rounding up:
call with the decimal_places argument equal to the number of
decimal places in the printf()'s precision:
- printf("%.2f%%", 99.999 ) ==> "100.00%"
- printf("%.2f%%", tr_truncd(99.999, 2)) ==> "99.99%"
^ ^
| These should match |
+------------------------+
*/
/**
* @brief truncate a double value at a given number of decimal places.
*
* this can be used to prevent a printf() call from rounding up:
* call with the decimal_places argument equal to the number of
* decimal places in the printf()'s precision:
*
* - printf("%.2f%%", 99.999 ) ==> "100.00%"
*
* - printf("%.2f%%", tr_truncd(99.999, 2)) ==> "99.99%"
* ^ ^
* | These should match |
* +------------------------+
*/
double tr_truncd( double x, int decimal_places );
/**
@ -492,14 +495,18 @@ char* tr_strratio( char * buf, size_t buflen, double ratio, const char * infinit
struct tm * tr_localtime_r( const time_t *_clock, struct tm *_result );
/** on success, return 0. on failure, return -1 and set errno */
/**
* @brief move a file
* @return 0 on success; otherwise, return -1 and set errno
*/
int tr_moveFile( const char * oldpath, const char * newpath,
tr_bool * renamed ) TR_GNUC_NONNULL(1,2);
/** @brief convenience function to remove an item from an array */
static inline void tr_removeElementFromArray( void * array,
int index_to_remove,
size_t sizeof_element,
size_t nmemb )
int index_to_remove,
size_t sizeof_element,
size_t nmemb )
{
char * a = (char*) array;