/* ***** BEGIN LICENSE BLOCK *****
 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
 * 
 * The contents of this file are subject to the Mozilla Public License
 * Version 1.1 (the "License"); you may not use this file except in
 * compliance with the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 * 
 * Software distributed under the License is distributed on an "AS IS"
 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the
 * License for the specific language governing rights and limitations
 * under the License.
 * 
 * The Original Code is Komodo code.
 * 
 * The Initial Developer of the Original Code is ActiveState Software Inc.
 * Portions created by ActiveState Software Inc are Copyright (C) 2000-2007
 * ActiveState Software Inc. All Rights Reserved.
 * 
 * Contributor(s):
 *   ActiveState Software Inc
 * 
 * Alternatively, the contents of this file may be used under the terms of
 * either the GNU General Public License Version 2 or later (the "GPL"), or
 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 * in which case the provisions of the GPL or the LGPL are applicable instead
 * of those above. If you wish to allow use of your version of this file only
 * under the terms of either the GPL or the LGPL, and not to allow others to
 * use your version of this file under the terms of the MPL, indicate your
 * decision by deleting the provisions above and replace them with the notice
 * and other provisions required by the GPL or the LGPL. If you do not delete
 * the provisions above, a recipient may use your version of this file under
 * the terms of any one of the MPL, the GPL or the LGPL.
 * 
 * ***** END LICENSE BLOCK ***** */

#include "nsISupports.idl"
#include "nsIFile.idl"
#include "koIRemoteFileInfo.idl"
interface koIAsyncCallback;

// A remote connection instance.
[scriptable, uuid(e953df1c-979b-48ed-b48d-0c90255564bd)]
interface koIRemoteConnection : nsISupports {
    void promptForUsernameAndPassword(in wstring path);
    boolean open(in wstring server, in long port, in wstring username,
                 in wstring password, in wstring path, in boolean passive,
                 [optional] in wstring privatekey);
    
    // list caches results.  set refresh to true to force a refresh from the server
    // A better name for this method would be 'stat', as it's a remote
    // analog to the stat method, returning a koIRFI object.
    void list(in wstring path, in boolean refresh, [retval] out koIRemoteFileInfo pathinfo);
    void close();
    // refresh removes any cached information for this path and subsequent child paths
    // and then does a list for this path with refresh set to true.
    //void refresh(in wstring path);
    void rename(in wstring oldName, in wstring newName);
    void removeFile(in wstring name);
    void removeDirectory(in wstring name);
    void removeDirectoryRecursively(in wstring path);
    void changeDirectory(in wstring path);
    void currentDirectory();
    void createFile(in wstring name, in long permissions);
    void createDirectory(in wstring name, in long permissions);
    // Recursively create all missing directories in the given path.
    void createDirectories(in wstring path, in long permissions);
    void getHomeDirectory([retval] out wstring path);
    void getParentPath(in wstring path, [retval] out wstring parentPath);
    void chmod(in wstring path, in long permissions);

    void readFile(in wstring name, out unsigned long count, [array, size_is(count), retval] out octet text);
    void writeFile(in wstring name, [array, size_is(count)] in octet text, in unsigned long count);

    // Remove any cached information held for this path.
    void invalidatePath(in wstring path, in boolean invalidateChildren);

    attribute wstring alias;   // Server pref alias for connection
    readonly attribute wstring protocol;
    readonly attribute wstring server;
    readonly attribute long port;
    readonly attribute wstring username;
    readonly attribute wstring password;
    readonly attribute wstring privatekey;
    readonly attribute wstring lastError;
};

[scriptable, uuid(eebc454e-7700-4406-9da1-66b711c5f3ae)]
interface koISSHConnection : koIRemoteConnection {
    // Run the specified command remotely and return the process retval.
    //   command - command string to be run
    //   combineStdoutAndStderr - whether the stderr is combined with stdout,
    //                            when true, the stdout result contains both
    //                            the outputs from stdout and stderr.
    //   stdout - normal output from the command
    //   stderr - error output from the command
    //            XXX - currently stderr will always be an empty string
    //                  due to it being unsupported by paramiko.
    long runCommand(in wstring command, in boolean combineStdoutAndStderr,
                    // The stdout and stderr should be an AString (in order to
                    // support null bytes), but multiple AString out values
                    // cause problems for Python XPCOM components: bug 84054.
                    out wstring stdout, out wstring stderr);
    
    void runCommandAsync(in wstring command, in koIAsyncCallback callbackStdout, in koIAsyncCallback callbackStderr);
};
