nsILoginManagerStorage

by 4 contributors:

This interface is implemented by modules that wish to provide storage mechanisms for the Login Manager.
1.0
28
Introduced
Gecko 1.9
Inherits from: nsISupports Last changed in Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)

For example, if you wish to provide operating system integration with a native password manager system, implementing and registering a storage module for the Login Manager is how you do it. See Creating a Login Manager storage module for details.

Note: Extensions that simply want to access/store logins should use the Login Manager service and nsILoginManager interface instead. The Login Manager will handle selecting and using the correct nsILoginManangerStorage module.

Method overview

void addLogin(in nsILoginInfo aLogin);
unsigned long countLogins(in AString aHostname, in AString aActionURL, in AString aHttpRealm);
void findLogins(out unsigned long count, in AString aHostname, in AString aActionURL, in AString aHttpRealm, [retval, array, size_is(count)] out nsILoginInfo logins);
void getAllDisabledHosts([optional] out unsigned long count, [retval, array, size_is(count)] out wstring hostnames);
void getAllEncryptedLogins([optional] out unsigned long count, [retval, array, size_is(count)] out nsILoginInfo logins);
void getAllLogins([optional] out unsigned long count, [retval, array, size_is(count)] out nsILoginInfo logins);
boolean getLoginSavingEnabled(in AString aHost);
void init();
void initWithFile(in nsIFile aInputFile, in nsIFile aOutputFile);
void modifyLogin(in nsILoginInfo oldLogin, in nsISupports newLoginData);
void removeAllLogins();
void removeLogin(in nsILoginInfo aLogin);
void searchLogins(out unsigned long count, in nsIPropertyBag matchData, [retval, array, size_is(count)] out nsILoginInfo logins);
void setLoginSavingEnabled(in AString aHost, in boolean isEnabled);

Attributes

Attribute Type Description
uiBusy boolean true when a master password prompt is being shown. Read only.

Methods

addLogin()

Called by the Login Manager to store a new login.

Gecko 1.9.1 note
Default values for the nsILoginMetaInfo properties are created if the specified login doesn't explicitly specify them.

void addLogin(
  in nsILoginInfo aLogin
);
Parameters
aLogin
The login to add to the login storage.

countLogins()

Implement this method to return the number of logins matching the specified criteria. This method is called, for example, to check to see if there is a login that will match the criteria without having to ask the user for their master password in order to decrypt the logins.

unsigned long countLogins(
  in AString aHostname,
  in AString aActionURL,
  in AString aHttpRealm
);
Parameters
aHostname
The hostname to which to restrict the search. Specify an empty string to match all hosts. Passing null should not match any logins, and should return 0.
aActionURL
The URL of the form to which the login will be submitted. To match any form login, specify an empty string. To not match to any form login, specify null.
aHttpRealm
The HTTP realm for which the login applies. To match logins for any realm, specify an empty string. To not match any realm, specify null.
Return value

The number of logins that match the specified criteria.

findLogins()

Implement this method to search the login store for logins matching the specified criteria. This method is called by the Login Manager when looking for saved logins that might apply to a form or authentication request.

void findLogins(
  out unsigned long count,
  in AString aHostname,
  in AString aActionURL,
  in AString aHttpRealm,
  [retval, array, size_is(count)] out nsILoginInfo logins
);
Parameters
count
Return in this parameter the number of matching logins found by the search.
aHostname
The hostname to which to restrict the search. For example: "http://www.site.com". Specify an empty string to match all hosts. Passing null should not match any logins, and should return a count of 0.
aActionURL
The URL of the form to which the login will be submitted. To match any form login, specify an empty string. To not match to any form login, specify null.
aHttpRealm
The HTTP realm for which the login applies. To match logins for any realm, specify an empty string. To not match any realm, specify null.
logins
Return in this parameter an array of nsILoginInfo matching the search criteria.

getAllDisabledHosts()

Implement this method to return a list of all hosts for which password saving is disabled.

void getAllDisabledHosts(
  out unsigned long count, Optional
  [retval, array, size_is(count)] out wstring hostnames
);
Parameters
count Optional
Return in this parameter the number of disabled hostnames returned in the hostnames parameter.
hostnames
Return in this parameter an array of all hostnames for which password saving is disabled.

Requires Gecko 1.9.1 (Firefox 3.5 / Thunderbird 3.0 / SeaMonkey 2.0)

getAllEncryptedLogins()

