1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/toolkit/components/passwordmgr/nsILoginManagerStorage.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,263 @@
1.4 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.5 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.6 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.7 +
1.8 +
1.9 +#include "nsISupports.idl"
1.10 +
1.11 +interface nsIFile;
1.12 +interface nsILoginInfo;
1.13 +interface nsIPropertyBag;
1.14 +
1.15 +[scriptable, uuid(fe0a4e80-d36f-43cc-a37b-4e1906e77257)]
1.16 +
1.17 +/*
1.18 + * NOTE: This interface is intended to be implemented by modules
1.19 + * providing storage mechanisms for the login manager.
1.20 + * Other code should use the login manager's interfaces
1.21 + * (nsILoginManager), and should not call storage modules
1.22 + * directly.
1.23 + */
1.24 +interface nsILoginManagerStorage : nsISupports {
1.25 + /**
1.26 + * Initialize the component. Not invoked automatically.
1.27 + */
1.28 + void init();
1.29 +
1.30 +
1.31 + /**
1.32 + * Initialize the component, but override the default filename
1.33 + * locations. This is primarily used to the unit tests and profile
1.34 + * migration.
1.35 + *
1.36 + * @param aFile
1.37 + * If non-null, file to use for login storage.
1.38 + *
1.39 + */
1.40 + void initWithFile(in nsIFile aFile);
1.41 +
1.42 +
1.43 + /**
1.44 + * Store a new login in the storage module.
1.45 + *
1.46 + * @param aLogin
1.47 + * The login to be added.
1.48 + *
1.49 + * Default values for the login's nsILoginMetaInfo properties will be
1.50 + * created. However, if the caller specifies non-default values, they will
1.51 + * be used instead.
1.52 + */
1.53 + void addLogin(in nsILoginInfo aLogin);
1.54 +
1.55 +
1.56 + /**
1.57 + * Remove a login from the storage module.
1.58 + *
1.59 + * @param aLogin
1.60 + * The login to be removed.
1.61 + *
1.62 + * The specified login must exactly match a stored login. However, the
1.63 + * values of any nsILoginMetaInfo properties are ignored.
1.64 + */
1.65 + void removeLogin(in nsILoginInfo aLogin);
1.66 +
1.67 +
1.68 + /**
1.69 + * Modify an existing login in the storage module.
1.70 + *
1.71 + * @param oldLogin
1.72 + * The login to be modified.
1.73 + * @param newLoginData
1.74 + * The new login values (either a nsILoginInfo or nsIProperyBag)
1.75 + *
1.76 + * If newLoginData is a nsILoginInfo, all of the old login's nsILoginInfo
1.77 + * properties are changed to the values from newLoginData (but the old
1.78 + * login's nsILoginMetaInfo properties are unmodified).
1.79 + *
1.80 + * If newLoginData is a nsIPropertyBag, only the specified properties
1.81 + * will be changed. The nsILoginMetaInfo properties of oldLogin can be
1.82 + * changed in this manner.
1.83 + *
1.84 + * If the propertybag contains an item named "timesUsedIncrement", the
1.85 + * login's timesUsed property will be incremented by the item's value.
1.86 + */
1.87 + void modifyLogin(in nsILoginInfo oldLogin, in nsISupports newLoginData);
1.88 +
1.89 +
1.90 + /**
1.91 + * Remove all stored logins.
1.92 + *
1.93 + * The browser sanitization feature allows the user to clear any stored
1.94 + * passwords. This interface allows that to be done without getting each
1.95 + * login first (which might require knowing the master password).
1.96 + *
1.97 + */
1.98 + void removeAllLogins();
1.99 +
1.100 +
1.101 + /**
1.102 + * Fetch all logins in the login manager. An array is always returned;
1.103 + * if there are no logins the array is empty.
1.104 + *
1.105 + * @param count
1.106 + * The number of elements in the array. JS callers can simply use
1.107 + * the array's .length property and omit this param.
1.108 + * @param logins
1.109 + * An array of nsILoginInfo objects.
1.110 + *
1.111 + * NOTE: This can be called from JS as:
1.112 + * var logins = pwmgr.getAllLogins();
1.113 + * (|logins| is an array).
1.114 + */
1.115 + void getAllLogins([optional] out unsigned long count,
1.116 + [retval, array, size_is(count)] out nsILoginInfo logins);
1.117 +
1.118 +
1.119 + /**
1.120 + * Fetch all logins in the login manager. An array is always returned;
1.121 + * if there are no logins the array is empty. This does not decrypt logins
1.122 + * before returning the array
1.123 + *
1.124 + * @param count
1.125 + * The number of elements in the array. JS callers can simply use
1.126 + * the array's .length property and omit this param.
1.127 + * @param logins
1.128 + * An array of nsILoginInfo objects.
1.129 + *
1.130 + * NOTE: This can be called from JS as:
1.131 + * var logins = pwmgr.getAllEncryptedLogins();
1.132 + * (|logins| is an array).
1.133 + */
1.134 + void getAllEncryptedLogins([optional] out unsigned long count,
1.135 + [retval, array, size_is(count)] out nsILoginInfo logins);
1.136 +
1.137 +
1.138 + /**
1.139 + * Search for logins in the login manager. An array is always returned;
1.140 + * if there are no logins the array is empty.
1.141 + *
1.142 + * @param count
1.143 + * The number of elements in the array. JS callers can simply use
1.144 + * the array's .length property, and supply an dummy object for
1.145 + * this out param. For example: |searchLogins({}, matchData)|
1.146 + * @param matchData
1.147 + * The data used to search. This does not follow the same
1.148 + * requirements as findLogins for those fields. Wildcard matches are
1.149 + * simply not specified.
1.150 + * @param logins
1.151 + * An array of nsILoginInfo objects.
1.152 + *
1.153 + * NOTE: This can be called from JS as:
1.154 + * var logins = pwmgr.searchLogins({}, matchData);
1.155 + * (|logins| is an array).
1.156 + */
1.157 + void searchLogins(out unsigned long count, in nsIPropertyBag matchData,
1.158 + [retval, array, size_is(count)] out nsILoginInfo logins);
1.159 +
1.160 +
1.161 + /**
1.162 + * Obtain a list of all hosts for which password saving is disabled.
1.163 + *
1.164 + * @param count
1.165 + * The number of elements in the array. JS callers can simply use
1.166 + * the array's .length property and omit this param.
1.167 + * @param hostnames
1.168 + * An array of hostname strings, in origin URL format without a
1.169 + * pathname. For example: "https://www.site.com".
1.170 + *
1.171 + * NOTE: This can be called from JS as:
1.172 + * var logins = pwmgr.getAllDisabledHosts();
1.173 + */
1.174 + void getAllDisabledHosts([optional] out unsigned long count,
1.175 + [retval, array, size_is(count)] out wstring hostnames);
1.176 +
1.177 +
1.178 + /**
1.179 + * Check to see if saving logins has been disabled for a host.
1.180 + *
1.181 + * @param aHost
1.182 + * The hostname to check. This argument should be in the origin
1.183 + * URL format, without a pathname. For example: "http://foo.com".
1.184 + */
1.185 + boolean getLoginSavingEnabled(in AString aHost);
1.186 +
1.187 +
1.188 + /**
1.189 + * Disable (or enable) storing logins for the specified host. When
1.190 + * disabled, the login manager will not prompt to store logins for
1.191 + * that host. Existing logins are not affected.
1.192 + *
1.193 + * @param aHost
1.194 + * The hostname to set. This argument should be in the origin
1.195 + * URL format, without a pathname. For example: "http://foo.com".
1.196 + * @param isEnabled
1.197 + * Specify if saving logins should be enabled (true) or
1.198 + * disabled (false)
1.199 + */
1.200 + void setLoginSavingEnabled(in AString aHost, in boolean isEnabled);
1.201 +
1.202 +
1.203 + /**
1.204 + * Search for logins matching the specified criteria. Called when looking
1.205 + * for logins that might be applicable to a form or authentication request.
1.206 + *
1.207 + * @param count
1.208 + * The number of elements in the array. JS callers can simply use
1.209 + * the array's .length property, and supply an dummy object for
1.210 + * this out param. For example: |findLogins({}, hostname, ...)|
1.211 + * @param aHostname
1.212 + * The hostname to restrict searches to, in URL format. For
1.213 + * example: "http://www.site.com".
1.214 + * @param aActionURL
1.215 + * For form logins, this argument should be the URL to which the
1.216 + * form will be submitted. For protocol logins, specify null.
1.217 + * @param aHttpRealm
1.218 + * For protocol logins, this argument should be the HTTP Realm
1.219 + * for which the login applies. This is obtained from the
1.220 + * WWW-Authenticate header. See RFC2617. For form logins,
1.221 + * specify null.
1.222 + * @param logins
1.223 + * An array of nsILoginInfo objects.
1.224 + *
1.225 + * NOTE: This can be called from JS as:
1.226 + * var logins = pwmgr.findLogins({}, hostname, ...);
1.227 + *
1.228 + */
1.229 + void findLogins(out unsigned long count, in AString aHostname,
1.230 + in AString aActionURL, in AString aHttpRealm,
1.231 + [retval, array, size_is(count)] out nsILoginInfo logins);
1.232 +
1.233 +
1.234 + /**
1.235 + * Search for logins matching the specified criteria, as with
1.236 + * findLogins(). This interface only returns the number of matching
1.237 + * logins (and not the logins themselves), which allows a caller to
1.238 + * check for logins without causing the user to be prompted for a master
1.239 + * password to decrypt the logins.
1.240 + *
1.241 + * @param aHostname
1.242 + * The hostname to restrict searches to. Specify an empty string
1.243 + * to match all hosts. A null value will not match any logins, and
1.244 + * will thus always return a count of 0.
1.245 + * @param aActionURL
1.246 + * The URL to which a form login will be submitted. To match any
1.247 + * form login, specify an empty string. To not match any form
1.248 + * login, specify null.
1.249 + * @param aHttpRealm
1.250 + * The HTTP Realm for which the login applies. To match logins for
1.251 + * any realm, specify an empty string. To not match logins for any
1.252 + * realm, specify null.
1.253 + */
1.254 + unsigned long countLogins(in AString aHostname, in AString aActionURL,
1.255 + in AString aHttpRealm);
1.256 + /**
1.257 + * True when a master password prompt is being shown.
1.258 + */
1.259 + readonly attribute boolean uiBusy;
1.260 +
1.261 + /**
1.262 + * True when the master password has already been entered, and so a caller
1.263 + * can ask for decrypted logins without triggering a prompt.
1.264 + */
1.265 + readonly attribute boolean isLoggedIn;
1.266 +};
