/* ***** 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 ***** */

// A service to maintain a cache of remote connections and connection information.
//
// Usage:
//  - XPCOM methods should use getConnection() to make a remote connection.
//          - This may be an already opened (cached) connection object
//  - User code can use saveSessionInfo() to cached a connection username/password
//  - User code can query getSessionInfo() to find a cached username/password
//

#include "nsISupports.idl"
#include "nsILoginInfo.idl"
#include "koIRemoteFileInfo.idl"
#include "koIRemoteConnection.idl"
interface koIAsyncCallback;

/**
 * Komodo Server Account information.
 * @since Komodo 5.0.0
 */
[scriptable, uuid(a48abf34-6fc8-4c0e-a0a0-a842dff807eb)]
interface koIServerInfo : nsISupports {
    readonly attribute wstring guid; // guid of the correspondig nsILoginMetaInfo record
    readonly attribute wstring raw_hostdata;  // Host data, as stored by the nsILoginManager
    readonly attribute wstring protocol;
    readonly attribute wstring alias;
    readonly attribute wstring hostname;
    readonly attribute long port;
    readonly attribute wstring username;
    readonly attribute wstring password;
    readonly attribute wstring path;
    readonly attribute boolean passive;
    readonly attribute wstring privatekey;

    // Initialize the Komodo server information from the data provided.
    void init(in wstring guid, in wstring protocol, in wstring alias,
              in wstring hostname, in wstring port, in wstring username,
              in wstring password, in wstring path, in wstring passive,
              [optional] in wstring privatekey);

    // Initialize the Komodo server information from the nsILoginInfo.
    void initFromLoginInfo(in nsILoginInfo logininfo);

    // Create a nsILoginInfo from the Komodo server information.
    nsILoginInfo generateLoginInfo();
};

[scriptable, uuid(D99E7A30-C5F3-43A7-8029-144097D41904)]
interface koIRemoteConnectionService : nsISupports {

    // Return true if the given url has the prefix that is supported by the
    // remote connection service. I.e. starts with "ftp://", "scp://" etc...
    boolean isSupportedRemoteUrl(in wstring url);

    // Return a list of protocols the remote connection service can support
    void getSupportedProtocolNames(out unsigned long count,
                                   [array, size_is(count), retval] out wstring protocols);

    // Return url for given connection and koRemoteFileInfo object
    wstring getUriForConnectionAndRfInfo(in koIRemoteConnection connection,
                                         in koIRemoteFileInfo rfinfo);

    // Get a connection object given the connection parameters.
    //  "protocol" is the connection protocol used, i.e. "ftp", "sftp"
    //  "server" is the remote host name/ip address for the connection.
    //  "port" is remote port number.
    //  "username" is the username used when trying to log in.
    //  "password" is the password used when trying to log in.
    //  "path" is the path we want to open or go to (only used for display purposes)
    void getConnection(in wstring protocol, in wstring server, in long port,
                       in wstring username, in wstring password, in wstring path,
                       [retval] out koIRemoteConnection connection);

    // Get a connection object given the connection parameters.
    //  "protocol" is the connection protocol used, i.e. "ftp", "sftp"
    //  "server" is the remote host name/ip address for the connection.
    //  "port" is remote port number.
    //  "username" is the username used when trying to log in.
    //  "password" is the password used when trying to log in.
    //  "path" is the path we want to open or go to (only used for display purposes)
    //  "passive" is the ftp mode, when False it means to use 'Active' ftp mode
    //  "privatekey" is the optional file path of a SSH private key file.
    void getConnection2(in wstring protocol, in wstring server, in long port,
                        in wstring username, in wstring password,
                        in wstring path, in boolean passive,
                        [optional] in wstring privatekey,
                        [retval] out koIRemoteConnection connection);

    // Return the connection object for the given URI, all the connection
    // details should be included in the supplied URI
    // ex: ftp://test:tesuser@somesite.com:21/web/info.php
    void getConnectionUsingUri(in wstring uri,
                               [retval] out koIRemoteConnection connection);

    // Like getConnectionUsingUri, but does not cache or re-use a cahce
    // connection. Used when threaded access can be contentous.
    void getConnectionUsingUriNoCache(in wstring uri,
                                      [retval] out koIRemoteConnection connection);

    /**
     * Return the connection object for the given server alias.
     * @since Komodo 4.4.0
     */
    void getConnectionUsingServerAlias(in wstring server_alias,
                                       [retval] out koIRemoteConnection connection);
    
    void getConnByAliasAsync(in wstring server_alias, in koIAsyncCallback callback);

    /**
     * Return the connection object for the given serverInfo.
     * @since Komodo 9.0.0
     */
    void getConnectionUsingServerInfo(in koIServerInfo serverInfo,
                                      [retval] out koIRemoteConnection connection);

    // Return the server details for the given URI, array list
    //   0-protocol, 1-server alias, 2-hostname, 3-port,
    //   4-username, 5-password, 6-path, 7-passive, 8-privatekey
    void getServerDetailsFromUri(in wstring uri, out unsigned long count,
                                 [array, size_is(count)] out wstring data);

    // Return the server preferences for the given server alias, array list
    //   0-protocol, 1-server alias, 2-hostname, 3-port,
    //   4-username, 5-password, 6-path, 7-passive, 8-privatekey
    void getServerPrefSettings(in wstring server_alias, out unsigned long count,
                               [array, size_is(count)] out wstring data);

    // Functions to cache username/passwords for a connection, so we don't keep
    // prompting the user when they have already entered this information
    void saveSessionInfo(in wstring key, [array, size_is(count)]
                         in wstring text, in unsigned long count);
    void getSessionInfo(in wstring key, out unsigned long count,
                        [array, size_is(count)] out wstring data);

    // Functions to cache remote file information for a connection, so we don't
    // keep requesting the same information from the server over and over
    //   cache_key: key for connection, usually "%s:%s" % (hostname, username)
    //   path:      remote path on the server
    //   rfinfo:    Information on the path (size, mode, child nodes etc...)
    void setCachedRFInfo(in wstring cache_key, in wstring path,
                         in koIRemoteFileInfo rfinfo);
    void getCachedRFInfo(in wstring cache_key, in wstring path,
                         [retval] out koIRemoteFileInfo rfinfo);
    //   removeChildPaths: whether to remove cached files that start with this path
    void removeCachedRFInfo(in wstring cache_key, in wstring path, in long removeChildPaths);

    /**
     * Return the server information for the given server alias.
     * @since Komodo 5.0.0
     */
    koIServerInfo getServerInfoForAlias(in wstring server_alias);

    /**
     * Return the list of servers, in koIServerInfo format.
     * @since Komodo 5.0.0
     */
    void getServerInfoList(out unsigned long count,
                           [array, size_is(count), retval] out koIServerInfo servers);
    /**
     * Save the list of servers, in koIServerInfo format.
     * @since Komodo 5.0.0
     */
    void saveServerInfoList(in unsigned long count,
                            [array, size_is(count)] in koIServerInfo servers);
    
    /**
     * Reset the cached list of servers (sync has to do that when it creates new logins)
     * @since Komodo 6.1.0
     */
    void clearServerInfoListCache();

    /**
     * Clear the connection cache.
     * @since Komodo 6.0.0
     */
    void clearConnectionCache();

    /**
     * Remove this connection from the connection cache.
     * @since Komodo 6.0.0
     */
    void removeConnectionFromCache(in koIRemoteConnection connection);
};
