nsISupports
Last changed in Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)Implemented by: @mozilla.org/categorymanager;1
. To use this service, use:
var categoryManager = Components.classes["@mozilla.org/categorymanager;1"] .getService(Components.interfaces.nsICategoryManager);
Method overview
string addCategoryEntry(in string aCategory, in string aEntry, in string aValue, in boolean aPersist, in boolean aReplace); |
void deleteCategory(in string aCategory); |
void deleteCategoryEntry(in string aCategory, in string aEntry, in boolean aPersist); |
nsISimpleEnumerator enumerateCategories(); |
nsISimpleEnumerator enumerateCategory(in string aCategory); |
string getCategoryEntry(in string aCategory, in string aEntry); |
Methods
addCategoryEntry()
This method sets the value for the given entry on the given category. The category and/or entry are created if they do not exist.
string addCategoryEntry( in string aCategory, in string aEntry, in string aValue, in boolean aPersist, in boolean aReplace );
Parameters
aCategory
- The name of the category being modified. ("protocol")
aEntry
- The name of the category entry being modified. ("http")
aValue
- The value for the category entry. ("moz.httprulez.1")
aPersist
- No longer supported. Category entries never persist across application sessions. You must pass
false
for this parameter. aReplace
- A flag indicating whether or not to overwrite the value of an existing category entry.
Return value
The previous value for the given category entry (if any).
Exceptions thrown
NS_ERROR_INVALID_ARG
- This error is returned if
aReplace
is false and the category entry already has a value, or ifaPersist
is true.
deleteCategory()
Delete a category and all entries.
void deleteCategory( in string aCategory );
Parameters
aCategory
- The name of the category being deleted.
deleteCategoryEntry()
Delete an entry from the category.
void deleteCategoryEntry( in string aCategory, in string aEntry, in boolean aPersist );
Parameters
aCategory
- The name of the category being modified. ("protocol")
aEntry
- The name of the category entry being deleted. ("http")
aPersist
- Ignored. Category entries never persist across sessions. You should always pass
false
for this parameter.
enumerateCategories()
Enumerate all existing categories.
nsISimpleEnumerator enumerateCategories();
Parameters
None.
Return value
A simple enumerator, each result QIs to nsISupportsCString
.
enumerateCategory()
Enumerate the entries in a category.
nsISimpleEnumerator enumerateCategory( in string aCategory );
Parameters
aCategory
- The category to be enumerated.
Return value
A simple enumerator, each result QIs to nsISupportsCString
.
getCategoryEntry()
Get the value for the given category's entry.
string getCategoryEntry( in string aCategory, in string aEntry );
Parameters
aCategory
- The category being queried. ("protocol")
aEntry
- The entry being queried. ("http")
Return value
The value of the given category's entry. This pointer must be released using nsIMemory.free()
when it is no longer needed.
Exceptions thrown
NS_ERROR_NOT_AVAILABLE
- Indicates that either the category or entry is undefined.
Examples
Print out a list of all categories
This snippet shows how to print out a list of all categories in C++.
nsresult PrintAllCategories() { nsresult rv; nsCOMPtr<nsIServiceManager> svcMgr; rv = NS_GetServiceManager(getter_AddRefs(svcMgr)); if (NS_FAILED(rv)) return rv; nsCOMPtr<nsICategoryManager> catMgr; rv = svcMgr->GetServiceByContractID(NS_CATEGORYMANAGER_CONTRACTID, NS_GET_IID(nsICategoryManager), getter_AddRefs(catMgr)); if (NS_FAILED(rv)) return rv; nsCOMPtr<nsISimpleEnumerator> cats; rv = catMgr->EnumerateCategories(getter_AddRefs(cats)); if (NS_FAILED(rv)) return rv; PRBool hasMore; while (NS_SUCCEEDED(cats->HasMoreElements(&hasMore) && hasMore) { nsCOMPtr<nsISupports> elem; cats->GetNext(getter_AddRefs(elem)); nsCOMPtr<nsISupportsCString> category = do_QueryInterface(elem, &rv); if (NS_FAILED(rv)) break; nsEmbedCString categoryName; rv = category->GetData(categoryName); if (NS_FAILED(rv)) break; printf("%s\n", categoryName.get()); } return NS_OK; }
This snippet shows how to print out a list of all categories in Javascript.
var categoryManager = Components.classes["@mozilla.org/categorymanager;1"] .getService(Components.interfaces.nsICategoryManager); var enumerator = categoryManager.enumerateCategories(); var categories = []; while (enumerator.hasMoreElements()) { var item = enumerator.getNext(); var category = item.QueryInterface(Components.interfaces.nsISupportsCString) categories.push(category.toString()); } categories.sort(); var categoriesString = categories.join("\n"); dump(categoriesString + "\n");
Print out a list of app-startup
entries
This example prints out a list of entries of "app-startup" category.
var categoryManager = Components.classes["@mozilla.org/categorymanager;1"] .getService(Components.interfaces.nsICategoryManager); var enumerator = categoryManager.enumerateCategory("app-startup"); var entries = []; while (enumerator.hasMoreElements()) { var item = enumerator.getNext(); var entry = item.QueryInterface(Components.interfaces.nsISupportsCString) entries.push(entry.toString()); } entries.sort(); var entriesString = entries.join("\n"); dump(entriesString + "\n");
Disable currently loaded plugins by type
This snippet here shows how to disable plugins that are currently loaded for the file type of PDF. The second portion of this snippet disables plugins from loading in the future, it does not user the category manager but it is included for completness of the example.
var CONTENT_TYPE = 'application/pdf'; // Update the category manager in case the plugins are already loaded. let categoryManager = Cc['@mozilla.org/categorymanager;1']; categoryManager.getService(Ci.nsICategoryManager).deleteCategoryEntry('Gecko-Content-Viewers', CONTENT_TYPE, false); // Update pref manager to prevent plugins from loading in future var stringTypes = ''; var types = []; var PREF_DISABLED_PLUGIN_TYPES = 'plugin.disable_full_page_plugin_for_types'; if (Services.prefs.prefHasUserValue(PREF_DISABLED_PLUGIN_TYPES)) { stringTypes = Services.prefs.getCharPref(PREF_DISABLED_PLUGIN_TYPES); } if (stringTypes !== '') { types = stringTypes.split(','); } if (types.indexOf(CONTENT_TYPE) === -1) { types.push(CONTENT_TYPE); } Services.prefs.setCharPref(PREF_DISABLED_PLUGIN_TYPES, types.join(','));
Remarks
Categories have a variety of uses throughout the Mozilla platform. They are often used to register lists of ContractIDs, corresponding to components that wish to be notified of various events by some subsystem.