gecko/toolkit/components/passwordmgr/public/nsILoginManager.idl

/* ***** 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 mozilla.org code.
 *
 * The Initial Developer of the Original Code is Mozilla Corporation.
 * Portions created by the Initial Developer are Copyright (C) 2007
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s):
 *  Justin Dolske <dolske@mozilla.com> (original author)
 *
 * 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"

interface nsIURI;
interface nsILoginInfo;
interface nsIAutoCompleteResult;
interface nsIDOMHTMLInputElement;

[scriptable, uuid(579f45b7-682f-479f-9085-3f8075488803)]

interface nsILoginManager : nsISupports {

    /**
    * Store a new login in the login manager.
    *
    * @param aLogin
    *        The login to be added.
    */
    void addLogin(in nsILoginInfo aLogin);


    /**
    * Remove a login from the login manager.
    *
    * @param aLogin
    *        The login to be removed.
    */
    void removeLogin(in nsILoginInfo aLogin);


    /**
    * Modify an existing login in the login manager.
    *
    * @param aLogin
    *        The login to be modified.
    */
    void modifyLogin(in nsILoginInfo oldLogin, in nsILoginInfo newLogin);


    /**
    * Remove all logins known to login manager.
    *
    * The browser sanitization feature allows the user to clear any stored
    * passwords. This interface allows that to be done without getting each
    * login first (which might require knowing the master password).
    *
    */
    void removeAllLogins();


    /**
    * Fetch all logins in the login manager. An array is always returned;
    * if there are no logins the array is empty.
    *
    * @param count
    *        The number of elements in the array. JS callers can simply use
    *        the array's .length property, and supply an dummy object for
    *        this out param. For example: |getAllLogins({})|
    * @param logins
    *        An array of nsILoginInfo objects. 
    *
    * NOTE: This can be called from JS as:
    *       var logins = pwmgr.getAllLogins({});
    *       (|logins| is an array).
    */
    void getAllLogins(out unsigned long count,
                      [retval, array, size_is(count)] out nsILoginInfo logins);

    
    /**
    * Obtain a list of all hosts for which password saving is disabled.
    *
    * @param count
    *        The number of elements in the array. JS callers can simply use
    *        the array's .length property, and supply an dummy object for
    *        this out param. For example: |getAllDisabledHosts({})|
    * @param hostnames
    *        An array of hostname strings, in origin URL format without a
    *        pathname. For example: "https://www.site.com".
    *
    * NOTE: This can be called from JS as:
    *       var logins = pwmgr.getDisabledAllLogins({});
    */
    void getAllDisabledHosts(out unsigned long count,
                      [retval, array, size_is(count)] out wstring hostnames);


    /**
    * Check to see if saving logins has been disabled for a host.
    *
    * @param aHost
    *        The hostname to check. This argument should be in the origin
    *        URL format, without a pathname. For example: "http://foo.com".
    */
    boolean getLoginSavingEnabled(in AString aHost);


    /**
    * Disable (or enable) storing logins for the specified host. When
    * disabled, the login manager will not prompt to store logins for
    * that host. Existing logins are not affected.
    *
    * @param aHost
    *        The hostname to set. This argument should be in the origin
    *        URL format, without a pathname. For example: "http://foo.com".
    * @param isEnabled
    *        Specify if saving logins should be enabled (true) or
    *        disabled (false)
    */
    void setLoginSavingEnabled(in AString aHost, in boolean isEnabled);


    /**
    * Search for logins matching the specified criteria. Called when looking
    * for logins that might be applicable to a form or authentication request.
    *
    * @param count
    *        The number of elements in the array. JS callers can simply use
    *        the array's .length property, and supply an dummy object for
    *        this out param. For example: |findLogins({}, hostname, ...)|
    * @param aHostname
    *        The hostname to restict searches to. When looking for form
    *        logins, this argument should be in origin URL format, without
    *        a pathname. For example: "http://www.site.com". For protocol
    *        logins (http//ftp), it should be the hostname with a port
    *        appended. For example: "www.bar.com:443".
    * @param aActionURL
    *        For form logins, this argument should be the URL to which the
    *        form will be submitted. For protocol logins, specify null.
    * @param aHttpRealm
    *        For protocol logins, this argument should be the HTTP Realm
    *        for which the login applies. This is obtained from the
    *        WWW-Authenticate header. See RFC2617. For form logins,
    *        specify null.
    * @param logins
    *        An array of nsILoginInfo objects. 
    *
    * NOTE: This can be called from JS as:
    *       var logins = pwmgr.findLogins({}, hostname, ...);
    *
    */
    void findLogins(out unsigned long count, in AString aHostname,
                    in AString aActionURL,   in AString aHttpRealm,
                    [retval, array, size_is(count)] out nsILoginInfo logins);


    /**
    * Generate results for a userfield autocomplete menu.
    *
    * NOTE: This interface is provided for use only by the FormFillController,
    *       which calls it directly. This isn't really ideal, it should
    *       probably be callback registered through the FFC.
    */
    nsIAutoCompleteResult autoCompleteSearch(in AString aSearchString,
                                    in nsIAutoCompleteResult aPreviousResult,
                                    in nsIDOMHTMLInputElement aElement);
};

%{C++

#define NS_LOGINMANAGER_CONTRACTID "@mozilla.org/login-manager;1"

%}