/*
 * File    : DownloadStats.java
 * Created : 08-Jan-2004
 * By      : parg
 * 
 * Azureus - a Java Bittorrent client
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program 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 ( see the LICENSE file ).
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 */

package org.gudy.azureus2.plugins.download;

/**
 * @author parg
 * This class gives access to various stats associated with the download
 */

public interface 
DownloadStats 
{
	public static final int HEALTH_STOPPED    		= 1;
	public static final int HEALTH_NO_TRACKER 		= 2;
	public static final int HEALTH_NO_REMOTE  		= 3;
	public static final int HEALTH_OK  				= 4;
	/** not connected to any peer and downloading */
	public static final int HEALTH_KO 				= 5;
	/** download in STATE_ERROR, see {@link #getStatus()} for error */
	public static final int HEALTH_ERROR 				= 6;
	
	/**
	 * Returns an overall string representing the state of the download
	 * @return
   *
   * @since 2.0.7.0
	 */
	public String
	getStatus();
	
	/**
	 * Returns an overall string representing the state of the download
	 * *localised*
	 * @return
   *
   * @since 2.3.0.7
	 */
	public String
	getStatus( boolean localised);
	
	/**
	 * Gives access to the directory into which the download is being saved
	 * @return
   *
   * @since 2.0.7.0
	 */
	public String
	getDownloadDirectory();
	
	/**
	 * Gives access to the target file or directory that the download is being saved to
	 * @return
   *
   * @since 2.0.7.0
	 */
	public String
	getTargetFileOrDir();
	
	/**
	 * returns an general status string for the tracker
	 * @return
   *
   * @since 2.0.7.0
	 */
	public String
	getTrackerStatus();
	
	/**
	 * returns a value between 0 and 1000 giving the completion status of the current download
	 * task (e.g. checking, downloading)
	 * @return
   *
   * @since 2.0.7.0
	 */
	public int
	getCompleted();
	
  /** Retrieve the level of download completion.
   * 
   * To understand the bLive parameter, you must know a bit about the
   * Torrent activation process:
   * 1) Torrent goes into ST_WAITING
   * 2) Torrent moves to ST_PREPARING
   * 3) Torrent moves to ST_DOWNLOADING or ST_SEEDING
   *
   * While in ST_PREPARING, Completion Level is rebuilt (either via Fast Resume
   * or via piece checking). Quite often, the download completion level before
   * ST_PREPARING and after ST_PREPARING are identical.
   *
   * Before going into ST_PREPARING, we store the download completion level.
   * If you wish to retrieve this value instead of the live "building" one,
   * pass false for the parameter.
   *
   * @param bLive true - Always returns the known completion level of the torrent
   *               false - In the case of ST_PREPARING, return completion level 
   *                       before of the torrent ST_PREPARING started.  
   *                       Otherwise, same as true.
   * @return 0 - 1000
   *
   * @since 2.0.8.0
	 */
	public int
	getDownloadCompleted(boolean bLive);

	/**
	 * if isChecking then returns completeness, 1000 -> 100%
	 * @return
	 */

	public int
	getCheckingDoneInThousandNotation();

	/**
	 * resets totals. stops and restarts torrent if running to do so
	 * @since 4511. Supply -1 to leave a value unchanged
	 */

	public void
	resetUploadedDownloaded(
		long		new_up,
		long		new_down );
	
	/**
	 * Gives the number of bytes downloaded
	 * @return
   *
   * @since 2.0.7.0
	 */
	public long
	getDownloaded();
	
	/**
	 * @since 5.1.0.1
	 * @param include_protocol
	 * @return
	 */
	
	public long
	getDownloaded(
		boolean	include_protocol );
	
	/**
	 * Gives number of bytes remaining.  Excludes DND files only if disk manager exists
	 * 
	 * @since 2.5.0.2
	 */
	
	public long
	getRemaining();
	
	/**
	 * Gives the number of bytes uploaded
	 * @return
   *
   * @since 2.0.7.0
	 */
	public long
	getUploaded();

	/**
	 * @since 5.1.0.1
	 * @param include_protocol
	 * @return
	 */
	
	public long
	getUploaded(
		boolean	include_protocol );
	
	/**
	 * Gives the number of bytes discarded.
	 * Does not include {@link #getHashFails()}
	 * (ex. end game mode where multiple peers send same block, et)
	 * @return
   *
   * @since 2.0.7.0
	 */
	public long
	getDiscarded();
	
	/**
	 * Gives average number of bytes downloaded in last second 
	 * @return
   *
   * @since 2.0.7.0
	 */
	public long
	getDownloadAverage();
	
	/**
	 * @since 5.1.0.1
	 * @param include_protocol
	 * @return
	 */
	public long
	getDownloadAverage(
		boolean	include_protocol );

	/**
	 * Gives average number of bytes uploaded in last second 
	 * @return
   *
   * @since 2.0.7.0
	 */
	public long
	getUploadAverage();
	
	/**
	 * @since 5.1.0.1
	 * @param include_protocol
	 * @return
	 */
	
	public long
	getUploadAverage(
		boolean	include_protocol );
	
	/**
	 * Gives average number of bytes computed for torrent in last second 
	 * @return
   *
   * @since 2.0.7.0
	 */
	public long
	getTotalAverage();
	
	/**
	 * Gives the elapsed download time as a string
	 * @return
   *
   * @since 2.0.7.0
	 */
	public String
	getElapsedTime();
	
	/**
	 * Gives the estimated time to completion as a string
	 * @return
   *
   * @since 2.0.7.0
	 */
	public String
	getETA();

	/**
	 * ETA time in seconds.
	 * 
	 * @return
	 *   0 = download is complete.<BR>
	 * < 0 = download is complete and it took -xxx time to complete.<BR>
	 * 	-1 = unknown eta (no peer manager) or download completed 1s ago<BR>
	 * 315360000000L = incomplete and 0 average speed<BR> 
	 * 
	 * @since 4.2.0.3
	 */
	
	public long
	getETASecs();
	
	/**
	 * Gives the number of bytes thrown away due to piece hash check fails
	 * @return
   *
   * @since 2.0.7.0
	 */
	public long
	getHashFails();
	
	/**
	 * Gives the share ratio of the torrent in 1000ths (i.e. 1000 = share ratio of 1)
	 * @return
   *
   * @since 2.0.7.0
	 */
	public int
	getShareRatio();

  /** in ms since epoch
   *
   * @since 2.0.8.0
	 */
	public long
	getTimeStarted();
	
  /**
   * Time that the torrent started seeding.
   * @return the difference, measured in milliseconds, between the torrent 
   *         started seeding and midnight, January 1, 1970 UTC.  see
   *         SystemTime.getCurrentTime().
   *         -1 is not seeding
   *
   * @since 2.1.0.0
	 */
	public long
	getTimeStartedSeeding();

	/**
	 * Gives the currently seen availability of the torrent
	 * @return
   *
   * @since 2.0.8.2
	 */
	public float
	getAvailability();


  /**
   * Return the # of seconds that the torrent has been downloading.  This 
   * number is totalled across sessions.
   *
   * @return -1 if it has never downloaded
   *
   * @since 2.1.0.0
	 */
	public long 
	getSecondsDownloading();

  /**
   * Return the # of seconds that the torrent has been only seeding.  This 
   * number is totalled across sessions, and does not include the time
   * seeding during the download phase.
   *
   * @return -1 if it has never seeded
   *
   * @since 2.1.0.0
	 */
	public long 
	getSecondsOnlySeeding();
	
	/**
	 * Returns the number of seconds running time since data was downloaded, -1 if never 
	 * @since 2501
	 * @return
	 */
	
	public long
	getSecondsSinceLastDownload();
	
	/**
	 * Returns the number of seconds running time since data was uploaded, -1 if never 
	 * @since 2501
	 * @return
	 */
	
	public long
	getSecondsSinceLastUpload();
	
	/**
	 * returns an indication of the health of the torrent 
	 * @return	see above HEALTH constants
	 */
	
	public int
	getHealth();

	/**
	 * Return the number of bytes of data fromt he torrent that is unavailable
	 * given the current sources (peers).
	 *
	 * Does not exclude DND files
	 * 
	 * @return -1 if could not be determined
	 * 
	 * @since 4.8.0.1
	 */
	public long
	getBytesUnavailable();
}
