#include "nsISupports.idl" interface nsILocalFile; interface nsIObserver; interface nsIURI; interface nsIArray; /** * This interface gives you access to see and change the configuration of a user * script. */ [scriptable, uuid(b8d38931-1fe8-4de3-91e6-45d8475d0d84)] interface gmIUserScript : nsISupports { // TODO: Document these readonly attribute AString id; // namespace + name readonly attribute boolean installed; readonly attribute nsILocalFile file; readonly attribute AString name; readonly attribute AString namespace; attribute AString description; attribute boolean enabled; readonly attribute unsigned long includeCount; AString getInclude(in unsigned long index); void addInclude(in AString url); void removeInclude(in AString url); readonly attribute unsigned long excludeCount; AString gedExclude(in unsigned long index); void addExclude(in AString url); void removeExclude(in AString url); /** * The number of dependencies for this user script. */ readonly attribute long dependencyCount; /** * Get a dependency by its index. Dependencies are indexed from zero to * dependencyCount - 1. * * @param index Index of a dependency. * @return TODO I have no idea what type this method should return. using a string for now. */ AString getDependency(in unsigned long index); /** * Chack if this user script will overwrite another user script when it is * installed. Only applicable on scripts where the installed attribute is * false. * * @return True if this user script will overwrite another user script upon * install, false otherwise. */ boolean willOverwriteOnInstall(); /** * Begin an update batch. * * When you do multiple changes to a user script in one go, you can call * beginUpdateBatch(), make your changes and call endUpdateBatch() to avoid * multible notifications and file writes. You must always do your changes * and call endUpdateBatch() immediately after you call beginUpdateBatch(). * Example: You cannot wait for user interaction when you are in the middle * of an update batch. */ void beginUpdateBatch(); /** * End an update batch started by beginUpdateBatch(). */ void endUpdateBatch(); }; /** * This interface allows you to install and uninstall user scripts, change * their configuration and get notifications of any changes made. */ [scriptable, uuid(5598eeb7-660a-444c-b25d-17c832da8cd8)] interface gmIUserScriptService : nsISupports { /** * The number of installed user scripts. */ readonly attribute unsigned long userScriptCount; /** * Get a user script by its index. User scripts are indexed from zero to * userScriptCount - 1. * * @param index Index of a user script. * @return The user script at the given index. Or null if the index is out * of bounds. */ gmIUserScript getUserScript(in unsigned long index); /** * Parse a new user script from it's source. This will not install the user * script. To install the user script, call installUserScript() with the * return value of this method as parameter. To abort the installation * process, just don't call installUserScript(). * * @param source The source file of the user script, including the * configuration section. * @param uri The URI from where the user script was downloaded. If the user * script was not downloaded, this parameter should be null. * @return A not yet installed user script generated from the given source. */ gmIUserScript parseUserScript(in AString source, in nsIURI uri); /** * Install a new user script. If a user script with the same ID is already * installed, it will be overwritten. You may use * gmIUserScript.willOverwriteOnInstall() to check for this case before * installing the user script. Before you install a user script, you must * make sure that all dependencies are installed. This is not done * automatically. * * @param The user script to install. */ void installUserScript(in gmIUserScript userScript); /** * Uninstall an installed user script. This will also remove the script * file from disc. * * @param userScript The user script to be uninstalled. * @param uninstallPrefs If this is true, all associated preferences will * be removed too. */ void uninstallUserScript(in gmIUserScript userScript, in boolean uninstallPrefs); /** * Move a user script to a new position in the installed user script list. * * If you try to move a user script outside the boundaries of the list, the * user script will just be moved to the beginning or end of the list * depending on what boundary you exceeded. * * @param userScript The user script to move. * @param offset The distance to move. The new index of the user script will * be the existing index plus this value. */ void moveUserScript(in gmIUserScript userScript, in unsigned long offset); /** * Get a list of installed user scripts which will run on the given URL. The * URL will be compared to the user script's included and excluded pages * lists. Both enabled and disabled user scripts are returned. * * TODO find better collection interface for return type * * @param url The page url used to compare. * @return List of matching user scripts. */ nsIArray getScriptsForUrl(in AString url); /** * TODO I am not sure if this is how observers in XPCOM are supposed to work. * * Register a new observer. * * Whenever something is changed, observers are notified by calling: * * observer.observe(, , ); * * Values of : * "add": has been installed and added to the end of the * installed user script list. * "remove": has been uninstalled and removed from the * installed user script list. * "edit": One or more properties of has been changed. * This can be the description, enabled status, includes and * excludes. * "move": has been moved from its current position to the * position with index in the installed user script list. * * @param observer The observer to be added. */ void addObserver(in nsIObserver observer); /** * Unregister an existing observer. See addObserver for more details. * * @param observer The observer to be removed. */ void removeObserver(in nsIObserver observer); };