michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: 
michael@0: #include "nsISupports.idl"
michael@0: 
michael@0: interface nsIFile;
michael@0: interface nsILoginInfo;
michael@0: interface nsIPropertyBag;
michael@0: 
michael@0: [scriptable, uuid(fe0a4e80-d36f-43cc-a37b-4e1906e77257)]
michael@0: 
michael@0: /*
michael@0:  * NOTE: This interface is intended to be implemented by modules
michael@0:  *       providing storage mechanisms for the login manager.
michael@0:  *       Other code should use the login manager's interfaces
michael@0:  *       (nsILoginManager), and should not call storage modules
michael@0:  *       directly.
michael@0:  */
michael@0: interface nsILoginManagerStorage : nsISupports {
michael@0:     /**
michael@0:      * Initialize the component. Not invoked automatically.
michael@0:      */
michael@0:     void init();
michael@0: 
michael@0: 
michael@0:     /**
michael@0:      * Initialize the component, but override the default filename
michael@0:      * locations. This is primarily used to the unit tests and profile
michael@0:      * migration.
michael@0:      *
michael@0:      * @param aFile
michael@0:      *        If non-null, file to use for login storage.
michael@0:      *
michael@0:      */
michael@0:     void initWithFile(in nsIFile aFile);
michael@0: 
michael@0: 
michael@0:     /**
michael@0:      * Store a new login in the storage module.
michael@0:      *
michael@0:      * @param aLogin
michael@0:      *        The login to be added.
michael@0:      *
michael@0:      * Default values for the login's nsILoginMetaInfo properties will be
michael@0:      * created. However, if the caller specifies non-default values, they will
michael@0:      * be used instead.
michael@0:      */
michael@0:     void addLogin(in nsILoginInfo aLogin);
michael@0: 
michael@0: 
michael@0:     /**
michael@0:      * Remove a login from the storage module.
michael@0:      *
michael@0:      * @param aLogin
michael@0:      *        The login to be removed.
michael@0:      *
michael@0:      * The specified login must exactly match a stored login. However, the
michael@0:      * values of any nsILoginMetaInfo properties are ignored.
michael@0:      */
michael@0:     void removeLogin(in nsILoginInfo aLogin);
michael@0: 
michael@0: 
michael@0:     /**
michael@0:      * Modify an existing login in the storage module.
michael@0:      *
michael@0:      * @param oldLogin
michael@0:      *        The login to be modified.
michael@0:      * @param newLoginData
michael@0:      *        The new login values (either a nsILoginInfo or nsIProperyBag)
michael@0:      *
michael@0:      * If newLoginData is a nsILoginInfo, all of the old login's nsILoginInfo
michael@0:      * properties are changed to the values from newLoginData (but the old
michael@0:      * login's nsILoginMetaInfo properties are unmodified).
michael@0:      *
michael@0:      * If newLoginData is a nsIPropertyBag, only the specified properties
michael@0:      * will be changed. The nsILoginMetaInfo properties of oldLogin can be
michael@0:      * changed in this manner.
michael@0:      *
michael@0:      * If the propertybag contains an item named "timesUsedIncrement", the
michael@0:      * login's timesUsed property will be incremented by the item's value.
michael@0:      */
michael@0:     void modifyLogin(in nsILoginInfo oldLogin, in nsISupports newLoginData);
michael@0: 
michael@0: 
michael@0:     /**
michael@0:      * Remove all stored logins.
michael@0:      *
michael@0:      * The browser sanitization feature allows the user to clear any stored
michael@0:      * passwords. This interface allows that to be done without getting each
michael@0:      * login first (which might require knowing the master password).
michael@0:      *
michael@0:      */
michael@0:     void removeAllLogins();
michael@0: 
michael@0: 
michael@0:     /**
michael@0:      * Fetch all logins in the login manager. An array is always returned;
michael@0:      * if there are no logins the array is empty.
michael@0:      *
michael@0:      * @param count
michael@0:      *        The number of elements in the array. JS callers can simply use
michael@0:      *        the array's .length property and omit this param.
michael@0:      * @param logins
michael@0:      *        An array of nsILoginInfo objects.
michael@0:      *
michael@0:      * NOTE: This can be called from JS as:
michael@0:      *       var logins = pwmgr.getAllLogins();
michael@0:      *       (|logins| is an array).
michael@0:      */
michael@0:     void getAllLogins([optional] out unsigned long count,
michael@0:                       [retval, array, size_is(count)] out nsILoginInfo logins);
michael@0: 
michael@0: 
michael@0:     /**
michael@0:     * Fetch all logins in the login manager. An array is always returned;
michael@0:     * if there are no logins the array is empty. This does not decrypt logins
michael@0:     * before returning the array
michael@0:     *
michael@0:     * @param count
michael@0:     *        The number of elements in the array. JS callers can simply use
michael@0:     *        the array's .length property and omit this param.
michael@0:     * @param logins
michael@0:     *        An array of nsILoginInfo objects.
michael@0:     *
michael@0:     * NOTE: This can be called from JS as:
michael@0:     *       var logins = pwmgr.getAllEncryptedLogins();
michael@0:     *       (|logins| is an array).
michael@0:     */
michael@0:     void getAllEncryptedLogins([optional] out unsigned long count,
michael@0:                                [retval, array, size_is(count)] out nsILoginInfo logins);
michael@0: 
michael@0: 
michael@0:     /**
michael@0:      * Search for logins in the login manager. An array is always returned;
michael@0:      * if there are no logins the array is empty.
michael@0:      *
michael@0:      * @param count
michael@0:      *        The number of elements in the array. JS callers can simply use
michael@0:      *        the array's .length property, and supply an dummy object for
michael@0:      *        this out param. For example: |searchLogins({}, matchData)|
michael@0:      * @param matchData
michael@0:      *        The data used to search. This does not follow the same
michael@0:      *        requirements as findLogins for those fields. Wildcard matches are
michael@0:      *        simply not specified.
michael@0:      * @param logins
michael@0:      *        An array of nsILoginInfo objects.
michael@0:      *
michael@0:      * NOTE: This can be called from JS as:
michael@0:      *       var logins = pwmgr.searchLogins({}, matchData);
michael@0:      *       (|logins| is an array).
michael@0:      */
michael@0:     void searchLogins(out unsigned long count, in nsIPropertyBag matchData,
michael@0:                       [retval, array, size_is(count)] out nsILoginInfo logins);
michael@0: 
michael@0: 
michael@0:     /**
michael@0:      * Obtain a list of all hosts for which password saving is disabled.
michael@0:      *
michael@0:      * @param count
michael@0:      *        The number of elements in the array. JS callers can simply use
michael@0:      *        the array's .length property and omit this param.
michael@0:      * @param hostnames
michael@0:      *        An array of hostname strings, in origin URL format without a
michael@0:      *        pathname. For example: "https://www.site.com".
michael@0:      *
michael@0:      * NOTE: This can be called from JS as:
michael@0:      *       var logins = pwmgr.getAllDisabledHosts();
michael@0:      */
michael@0:     void getAllDisabledHosts([optional] out unsigned long count,
michael@0:                       [retval, array, size_is(count)] out wstring hostnames);
michael@0: 
michael@0: 
michael@0:     /**
michael@0:      * Check to see if saving logins has been disabled for a host.
michael@0:      *
michael@0:      * @param aHost
michael@0:      *        The hostname to check. This argument should be in the origin
michael@0:      *        URL format, without a pathname. For example: "http://foo.com".
michael@0:      */
michael@0:     boolean getLoginSavingEnabled(in AString aHost);
michael@0: 
michael@0: 
michael@0:     /**
michael@0:      * Disable (or enable) storing logins for the specified host. When
michael@0:      * disabled, the login manager will not prompt to store logins for
michael@0:      * that host. Existing logins are not affected.
michael@0:      *
michael@0:      * @param aHost
michael@0:      *        The hostname to set. This argument should be in the origin
michael@0:      *        URL format, without a pathname. For example: "http://foo.com".
michael@0:      * @param isEnabled
michael@0:      *        Specify if saving logins should be enabled (true) or
michael@0:      *        disabled (false)
michael@0:      */
michael@0:     void setLoginSavingEnabled(in AString aHost, in boolean isEnabled);
michael@0: 
michael@0: 
michael@0:     /**
michael@0:      * Search for logins matching the specified criteria. Called when looking
michael@0:      * for logins that might be applicable to a form or authentication request.
michael@0:      *
michael@0:      * @param count
michael@0:      *        The number of elements in the array. JS callers can simply use
michael@0:      *        the array's .length property, and supply an dummy object for
michael@0:      *        this out param. For example: |findLogins({}, hostname, ...)|
michael@0:      * @param aHostname
michael@0:      *        The hostname to restrict searches to, in URL format. For
michael@0:      *        example: "http://www.site.com".
michael@0:      * @param aActionURL
michael@0:      *        For form logins, this argument should be the URL to which the
michael@0:      *        form will be submitted. For protocol logins, specify null.
michael@0:      * @param aHttpRealm
michael@0:      *        For protocol logins, this argument should be the HTTP Realm
michael@0:      *        for which the login applies. This is obtained from the
michael@0:      *        WWW-Authenticate header. See RFC2617. For form logins,
michael@0:      *        specify null.
michael@0:      * @param logins
michael@0:      *        An array of nsILoginInfo objects.
michael@0:      *
michael@0:      * NOTE: This can be called from JS as:
michael@0:      *       var logins = pwmgr.findLogins({}, hostname, ...);
michael@0:      *
michael@0:      */
michael@0:     void findLogins(out unsigned long count, in AString aHostname,
michael@0:                     in AString aActionURL,   in AString aHttpRealm,
michael@0:                     [retval, array, size_is(count)] out nsILoginInfo logins);
michael@0: 
michael@0: 
michael@0:    /**
michael@0:     * Search for logins matching the specified criteria, as with
michael@0:     * findLogins(). This interface only returns the number of matching
michael@0:     * logins (and not the logins themselves), which allows a caller to
michael@0:     * check for logins without causing the user to be prompted for a master
michael@0:     * password to decrypt the logins.
michael@0:     *
michael@0:     * @param aHostname
michael@0:     *        The hostname to restrict searches to. Specify an empty string
michael@0:     *        to match all hosts. A null value will not match any logins, and
michael@0:     *        will thus always return a count of 0.
michael@0:     * @param aActionURL
michael@0:     *        The URL to which a form login will be submitted. To match any
michael@0:     *        form login, specify an empty string. To not match any form
michael@0:     *        login, specify null.
michael@0:     * @param aHttpRealm
michael@0:     *        The HTTP Realm for which the login applies. To match logins for
michael@0:     *        any realm, specify an empty string. To not match logins for any
michael@0:     *        realm, specify null.
michael@0:     */
michael@0:    unsigned long countLogins(in AString aHostname, in AString aActionURL,
michael@0:                              in AString aHttpRealm);
michael@0:    /**
michael@0:     * True when a master password prompt is being shown.
michael@0:     */
michael@0:     readonly attribute boolean uiBusy;
michael@0: 
michael@0:    /**
michael@0:     * True when the master password has already been entered, and so a caller
michael@0:     * can ask for decrypted logins without triggering a prompt.
michael@0:     */
michael@0:     readonly attribute boolean isLoggedIn;
michael@0: };