Source code

Revision control

Other Tools

1
/* This Source Code Form is subject to the terms of the Mozilla Public
2
* License, v. 2.0. If a copy of the MPL was not distributed with this
3
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
4
5
6
#include "nsISupports.idl"
7
8
interface nsIFile;
9
interface nsILoginInfo;
10
interface nsIPropertyBag;
11
12
/**
13
* NOTE: This interface is intended to be implemented by modules
14
* providing storage mechanisms for the login manager.
15
* Other code should use the login manager's interfaces
16
* (nsILoginManager), and should not call storage modules
17
* directly.
18
*/
19
[scriptable, uuid(5df81a93-25e6-4b45-a696-089479e15c7d)]
20
interface nsILoginManagerStorage : nsISupports {
21
/**
22
* Initialize the component.
23
*
24
* At present, other methods of this interface may be called before the
25
* returned promise is resolved or rejected.
26
*
27
* @return {Promise}
28
* @resolves When initialization is complete.
29
* @rejects JavaScript exception.
30
*/
31
Promise initialize();
32
33
34
/**
35
* Ensures that all data has been written to disk and all files are closed.
36
*
37
* At present, this method is called by regression tests only. Finalization
38
* on shutdown is done by observers within the component.
39
*
40
* @return {Promise}
41
* @resolves When finalization is complete.
42
* @rejects JavaScript exception.
43
*/
44
Promise terminate();
45
46
47
/**
48
* Store a new login in the storage module.
49
*
50
* @param aLogin
51
* The login to be added.
52
* @param aPreEncrypted
53
* Whether the login was already encrypted or not.
54
* @param aPlaintextUsername
55
* The plaintext username, if the login was already encrypted.
56
* @param aPlaintextPassword
57
* The plaintext password, if the login was already encrypted.
58
* @return a clone of the login info with the guid set (even if it was not provided).
59
*
60
* Default values for the login's nsILoginMetaInfo properties will be
61
* created. However, if the caller specifies non-default values, they will
62
* be used instead.
63
*/
64
nsILoginInfo addLogin(in nsILoginInfo aLogin, [optional] in boolean aPreEncrypted, [optional] in jsval aPlaintextUsername, [optional] in jsval aPlaintextPassword);
65
66
67
/**
68
* Remove a login from the storage module.
69
*
70
* @param aLogin
71
* The login to be removed.
72
*
73
* The specified login must exactly match a stored login. However, the
74
* values of any nsILoginMetaInfo properties are ignored.
75
*/
76
void removeLogin(in nsILoginInfo aLogin);
77
78
79
/**
80
* Modify an existing login in the storage module.
81
*
82
* @param oldLogin
83
* The login to be modified.
84
* @param newLoginData
85
* The new login values (either a nsILoginInfo or nsIProperyBag)
86
*
87
* If newLoginData is a nsILoginInfo, all of the old login's nsILoginInfo
88
* properties are changed to the values from newLoginData (but the old
89
* login's nsILoginMetaInfo properties are unmodified).
90
*
91
* If newLoginData is a nsIPropertyBag, only the specified properties
92
* will be changed. The nsILoginMetaInfo properties of oldLogin can be
93
* changed in this manner.
94
*
95
* If the propertybag contains an item named "timesUsedIncrement", the
96
* login's timesUsed property will be incremented by the item's value.
97
*/
98
void modifyLogin(in nsILoginInfo oldLogin, in nsISupports newLoginData);
99
100
101
/**
102
* Record that the password of a saved login was used (e.g. submitted or copied).
103
*
104
* @param nsILoginInfo aLogin
105
* The login record of the password that was used.
106
*
107
* If only the username was used, this method shouldn't be called as we don't
108
* want to double-count the use if both the username and password are copied.
109
* Copying of the username normally precedes the copying of the password anyways.
110
*/
111
void recordPasswordUse(in nsILoginInfo aLogin);
112
113
114
/**
115
* Remove all stored logins.
116
*
117
* The browser sanitization feature allows the user to clear any stored
118
* passwords. This interface allows that to be done without getting each
119
* login first (which might require knowing the master password).
120
*/
121
void removeAllLogins();
122
123
124
/**
125
* Fetch all logins in the login manager. An array is always returned;
126
* if there are no logins the array is empty.
127
*
128
* @return An array of nsILoginInfo objects.
129
*/
130
Array<nsILoginInfo> getAllLogins();
131
132
/**
133
* Fetch all logins in the login manager. An array is always returned;
134
* if there are no logins the array is empty.
135
*
136
* @return An array of nsILoginInfo objects.
137
*/
138
Promise getAllLoginsAsync();
139
140
/**
141
* Asynchonously search for logins in the login manager. The Promise always
142
* resolves to an array; if there are no logins the array is empty.
143
*
144
* @param {object} matchData
145
* The data used to search as a JS object. This does not follow the same
146
* requirements as findLogins for those fields. Wildcard matches are
147
* simply not specified.
148
* @return A promise resolving to an array of nsILoginInfo objects.
149
*/
150
Promise searchLoginsAsync(in jsval matchData);
151
152
/**
153
* Search for logins in the login manager. An array is always returned;
154
* if there are no logins the array is empty.
155
* @deprecated New code should use `searchLoginsAsync`.
156
* Only autocomplete, prompt, and test code still use this.
157
*
158
* @param matchData
159
* The data used to search. This does not follow the same
160
* requirements as findLogins for those fields. Wildcard matches are
161
* simply not specified.
162
* @return An array of nsILoginInfo objects.
163
*/
164
Array<nsILoginInfo> searchLogins(in nsIPropertyBag matchData);
165
166
/**
167
* Search for logins matching the specified criteria. Called when looking
168
* for logins that might be applicable to a form or authentication request.
169
*
170
* @param aOrigin
171
* The origin to restrict searches to. For example: "http://www.site.com".
172
* @param aActionURL
173
* For form logins, this argument should be the origin to which the
174
* form will be submitted. For HTTP auth. logins, specify null.
175
* @param aHttpRealm
176
* For protocol logins, this argument should be the HTTP Realm
177
* for which the login applies. This is obtained from the
178
* WWW-Authenticate header. See RFC2617. For form logins,
179
* specify null.
180
* @return An array of nsILoginInfo objects.
181
*/
182
Array<nsILoginInfo> findLogins(in AString aOrigin, in AString aActionOrigin,
183
in AString aHttpRealm);
184
185
186
/**
187
* Search for logins matching the specified criteria, as with
188
* findLogins(). This interface only returns the number of matching
189
* logins (and not the logins themselves), which allows a caller to
190
* check for logins without causing the user to be prompted for a master
191
* password to decrypt the logins.
192
*
193
* @param aOrigin
194
* The origin to restrict searches to. Specify an empty string
195
* to match all origins. A null value will not match any logins, and
196
* will thus always return a count of 0.
197
* @param aActionOrigin
198
* The origin to which a form login will be submitted. To match any
199
* form login, specify an empty string. To not match any form
200
* login, specify null.
201
* @param aHttpRealm
202
* The HTTP Realm for which the login applies. To match logins for
203
* any realm, specify an empty string. To not match logins for any
204
* realm, specify null.
205
*/
206
unsigned long countLogins(in AString aOrigin, in AString aActionOrigin,
207
in AString aHttpRealm);
208
/**
209
* True when a master password prompt is being shown.
210
*/
211
readonly attribute boolean uiBusy;
212
213
/**
214
* True when the master password has already been entered, and so a caller
215
* can ask for decrypted logins without triggering a prompt.
216
*/
217
readonly attribute boolean isLoggedIn;
218
};