nsICategoryManager

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

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 if aPersist 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.