The Tor Browser: comparison addon-sdk/source/lib/sdk/platform/xpcom.js

comparison: addon-sdk/source/lib/sdk/platform/xpcom.js

addon-sdk/source/lib/sdk/platform/xpcom.js

changeset 0: 6474c204b198

equal deleted inserted replaced

--1:000000000000
+:3205cc95f780
+/* This Source Code Form is subject to the terms of the Mozilla Public
+* License, v. 2.0. If a copy of the MPL was not distributed with this
+* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+"use strict";
+module.metadata = {
+"stability": "unstable"
+};
+const { Cc, Ci, Cr, Cm, components: { classesByID } } = require('chrome');
+const { registerFactory, unregisterFactory, isCIDRegistered } =
+Cm.QueryInterface(Ci.nsIComponentRegistrar);
+const { merge } = require('../util/object');
+const { Class, extend, mix } = require('../core/heritage');
+const { uuid } = require('../util/uuid');
+// This is a base prototype, that provides bare bones of XPCOM. JS based
+// components can be easily implement by extending it.
+const Unknown = new function() {
+function hasInterface(component, iid) {
+return component && component.interfaces &&
+( component.interfaces.some(function(id) iid.equals(Ci[id])) ||
+component.implements.some(function($) hasInterface($, iid)) ||
+hasInterface(Object.getPrototypeOf(component), iid));
+}
+return Class({
+/**
+* The `QueryInterface` method provides runtime type discovery used by XPCOM.
+* This method return queried instance of `this` if given `iid` is listed in
+* the `interfaces` property or in equivalent properties of objects in it's
+* prototype chain. In addition it will look up in the prototypes under
+* `implements` array property, this ways compositions made via `Class`
+* utility will carry interfaces implemented by composition components.
+*/
+QueryInterface: function QueryInterface(iid) {
+// For some reason there are cases when `iid` is `null`. In such cases we
+// just return `this`. Otherwise we verify that component implements given
+// `iid` interface. This will be no longer necessary once Bug 748003 is
+// fixed.
+if (iid && !hasInterface(this, iid))
+throw Cr.NS_ERROR_NO_INTERFACE;
+return this;
+},
+/**
+* Array of `XPCOM` interfaces (as strings) implemented by this component.
+* All components implement `nsISupports` by default which is default value
+* here. Provide array of interfaces implemented by an object when
+* extending, to append them to this list (Please note that there is no
+* need to repeat interfaces implemented by super as they will be added
+* automatically).
+*/
+interfaces: Object.freeze([ 'nsISupports' ])
+});
+}
+exports.Unknown = Unknown;
+// Base exemplar for creating instances implementing `nsIFactory` interface,
+// that maybe registered into runtime via `register` function. Instances of
+// this factory create instances of enclosed component on `createInstance`.
+const Factory = Class({
+extends: Unknown,
+interfaces: [ 'nsIFactory' ],
+/**
+* All the descendants will get auto generated `id` (also known as `classID`
+* in XPCOM world) unless one is manually provided.
+*/
+get id() { throw Error('Factory must implement `id` property') },
+/**
+* XPCOM `contractID` may optionally  be provided to associate this factory
+* with it. `contract` is a unique string that has a following format:
+* '@vendor.com/unique/id;1'.
+*/
+contract: null,
+/**
+* Class description that is being registered. This value is intended as a
+* human-readable description for the given class and does not needs to be
+* globally unique.
+*/
+description: 'Jetpack generated factory',
+/**
+* This method is required by `nsIFactory` interfaces, but as in most
+* implementations it does nothing interesting.
+*/
+lockFactory: function lockFactory(lock) undefined,
+/**
+* If property is `true` XPCOM service / factory will be registered
+* automatically on creation.
+*/
+register: true,
+/**
+* If property is `true` XPCOM factory will be unregistered prior to add-on
+* unload.
+*/
+unregister: true,
+/**
+* Method is called on `Service.new(options)` passing given `options` to
+* it. Options is expected to have `component` property holding XPCOM
+* component implementation typically decedent of `Unknown` or any custom
+* implementation with a `new` method and optional `register`, `unregister`
+* flags. Unless `register` is `false` Service / Factory will be
+* automatically registered. Unless `unregister` is `false` component will
+* be automatically unregistered on add-on unload.
+*/
+initialize: function initialize(options) {
+merge(this, {
+id: 'id' in options ? options.id : uuid(),
+register: 'register' in options ? options.register : this.register,
+unregister: 'unregister' in options ? options.unregister : this.unregister,
+contract: 'contract' in options ? options.contract : null,
+Component: options.Component
+});
+// If service / factory has auto registration enabled then register.
+if (this.register)
+register(this);
+},
+/**
+* Creates an instance of the class associated with this factory.
+*/
+createInstance: function createInstance(outer, iid) {
+try {
+if (outer)
+throw Cr.NS_ERROR_NO_AGGREGATION;
+return this.create().QueryInterface(iid);
+}
+catch (error) {
+throw error instanceof Ci.nsIException ? error : Cr.NS_ERROR_FAILURE;
+}
+},
+create: function create() this.Component()
+});
+exports.Factory = Factory;
+// Exemplar for creating services that implement `nsIFactory` interface, that
+// can be registered into runtime via call to `register`. This services return
+// enclosed `component` on `getService`.
+const Service = Class({
+extends: Factory,
+initialize: function initialize(options) {
+this.component = options.Component();
+Factory.prototype.initialize.call(this, options);
+},
+description: 'Jetpack generated service',
+/**
+* Creates an instance of the class associated with this factory.
+*/
+create: function create() this.component
+});
+exports.Service = Service;
+function isRegistered({ id }) isCIDRegistered(id)
+exports.isRegistered = isRegistered;
+/**
+* Registers given `component` object to be used to instantiate a particular
+* class identified by `component.id`, and creates an association of class
+* name and `component.contract` with the class.
+*/
+function register(factory) {
+if (!(factory instanceof Factory)) {
+throw new Error("xpcom.register() expect a Factory instance.\n" +
+"Please refactor your code to new xpcom module if you" +
+" are repacking an addon from SDK <= 1.5:\n" +
+"https://addons.mozilla.org/en-US/developers/docs/sdk/latest/packages/api-utils/xpcom.html");
+}
+registerFactory(factory.id, factory.description, factory.contract, factory);
+if (factory.unregister)
+require('../system/unload').when(unregister.bind(null, factory));
+}
+exports.register = register;
+/**
+* Unregister a factory associated with a particular class identified by
+* `factory.classID`.
+*/
+function unregister(factory) {
+if (isRegistered(factory))
+unregisterFactory(factory.id, factory);
+}
+exports.unregister = unregister;
+function autoRegister(path) {
+// TODO: This assumes that the url points to a directory
+// that contains subdirectories corresponding to OS/ABI and then
+// further subdirectories corresponding to Gecko platform version.
+// we should probably either behave intelligently here or allow
+// the caller to pass-in more options if e.g. there aren't
+// Gecko-specific binaries for a component (which will be the case
+// if only frozen interfaces are used).
+var runtime = require("../system/runtime");
+var osDirName = runtime.OS + "_" + runtime.XPCOMABI;
+var platformVersion = require("../system/xul-app").platformVersion.substring(0, 5);
+var file = Cc['@mozilla.org/file/local;1']
+.createInstance(Ci.nsILocalFile);
+file.initWithPath(path);
+file.append(osDirName);
+file.append(platformVersion);
+if (!(file.exists() && file.isDirectory()))
+throw new Error("component not available for OS/ABI " +
+osDirName + " and platform " + platformVersion);
+Cm.QueryInterface(Ci.nsIComponentRegistrar);
+Cm.autoRegister(file);
+}
+exports.autoRegister = autoRegister;
+/**
+* Returns registered factory that has a given `id` or `null` if not found.
+*/
+function factoryByID(id) classesByID[id] || null
+exports.factoryByID = factoryByID;
+/**
+* Returns factory registered with a given `contract` or `null` if not found.
+* In contrast to `Cc[contract]` that does ignores new factory registration
+* with a given `contract` this will return a factory currently associated
+* with a `contract`.
+*/
+function factoryByContract(contract) factoryByID(Cm.contractIDToCID(contract))
+exports.factoryByContract = factoryByContract;