/* * xvITorrent.idl * * Copyright (c) 2005, 2006 by Daniel Potter. All rights reserved. * * This file is part of FireTorrent. * * FireTorrent is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 as published * by the Free Software Foundation. * * FireTorrent is distributed in the hope that it will be useful, but * WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * General Public License for more details. * * You should have received a copy of the GNU General Public License * along with FireTorrent; if not, write to the Free Software Foundation, * Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA * * Interface definition for the various torrent components. */ #include "nsISupports.idl" #include "nsILocalFile.idl" /** * An individual piece within a torrent. Note that pieces can span files - so * an individual piece can represent any number of files. A piece is further * divided into blocks of 1.4k each. This individual blocks are what is * actually traded on the network. * @status FLUID */ [scriptable, uuid(26966edc-ce1a-4776-9041-7861fccc3c6b)] interface xvITorrentPiece : nsISupports { /** * The numeric index of this block within the torrent. */ readonly attribute PRUint32 blockNumber; }; /** * A file located within a torrent. * @status FLUID */ [scriptable, uuid(9e7ffef9-1e0e-4a03-a004-634eeba2d565)] interface xvITorrentFile : nsISupports { /** * The path of this file. This path is delimited with "/" regardless * of platform, and is NOT used to construct the directory structure * while the torrent downloads. */ readonly attribute ACString name; /** * The total size of this file. */ readonly attribute PRUint64 length; /** * The number of pieces within this file. */ readonly attribute PRUint32 pieceCount; /** * The number of completed pieces within this file. */ readonly attribute PRUint32 completedPieceCount; /** * Allocate space for this file on the local file system. * If given a regular file (or a non-existant file), then * the file is created and used. THIS WILL OVERWRITE THE * FILE! * * If given a directory, then the path specified within this * torrent will be created if it does not exist. If a file * already exists at this location, it will be overwritten. */ void allocate(in nsILocalFile file); /** * Launches the file ASSUMING WE THINK IT'S DONE, via * nsILocalFile.launch(). If the file is marked incomplete for any * reason (essentially, we still have an output stream open to it), * then this call will do nothing. * * @return true if we attempted to launch the file, false if the * file is still considered closed and the call was ignored */ boolean launch(); /** * Reveals the file via nsILocalFile.reveal(). */ void reveal(); }; /** * A peer in a torrent. * @status FLUID */ [scriptable, uuid(87144ef5-30cc-4cf9-bfeb-bd42864a15f0)] interface xvITorrentPeer : nsISupports { readonly attribute string peerId; }; /** * An instance of a torrent. * @status FLUID */ [scriptable, uuid(95750ffd-61e2-4d61-8f8b-19c0a2b84329)] interface xvITorrent : nsISupports { /** * Currently uploading. */ const PRUint32 STATUS_UPLOADING = (1<<0); /** * Currently downloading the file. */ const PRUint32 STATUS_DOWNLOADING = (1<<1); /** * Currently checking the SHA1 hashes of the file pieces to ensure * that the file is valid. */ const PRUint32 STATUS_CHECKING = (1<<2); /** * Indicates that the last request to the tracker succeeded. */ const PRUint32 STATUS_TRACKER_ALIVE = (1<<3); /** * Currently downloading the torrent file */ const PRUint32 STATUS_DOWNLOADING_TORRENT = (1<<4); /** * An ORed bitfield of the state constants indicating what the torrent * is currently doing. */ readonly attribute PRUint32 status; /** * The name of the tracker file as defined in the torrent. */ readonly attribute AString name; /** * The comment of the tracker file as defined in the torrent. */ readonly attribute AString comment; /** * The URL of the tracker as defined in the torrent. */ readonly attribute ACString tracker; /** * The current infoHash of this torrent. */ readonly attribute string infoHash; /** * Total bytes required to download. */ readonly attribute PRUint64 total; /** * Number of bytes currently available. */ readonly attribute PRUint64 completedTotal; /** * Number of bytes downloaded *through FireTorrent* and not out of the * total. download / total does NOT give a complete percentage. Use * completedTotal / total for that. */ readonly attribute PRUint64 downloaded; /** * Number of bytes uploaded *this session* and not cross total. */ readonly attribute PRUint64 uploaded; /** * Total number of pieces in this torrent. */ readonly attribute PRUint64 pieceCount; /** * Size of a piece (in bytes). */ readonly attribute PRUint32 pieceSize; /** * The number of complete peers (seeds) available. */ readonly attribute PRUint32 completePeers; /** * The number of incomplete peers (leechers) available. */ readonly attribute PRUint32 incompletePeers; /** * The number of files in this torrent. Single file downloads are * (not surprisingly) 1, multi are 1+. */ readonly attribute PRUint32 numberFiles; /** * The last time the tracker was contacted in milliseconds, or negative * for "never". */ readonly attribute PRInt32 lastTrackerHit; /** * The next time the tracker will be contacted, in milliseconds. */ readonly attribute PRInt32 nextTrackerHit; /** * Gets information about a file within the torrent. */ xvITorrentFile getFileInfo(in PRUint32 index); /** * Gets information about a piece within the torrent. */ xvITorrentPiece getPiece(in PRUint32 index); /** * Determines if this client has the given piece. */ boolean hasPiece(in PRUint32 index); /** * Determines the number of other clients that have the given piece. * This is only updated occasionally. */ PRUint16 pieceAvailability(in PRUint32 index); /** * Indicates the directory/file where the torrent should be saved to. * If the torrent is a single-file download and the location is a * directory, then the name attribute will be used as the file name. * If the torrent is a multi-file download and the location is a file, * then the directory where that file is located at will be used. * In the case of a multi-file download, the directory is checked to see * if it contains the requested files. If it does, that directory is * used directly. If it does not, then the directory name as specified * within the torrent is used instead. * * In any case, following a call to this method, all required files * and directories will be created and allocated in order to allow the * download to proceed. */ void setDownloadLocation(in nsILocalFile file); /** * Starts the torrent. */ void start( ); /** * Stops the torrent (even if it's incomplete). */ void stop( ); };