//==============================================================================
// FTPClientI.java
//==============================================================================

package tribble.net.ftp;

import java.io.File;
import java.io.InputStream;
import java.io.IOException;
import java.io.OutputStream;

import java.lang.Exception;
import java.lang.String;


/*******************************************************************************
* Basic FTP client interface.
* Allows clients to establish FTP connections, send and receive files, get
* remote directory listings, etc.
*
* <!--~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~-->
* @version	API 2.0 $Revision: 1.14 $ $Date: 2010/07/12 21:26:49 $
* @since	API 1.0, 2001-04-14
* @author	David R. Tribble (david&#64;tribble.com).
*	<p>
*	Copyright ©2001-2010 by David R. Tribble, all rights reserved.<br/>
*	Permission is granted to any person or entity except those designated
*	by the United States Department of State as a terrorist, or terrorist
*	government or agency, to use and distribute this source code provided
*	that the original copyright notice remains present and unaltered.
*/

public interface FTPClientI
    extends FTPSimpleClientI
{
    /** Revision information. */
    static final String		REV =
        "@(#)tribble/net/ftp/FTPClientI.java API 2.0 $Revision: 1.14 $ $Date: 2010/07/12 21:26:49 $\n";


// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Methods

    /***************************************************************************
    * Log in to the remote FTP system.
    *
    * @param	user
    * FTP user-ID for the remote system.
    *
    * @param	pwd
    * User password.  This can be empty (<tt>""</tt>).
    *
    * @throws	IOException
    * Thrown if an error occurs.
    *
    * @see	#login() login()
    * @see	#connect connect()
    *
    * @since	1.2, 2006-03-15
    */
    public abstract void login(String user, String pwd)
        throws IOException;


    /***************************************************************************
    * Ping the remote FTP system.
    * This sends a "NOOP" FTP command to the remote system and receives its
    * reply.
    *
    * @throws	IOException
    * Thrown if an error occurs, e.g., the FTP connection is broken.
    *
    * @since	1.3, 2006-03-16
    */
    public abstract void ping()
        throws IOException;


    /***************************************************************************
    * Retrieve the identity information of the remote FTP system.
    *
    * @param	out
    * Output stream to which the identification information is to be written.
    *
    * @throws	IOException
    * Thrown if an I/O error occurs.
    *
    * @since	API 2.0, 1.14, 2010-07-12
    */
    public abstract void getSystemInfo(OutputStream out)
        throws IOException;


    /***************************************************************************
    * Retrieve the current status of the remote FTP system.
    *
    * @param	out
    * Output stream to which the status is to be written.
    *
    * @throws	IOException
    * Thrown if an I/O error occurs.
    *
    * @since	API 2.0, 1.14, 2010-07-12
    */
    public abstract void getStatus(OutputStream out)
        throws IOException;


    /***************************************************************************
    * Get (receive) a help listing of supported FTP commands from the remote FTP
    * system.
    *
    * @param	out
    * Output stream to which the help listing is to be written.
    *
    * @throws	IOException
    * Thrown if an error occurs.
    *
    * @since	API 2.0, 1.14, 2010-07-12
    */
    public abstract void getHelp(OutputStream out)
        throws IOException;


    /***************************************************************************
    * Get (receive) a file from the remote FTP system to the local system.
    *
    * @param	src
    * Remote source filename.  If this does not contain a directory prefix, the
    * current remote working directory is assumed.
    *
    * @param	dst
    * Local source filename.  If this does not contain a directory prefix, the
    * current local working directory is assumed.  This may be null, in which
    * case the base filename of <tt>src</tt> (without the directory prefix) is
    * used.
    *
    * @throws	IOException
    * Thrown if the file could not be transmitted or if any other error occurs.
    *
    * @see	#getFile(String, File) getFile()
    * @see	#getFile(String, OutputStream) getFile()
    * @see	#putFile(String, String) putFile()
    * @see	#appendFile(String, String) appendFile()
    *
    * @since	1.1, 2001-04-14
    */
    public abstract void getFile(String src, String dst)
        throws IOException;


    /***************************************************************************
    * Put (send) a file from the local system to the remote FTP system.
    *
    * @param	src
    * Local source filename.  If this does not contain a directory prefix, the
    * current local working directory is assumed.
    *
    * @param	dst
    * Remote target filename.  If this does not contain a directory prefix, the
    * current remote working directory is assumed.  This may be null, in which
    * case the base filename of <tt>src</tt> (without the directory prefix) is
    * used.
    *
    * @throws	IOException
    * Thrown if the file could not be transmitted or if any other error occurs.
    *
    * @see	#putFile(File, String) putFile()
    * @see	#putFile(InputStream, String) putFile()
    * @see	#appendFile(String, String) appendFile()
    * @see	#getFile(String, String) getFile()
    *
    * @since	1.1, 2001-04-14
    */
    public abstract void putFile(String src, String dst)
        throws IOException;


    /***************************************************************************
    * Append (send) a file from the local system to a file on the remote FTP
    * system.
    *
    * @param	src
    * Local source filename.  If this does not contain a directory prefix, the
    * current local working directory is assumed.
    *
    * @param	dst
    * Remote target filename.  If this does not contain a directory prefix, the
    * current remote working directory is assumed.  This may be null, in which
    * case the base filename of <tt>src</tt> (without the directory prefix) is
    * used.
    *
    * @throws	IOException
    * Thrown if the file could not be transmitted or if any other error occurs.
    *
    * @see	#appendFile(File, String) appendFile()
    * @see	#appendFile(InputStream, String) appendFile()
    * @see	#putFile(String, String) putFile()
    * @see	#getFile(String, String) getFile()
    *
    * @since	1.12, 2007-07-21
    */
    public abstract void appendFile(String src, String dst)
        throws IOException;


    /***************************************************************************
    * Get (receive) a directory listing from the remote FTP system.
    *
    * @param	path
    * The remote directory or filename to list.  If this is empty
    * (<tt>""</tt>), the current remote working directory is assumed.
    *
    * @param	out
    * Output stream to which the directory listing is to be written.
    *
    * @throws	IOException
    * Thrown if an error occurs.
    *
    * @since	API 2.0, 1.14, 2010-07-12
    */
    public abstract void getDirectoryList(String path, OutputStream out)
        throws IOException;


    /***************************************************************************
    * Get (receive) a directory listing from the remote FTP system.
    *
    * @param	path
    * The remote directory or filename to list.  If this is empty
    * (<tt>""</tt>), the current remote working directory is assumed.
    *
    * @param	max
    * Maximum number of filenames (output lines) to list.  A value of zero (0)
    * specifies that there is no maximum.
    *
    * @param	out
    * Output stream to which the directory listing is to be written.
    *
    * @throws	IOException
    * Thrown if an error occurs.
    *
    * @since	API 2.0, 1.14, 2010-07-12
    */
    public abstract void getDirectoryList(String path, int max, OutputStream out)
        throws IOException;


    /***************************************************************************
    * Get (receive) a list of filenames in a directory on the remote FTP system.
    *
    * @param	path
    * The remote directory or filename to list.  If this is empty
    * (<tt>""</tt>), the current remote working directory is assumed.
    *
    * @param	out
    * Output stream to which the directory listing is to be written.
    *
    * @throws	IOException
    * Thrown if an error occurs.
    *
    * @since	API 2.0, 1.14, 2010-07-12
    */
    public abstract void getDirectoryNames(String path, OutputStream out)
        throws IOException;


    /***************************************************************************
    * Get (receive) a list of filenames in a directory on the remote FTP system.
    *
    * @param	path
    * The remote directory or filename to list.  If this is empty
    * (<tt>""</tt>), the current remote working directory is assumed.
    *
    * @param	max
    * Maximum number of filenames to get.  A value of zero (0) specifies that
    * there is no maximum.
    *
    * @param	out
    * Output stream to which the directory listing is to be written.
    *
    * @throws	IOException
    * Thrown if an error occurs.
    *
    * @since	API 2.0, 1.14, 2010-07-12
    */
    public abstract void getDirectoryNames(String path, int max, OutputStream out)
        throws IOException;
}

// End FTPClientI.java