Ignore:
Timestamp:
May 29, 2009, 7:17:12 PM (13 years ago)
Author:
charles
Message:

(trunk libT) re-start work on making libT doxygen friendly. still a long ways to go on this.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/libtransmission/transmission.h

    r8460 r8561  
    2626 * This file defines the public API for the libtransmission library.
    2727 *
    28  * Other headers suitable for public consumption are bencode.h
    29  * and utils.h.  Most of the remaining headers in libtransmission
    30  * should be considered private to libtransmission.
     28 * Other headers with a public API are bencode.h and utils.h.
     29 * Most of the remaining headers in libtransmission are private.
    3130 */
    3231#ifndef TR_TRANSMISSION_H
     
    3736#endif
    3837
     38/***
     39****
     40****  Basic Types
     41****
     42***/
     43
    3944#include <inttypes.h> /* uintN_t */
     45#include <time.h> /* time_t */
     46
    4047#ifndef PRId64
    4148 #define PRId64 "lld"
     
    4754 #define PRIu32 "lu"
    4855#endif
    49 #include <time.h> /* time_t */
    50 
    51 #if defined( WIN32 ) && defined(_MSC_VER)
     56
     57#if defined(WIN32) && defined(_MSC_VER)
    5258 #define TR_INLINE __inline
    5359#else
     
    5763#define SHA_DIGEST_LENGTH 20
    5864#define TR_INET6_ADDRSTRLEN 46
    59 
    60 #define TR_RPC_SESSION_ID_HEADER "X-Transmission-Session-Id"
    6165
    6266typedef uint32_t tr_file_index_t;
     
    6670typedef uint8_t tr_bool;
    6771
    68 enum
    69 {
    70     TR_PRI_LOW    = -1,
    71     TR_PRI_NORMAL =  0, /* since NORMAL is 0, memset initializes nicely */
    72     TR_PRI_HIGH   =  1
    73 };
    74 
    75 typedef int8_t tr_priority_t;
    76 
    77 static TR_INLINE tr_bool tr_isPriority( tr_priority_t p )
    78 {
    79     return ( p == TR_PRI_LOW )
    80         || ( p == TR_PRI_NORMAL )
    81         || ( p == TR_PRI_HIGH );
    82 }
    83 
    84 /**
    85  * @brief returns Transmission's default configuration file directory.
    86  *
    87  * The default configuration directory is determined this way:
    88  * 1. If the TRANSMISSION_HOME environmental variable is set, its value is used.
    89  * 2. On Darwin, "${HOME}/Library/Application Support/${appname}" is used.
    90  * 3. On Windows, "${CSIDL_APPDATA}/${appname}" is used.
    91  * 4. If XDG_CONFIG_HOME is set, "${XDG_CONFIG_HOME}/${appname}" is used.
    92  * 5. ${HOME}/.config/${appname}" is used as a last resort.
    93  */
    94 const char* tr_getDefaultConfigDir( const char * appname );
    95 
    96 /**
    97  * @brief returns Transmisson's default download directory.
    98  *
    99  * The default download directory is determined this way:
    100  * 1. If the HOME environmental variable is set, "${HOME}/Downloads" is used.
    101  * 2. On Windows, "${CSIDL_MYDOCUMENTS}/Downloads" is used.
    102  * 3. Otherwise, getpwuid(getuid())->pw_dir + "/Downloads" is used.
    103  */
    104 const char* tr_getDefaultDownloadDir( void );
    105 
    10672typedef struct tr_ctor tr_ctor;
    10773typedef struct tr_info tr_info;
     
    10975typedef struct tr_session tr_session;
    11076
     77struct tr_benc;
     78
     79typedef int8_t tr_priority_t;
     80
     81#define TR_RPC_SESSION_ID_HEADER "X-Transmission-Session-Id"
     82
     83typedef enum
     84{
     85    TR_PREALLOCATE_NONE   = 0,
     86    TR_PREALLOCATE_SPARSE = 1,
     87    TR_PREALLOCATE_FULL   = 2
     88}
     89tr_preallocation_mode;
     90
     91typedef enum
     92{
     93    TR_PROXY_HTTP,
     94    TR_PROXY_SOCKS4,
     95    TR_PROXY_SOCKS5
     96}
     97tr_proxy_type;
     98
     99typedef enum
     100{
     101    TR_CLEAR_PREFERRED,
     102    TR_ENCRYPTION_PREFERRED,
     103    TR_ENCRYPTION_REQUIRED
     104}
     105tr_encryption_mode;
     106
     107
     108/***
     109****
     110****  Startup & Shutdown
     111****
     112***/
    111113
    112114/**
     
    121123 */
    122124
    123 typedef enum
    124 {
    125     TR_PREALLOCATE_NONE   = 0,
    126     TR_PREALLOCATE_SPARSE = 1,
    127     TR_PREALLOCATE_FULL   = 2
    128 }
    129 tr_preallocation_mode;
    130 
    131 static TR_INLINE tr_bool tr_isPreallocationMode( tr_preallocation_mode m  )
    132 {
    133     return ( m == TR_PREALLOCATE_NONE )
    134         || ( m == TR_PREALLOCATE_SPARSE )
    135         || ( m == TR_PREALLOCATE_FULL );
    136 }
    137 
    138 typedef enum
    139 {
    140     TR_PROXY_HTTP,
    141     TR_PROXY_SOCKS4,
    142     TR_PROXY_SOCKS5
    143 }
    144 tr_proxy_type;
    145 
    146 typedef enum
    147 {
    148     TR_CLEAR_PREFERRED,
    149     TR_ENCRYPTION_PREFERRED,
    150     TR_ENCRYPTION_REQUIRED
    151 }
    152 tr_encryption_mode;
    153 
    154 static TR_INLINE tr_bool tr_isEncryptionMode( tr_encryption_mode m )
    155 {
    156     return ( m == TR_CLEAR_PREFERRED )
    157         || ( m == TR_ENCRYPTION_PREFERRED )
    158         || ( m == TR_ENCRYPTION_REQUIRED );
    159 }
    160 
    161 
    162 #define TR_DEFAULT_BIND_ADDRESS_IPV4 "0.0.0.0"
    163 #define TR_DEFAULT_BIND_ADDRESS_IPV6 "::"
    164 #define TR_DEFAULT_OPEN_FILE_LIMIT_STR "32"
    165 #define TR_DEFAULT_RPC_WHITELIST "127.0.0.1"
    166 #define TR_DEFAULT_RPC_PORT_STR "9091"
    167 #define TR_DEFAULT_PEER_PORT_STR "51413"
    168 #define TR_DEFAULT_PEER_SOCKET_TOS_STR "0"
    169 #define TR_DEFAULT_PEER_LIMIT_GLOBAL_STR "240"
    170 #define TR_DEFAULT_PEER_LIMIT_TORRENT_STR "60"
     125/**
     126 * @brief returns Transmission's default configuration file directory.
     127 *
     128 * The default configuration directory is determined this way:
     129 * -# If the TRANSMISSION_HOME environment variable is set, its value is used.
     130 * -# On Darwin, "${HOME}/Library/Application Support/${appname}" is used.
     131 * -# On Windows, "${CSIDL_APPDATA}/${appname}" is used.
     132 * -# If XDG_CONFIG_HOME is set, "${XDG_CONFIG_HOME}/${appname}" is used.
     133 * -# ${HOME}/.config/${appname}" is used as a last resort.
     134 */
     135const char* tr_getDefaultConfigDir( const char * appname );
     136
     137/**
     138 * @brief returns Transmisson's default download directory.
     139 *
     140 * The default download directory is determined this way:
     141 * -# If the HOME environment variable is set, "${HOME}/Downloads" is used.
     142 * -# On Windows, "${CSIDL_MYDOCUMENTS}/Downloads" is used.
     143 * -# Otherwise, getpwuid(getuid())->pw_dir + "/Downloads" is used.
     144 */
     145const char* tr_getDefaultDownloadDir( void );
     146
     147
     148#define TR_DEFAULT_BIND_ADDRESS_IPV4       "0.0.0.0"
     149#define TR_DEFAULT_BIND_ADDRESS_IPV6            "::"
     150#define TR_DEFAULT_OPEN_FILE_LIMIT_STR          "32"
     151#define TR_DEFAULT_RPC_WHITELIST         "127.0.0.1"
     152#define TR_DEFAULT_RPC_PORT_STR               "9091"
     153#define TR_DEFAULT_PEER_PORT_STR             "51413"
     154#define TR_DEFAULT_PEER_SOCKET_TOS_STR           "0"
     155#define TR_DEFAULT_PEER_LIMIT_GLOBAL_STR       "240"
     156#define TR_DEFAULT_PEER_LIMIT_TORRENT_STR       "60"
    171157
    172158#define TR_PREFS_KEY_ALT_SPEED_ENABLED          "alt-speed-enabled"
     
    219205#define TR_PREFS_KEY_UPLOAD_SLOTS_PER_TORRENT   "upload-slots-per-torrent"
    220206
    221 struct tr_benc;
    222207
    223208/**
     
    244229
    245230/**
    246  * Add the session's configuration settings to the benc dictionary.
     231 * Add the session's current configuration settings to the benc dictionary.
    247232 *
    248233 * FIXME: this probably belongs in libtransmissionapp
     
    262247 * @param dictionary pointer to an uninitialized tr_benc
    263248 * @param configDir the configuration directory to find settings.json
    264  * @param appName if configDir is empty, appName is used to get the default config dir.
     249 * @param appName if configDir is empty, appName is used to find the default dir.
    265250 * @see tr_sessionGetDefaultSettings()
    266251 * @see tr_sessionInit()
     
    286271
    287272/**
    288  * Initialize a libtransmission session.
     273 * @brief Initialize a libtransmission session.
    289274 *
    290275 * For example, this will instantiate a session with all the default values:
     
    300285 *
    301286 *     tr_bencFree( &settings );
    302  * @encode
     287 * @endcode
    303288 *
    304289 * @param tag "gtk", "macosx", "daemon", etc... this is only for pre-1.30 resume files
     
    320305
    321306/**
    322  * @brief Return the session's configuration directory
     307 * @brief Return the session's configuration directory.
    323308 *
    324309 * This is where transmission stores its .torrent files, .resume files,
    325  * blocklists, etc.
     310 * blocklists, etc.  It's set in tr_transmissionInit() and is immutable
     311 * during the session.
    326312 */
    327313const char * tr_sessionGetConfigDir( const tr_session * );
     
    333319 * @see tr_ctorSetDownloadDir()
    334320 */
    335 void tr_sessionSetDownloadDir( tr_session  * session,
    336                                const char  * downloadDir );
     321void tr_sessionSetDownloadDir( tr_session * session, const char * downloadDir );
    337322
    338323/**
     
    772757
    773758
    774 /** @addtogroup tr_ctor Torrent Instantiation
     759/** @addtogroup tr_ctor Torrent Constructors
    775760    @{
    776761
     
    10311016****/
    10321017
     1018enum
     1019{
     1020    TR_PRI_LOW    = -1,
     1021    TR_PRI_NORMAL =  0, /* since NORMAL is 0, memset initializes nicely */
     1022    TR_PRI_HIGH   =  1
     1023};
    10331024
    10341025/**
     
    10851076**/
    10861077
     1078/** @brief a part of tr_info that represents a single tracker */
    10871079typedef struct tr_tracker_info
    10881080{
     
    12661258 **********************************************************************/
    12671259
     1260/** @brief a part of tr_info that represents a single file of the torrent's content */
    12681261typedef struct tr_file
    12691262{
     
    12791272tr_file;
    12801273
     1274/** @brief a part of tr_info that represents a single piece of the torrent's content */
    12811275typedef struct tr_piece
    12821276{
     
    12881282tr_piece;
    12891283
     1284/** @brief information about a torrent that comes from its metainfo file */
    12901285struct tr_info
    12911286{
     
    15821577const tr_stat * tr_torrentStatCached( tr_torrent * torrent );
    15831578
    1584 /** @deprecated this method will be removed in 1.40 */
     1579/** @deprecated */
    15851580void tr_torrentSetAddedDate( tr_torrent * torrent,
    15861581                             time_t       addedDate );
    15871582
    1588 /** @deprecated this method will be removed in 1.40 */
     1583/** @deprecated */
    15891584void tr_torrentSetActivityDate( tr_torrent * torrent,
    15901585                                time_t       activityDate );
    15911586
    1592 /** @deprecated this method will be removed in 1.40 */
    1593 void tr_torrentSetDoneDate( tr_torrent  * torrent,
    1594                             time_t        doneDate );
     1587/** @deprecated */
     1588void tr_torrentSetDoneDate( tr_torrent * torrent, time_t doneDate );
     1589
     1590/** @} */
    15951591
    15961592/** @brief Sanity checker to test that the direction is TR_UP or TR_DOWN */
     
    16001596static TR_INLINE tr_bool tr_isBool( tr_bool b ) { return b==1 || b==0; }
    16011597
    1602 /** @} */
    1603 
    16041598#ifdef __cplusplus
    16051599}
Note: See TracChangeset for help on using the changeset viewer.