Fetch all logins in the login manager. An array is always returned; if there are no logins the array is empty. This does not decrypt logins before returning the array.

void getAllEncryptedLogins(
  out unsigned long count, Optional
  [retval, array, size_is(count)] out nsILoginInfo logins
);
Parameters
count Optional
The number of elements in the array.
logins
An array of nsILoginInfo objects.

getAllLogins()

Implement this method to return a list of all logins in the login store.

void getAllLogins(
  out unsigned long count, Optional
  [retval, array, size_is(count)] out nsILoginInfo logins
);
Parameters
count Optional
Return in this parameter the number of logins returned in the logins array.
logins
Return in this parameter an array of all nsILoginInfo objects in the login store. This parameter must always be an array; if there are no logins in the login store, it must be an empty array, not null.

getLoginSavingEnabled()

Implement to report whether or not login saving has been disabled for a specific host.

boolean getLoginSavingEnabled(
  in AString aHost
);
Parameters
aHost
The hostname whose login saving status should be returned. This string will be in the origin URL format, without a pathname. For example, "http://mozilla.com".
Return value

Return true if login saving is enabled for the specified host; otherwise, return false.

init()

Implement this method to initialize the component. This is not called automatically; you must call it yourself if needed.

void init();
Parameters

None.

initWithFile()

Implement this method to initialize the component, overriding the default filename locations with those specified. This method is primarily used for unit tests and during profile migration.

void initWithFile(
  in nsIFile aInputFile,
  in nsIFile aOutputFile
);
Parameters
aInputFile
The file from which to read stored logins.
aOutputFile
The file to which to write stored logins, if not null. If this is null, use the default output file.

modifyLogin()

Implement this method to modify an existing login in the login store.

If newLoginData is specified as an nsILoginInfo object, all of the old login's properties are changed to the values from the newLoginData parameter. If newLoginData is a nsIPropertyBag, only the properties specified in the nsIPropertyBag are changed in oldLogin and its corresponding nsILoginMetaInfo.

void modifyLogin(
  in nsILoginInfo oldLogin,
  in nsISupports newLoginData
);
Parameters
oldLogin
The login to be modified.
newLoginData
The login information to replace the oldLogin with. This may be specified as either an nsILoginInfo or an nsIPropertyBag2 object.

removeAllLogins()

Implement this method to remove all logins from the login store. This is called by the browser sanitization feature when the user asks to clear all stored passwords. The user interface allows this to be done without getting each login first (which might require knowing the master password). No password should be required in order to remove all logins.

void removeAllLogins();
Parameters

None.

removeLogin()

Implement this method to remove the specified login from the login store.

Gecko 1.9.1 note
The values of any nsILoginMetaInfo properties are ignored.

void removeLogin(
  in nsILoginInfo aLogin
);
Parameters
aLogin
The login to remove from the login store. A login must match completely (except for its nsILoginMetaInfo data) to be removed.

Requires Gecko 1.9.1 (Firefox 3.5 / Thunderbird 3.0 / SeaMonkey 2.0)

searchLogins()

Implement this to search for logins in the login manager's data store, returning an array of matching logins. If there are no matching logins, return an empty array.

void searchLogins(
  out unsigned long count,
  in nsIPropertyBag matchData,
  [retval, array, size_is(count)] out nsILoginInfo logins
);
Parameters
count
The number of elements in the logins array.
matchData
The data used for the search. This does not follow the same requirements as findLogins() for those fields; wildcard matches are not specified.
logins
An array of matching nsILoginInfo objects.

setLoginSavingEnabled()

Implement this method to enable or disable login saving for the specified host. When login saving is disabled for a host, the Login Manager will not propt the user for permission to store logins for that host. Existing logins for the host should not be affected when setting this.

void setLoginSavingEnabled(
  in AString aHost,
  in boolean isEnabled
);
Parameters
aHost
The host for which to enable or disable login saving. The argument is in origin URL format, without a pathname (for example: "http://mozilla.com").
isEnabled
true if logins should be enabled for the host, or false if they should be disabled.

Remarks

For methods returning count, JavaScript callers can simply use the length property on the returned array to find out how many logins were returned in the array, for example:

var logins = pwmgr.searchLogins({}, matchData);
var numLogins = logins.length;

See also

Document Tags and Contributors

Contributors to this page: Sheppy, trevorh, Dolske, Callek
Last updated by: Sheppy,