330
339
const char * tr_sessionGetDownloadDir( const tr_session * session );
342
* @brief Set the per-session incomplete download folder.
344
* When you add a new torrent and the session's incomplete directory is enabled,
345
* the new torrent will start downloading into that directory, and then be moved
346
* to tr_torrent.downloadDir when the torrent is finished downloading.
348
* Torrents are not moved as a result of changing the session's incomplete dir --
349
* it's applied to new torrents, not existing ones.
351
* tr_torrentSetLocation() overrules the incomplete dir: when a user specifies
352
* a new location, that becomes the torrent's new downloadDir and the torrent
353
* is moved there immediately regardless of whether or not it's complete.
355
* @see tr_sessionInit()
356
* @see tr_sessionGetIncompleteDir()
357
* @see tr_sessionSetIncompleteDirEnabled()
358
* @see tr_sessionGetIncompleteDirEnabled()
360
void tr_sessionSetIncompleteDir( tr_session * session, const char * dir );
362
const char* tr_sessionGetIncompleteDir( const tr_session * session );
364
void tr_sessionSetIncompleteDirEnabled( tr_session * session, tr_bool );
366
tr_bool tr_sessionIsIncompleteDirEnabled( const tr_session * session );
370
* @brief When enabled, newly-created files will have ".part" appended
371
* to their filename until the file is fully downloaded
373
* This is not retroactive -- toggling this will not rename existing files.
374
* It only applies to new files created by Transmission after this API call.
376
* @see tr_sessionIsIncompleteFileNamingEnabled()
378
void tr_sessionSetIncompleteFileNamingEnabled( tr_session * session, tr_bool );
380
tr_bool tr_sessionIsIncompleteFileNamingEnabled( const tr_session * session );
333
383
* @brief Set whether or not RPC calls are allowed in this session.
335
385
* @details If true, libtransmission will open a server socket to listen
979
1046
tr_torrent* tr_torrentFindFromId( tr_session * session, int id );
1048
tr_torrent* tr_torrentFindFromHash( tr_session * session, const uint8_t * hash );
1053
* @brief find the location of a torrent's file by looking with and without
1054
* the ".part" suffix, looking in downloadDir and incompleteDir, etc.
1055
* @return a newly-allocated string (that must be tr_freed() by the caller when done)
1056
* that gives the location of this file on disk, or NULL if no file exists yet.
1057
* @param tor the torrent whose file we're looking for
1058
* @param fileNum the fileIndex, in [0...tr_info.fileCount)
1060
char* tr_torrentFindFile( const tr_torrent * tor, tr_file_index_t fileNo );
983
1064
**** Torrent speed limits
1158
1265
void tr_torrentClearCompletenessCallback( tr_torrent * torrent );
1269
typedef void ( tr_torrent_metadata_func )( tr_torrent * torrent,
1272
* Register to be notified whenever a torrent changes from
1273
* having incomplete metadata to having complete metadata.
1274
* This happens when a magnet link finishes downloading
1275
* metadata from its peers.
1277
void tr_torrentSetMetadataCallback (
1279
tr_torrent_metadata_func func,
1162
1283
* Register to be notified whenever a torrent's ratio limit
1163
1284
* has been hit. This will be called when the torrent's
1226
1347
void tr_torrentPeersFree( tr_peer_stat * peerStats,
1227
1348
int peerCount );
1351
**** tr_tracker_stat
1356
/* we won't (announce,scrape) this torrent to this tracker because
1357
* the torrent is stopped, or because of an error, or whatever */
1358
TR_TRACKER_INACTIVE,
1360
/* we will (announce,scrape) this torrent to this tracker, and are
1361
* waiting for enough time to pass to satisfy the tracker's interval */
1364
/* it's time to (announce,scrape) this torrent, and we're waiting on a
1365
* a free slot to open up in the announce manager */
1368
/* we're (announcing,scraping) this torrent right now */
1375
/* how many downloads this tracker knows of (-1 means it does not know) */
1378
/* whether or not we've ever sent this tracker an announcement */
1379
tr_bool hasAnnounced;
1381
/* whether or not we've ever scraped to this tracker */
1384
/* ex: http://www.legaltorrents.com:7070 */
1387
/* the full announce URL */
1388
char announce[1024];
1390
/* Transmission uses one tracker per tier,
1391
* and the others are kept as backups */
1394
/* is the tracker announcing, waiting, queued, etc */
1395
tr_tracker_state announceState;
1397
/* is the tracker scraping, waiting, queued, etc */
1398
tr_tracker_state scrapeState;
1400
/* number of peers the tracker told us about last time.
1401
* if "lastAnnounceSucceeded" is false, this field is undefined */
1402
int lastAnnouncePeerCount;
1404
/* human-readable string with the result of the last announce.
1405
if "hasAnnounced" is false, this field is undefined */
1406
char lastAnnounceResult[128];
1408
/* when the last announce was sent to the tracker.
1409
* if "hasAnnounced" is false, this field is undefined */
1410
time_t lastAnnounceStartTime;
1412
/* whether or not the last announce was a success.
1413
if "hasAnnounced" is false, this field is undefined */
1414
tr_bool lastAnnounceSucceeded;
1416
/* when the last announce was completed.
1417
if "hasAnnounced" is false, this field is undefined */
1418
time_t lastAnnounceTime;
1420
/* human-readable string with the result of the last scrape.
1421
* if "hasScraped" is false, this field is undefined */
1422
char lastScrapeResult[128];
1424
/* when the last scrape was sent to the tracker.
1425
* if "hasScraped" is false, this field is undefined */
1426
time_t lastScrapeStartTime;
1428
/* whether or not the last scrape was a success.
1429
if "hasAnnounced" is false, this field is undefined */
1430
tr_bool lastScrapeSucceeded;
1432
/* when the last scrape was completed.
1433
if "hasScraped" is false, this field is undefined */
1434
time_t lastScrapeTime;
1436
/* number of leechers this tracker knows of (-1 means it does not know) */
1439
/* when the next periodic announce message will be sent out.
1440
if announceState isn't TR_TRACKER_WAITING, this field is undefined */
1441
time_t nextAnnounceTime;
1443
/* when the next periodic scrape message will be sent out.
1444
if scrapeState isn't TR_TRACKER_WAITING, this field is undefined */
1445
time_t nextScrapeTime;
1447
/* number of seeders this tracker knows of (-1 means it does not know) */
1450
/* which tier this tracker is in */
1455
tr_tracker_stat * tr_torrentTrackers( const tr_torrent * torrent,
1456
int * setmeTrackerCount );
1458
void tr_torrentTrackersFree( tr_tracker_stat * trackerStats,
1230
1465
* @brief get the download speeds for each of this torrent's webseed sources.
1361
1604
TR_PEER_FROM_INCOMING = 0, /* connections made to the listening port */
1362
1605
TR_PEER_FROM_TRACKER = 1, /* peers received from a tracker */
1363
1606
TR_PEER_FROM_DHT = 2, /* peers learnt from the DHT */
1364
TR_PEER_FROM_CACHE = 3, /* peers read from the peer cache */
1607
TR_PEER_FROM_RESUME = 3, /* peers read from the .resume file */
1365
1608
TR_PEER_FROM_PEX = 4, /* peers discovered via PEX */
1609
TR_PEER_FROM_LTEP = 5, /* peer address provided in an LTEP handshake */
1366
1610
TR_PEER_FROM__MAX
1615
/* everything's fine */
1371
1616
TR_STAT_OK = 0,
1618
/* when we anounced to the tracker, we got a warning in the response */
1372
1619
TR_STAT_TRACKER_WARNING = 1,
1621
/* when we anounced to the tracker, we got an error in the response */
1373
1622
TR_STAT_TRACKER_ERROR = 2,
1624
/* local trouble, such as disk full or permissions error */
1374
1625
TR_STAT_LOCAL_ERROR = 3
1376
1627
tr_stat_errtype;
1419
1658
Range is [0..1] */
1420
1659
float percentComplete;
1661
/** How much of the metadata the torrent has.
1662
For torrents added from a .torrent this will always be 1.
1663
For magnet links, this number will from from 0 to 1 as the metadata is downloaded.
1665
float metadataPercentComplete;
1422
1667
/** How much has been downloaded of the files the user wants. This differs
1423
1668
from percentComplete if the user wants only some of the torrent's files.
1424
1669
Range is [0..1]
1425
1670
@see tr_stat.leftUntilDone */
1426
1671
float percentDone;
1428
/** The percentage of the actual ratio to the seed ratio. This will be
1429
equal to 1 if the ratio is reached or the torrent is set to seed forever.
1673
/** The percentage of the actual ratio to the seed ratio. This will be
1674
equal to 1 if the ratio is reached or the torrent is set to seed forever.
1433
1678
/** Speed all data being sent for this torrent. (KiB/s)
1434
1679
This includes piece data, protocol messages, and TCP overhead */
1471
1716
/** Number of webseeds that are sending data to us. */
1472
1717
int webseedsSendingToUs;
1474
/** Number of seeders that the tracker says this torrent has */
1477
/** Number of leechers that the tracker says this torrent has */
1480
/** Number of downloaders that the tracker says this torrent has.
1481
This is a new key introduced in BEP 21 and may not be supported by some trackers.
1482
If the tracker doesn't support this key, the value here will be -1. */
1485
/** Number of finished downloads that the tracker says torrent has */
1488
1719
/** Byte count of all the piece data we'll have downloaded when we're done,
1489
1720
whether or not we have it yet. This may be less than tr_info.totalSize
1490
1721
if only some of the torrent's files are wanted.
1521
1752
are moved to `corrupt' or `haveValid'. */
1522
1753
uint64_t haveUnchecked;
1525
* This is a human-readable string with the last scrape's results.
1526
* 1. If an http error occurred, the response code and description is given.
1527
* 2. If the tracker gave an error or warning messae, that is given.
1528
* 3. If everything went fine, "Success" is given.
1530
char scrapeResponse[128];
1532
/** This is a human-readable string with the last announce's results.
1533
Its contents have the same form as scrapeResponse. */
1534
char announceResponse[128];
1536
/** Time the most recent scrape request was sent,
1537
or zero if one hasn't been sent yet. */
1538
time_t lastScrapeTime;
1540
/** Time when the next scrape request will be sent,
1541
or 0 if an error has occured that stops scraping,
1542
or 1 if a scrape is currently in progress s.t.
1543
we haven't set a timer for the next one yet. */
1544
time_t nextScrapeTime;
1546
/** Time the most recent announce request was sent,
1547
or zero if one hasn't been sent yet. */
1548
time_t lastAnnounceTime;
1550
/** Time when the next reannounce request will be sent,
1551
or 0 if the torrent is stopped,
1552
or 1 if an announce is currently in progress s.t.
1553
we haven't set a timer for the next one yet */
1554
time_t nextAnnounceTime;
1556
/** If the torrent is running, this is the time at which
1557
the client can manually ask the torrent's tracker
1559
or 0 if the torrent is stopped or doesn't allow manual,
1560
or 1 if an announce is currently in progress s.t.
1561
we haven't set a timer for the next one yet */
1562
time_t manualAnnounceTime;
1564
/** A very rough estimate in KiB/s of how quickly data is being
1565
passed around between all the peers we're connected to.
1566
Don't put too much weight in this number. */
1755
/** time when one or more of the torrent's trackers will
1756
allow you to manually ask for more peers,
1757
or 0 if you can't */
1758
time_t manualAnnounceTime;
1569
1760
#define TR_RATIO_NA -1
1570
1761
#define TR_RATIO_INF -2