gecko/dom/bindings/Bindings.conf

# 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/.

# DOM Bindings Configuration.
#
# The WebIDL interfaces are defined in dom/webidl. For each such interface, there
# is a corresponding entry in the configuration table below. The configuration
# table maps each interface name to a |descriptor| or list of |descriptor|s.
#
# Valid fields for all descriptors:
#   * nativeType - The native type (concrete class or XPCOM interface) that
#                  instances of this interface will unwrap to.  If not
#                  specified, defaults to "mozilla::dom::InterfaceName" for
#                  non-worker non-external-or-callback interfaces, to
#                  "mozilla::dom::workers::InterfaceName" for worker
#                  non-external interfaces, to 'nsIDOM' followed by the
#                  interface name for non-worker external-or-callback
#                  interfaces, and to "JSObject" for worker external-or-callback
#                  interfaces.
#   * headerFile - The file in which the nativeType is declared (defaults
#                  to an educated guess).
#   * castable - Indicates whether the value in the wrapper can be cast to
#                nativeType, or whether it needs to be QI-ed (defaults to True
#                for everything but callback interfaces and external interfaces,
#                for which it defaults to false and is not allowed to be set
#                at all).
#   * concrete - Indicates whether there exist objects with this interface as
#                their primary interface.  Always False for callback interfaces.
#                defaults to True otherwise.
#   * prefable - Indicates whether this bindings should be disabled if the
#                global pref for Web IDL bindings is set to false.  This is a
#                risk mitigation strategy and it will cause all of the Web IDL
#                bindings marked as prefable to fall back to the xpconnect
#                bindings in case something goes wrong.  This defaults to False.
#                Setting this on objects which only have Web IDL bindings does
#                not make any sense.
#                Cannot be set on external interfaces.
#   * workers - Indicates whether the descriptor is intended to be used for
#               worker threads (defaults to false).
#   * customTrace - The native class will use a custom trace hook (defaults to
#                   true for workers, false otherwise).
#   * customFinalize - The native class will use a custom finalize hook
#                      (defaults to true for workers, false otherwise).
#   * notflattened - The native type does not have nsIClassInfo, so when
#                    wrapping it the right IID needs to be passed in.
#   * register - True if this binding should be registered.  Defaults to true.
#   * binaryNames - Dict for mapping method and attribute names to different
#                   names when calling the native methods (defaults to an empty
#                   dict). The keys are the property names as they appear in the
#                   .webidl file and the values are the names as they should be
#                   in the WebIDL.
#   * wrapperCache: True if this object is a wrapper cache.  Objects that are
#                   not can only be returned from a limited set of methods,
#                   cannot be prefable, and must ensure that they disallow
#                   XPConnect wrapping.  Always false for callback interfaces.
#                   Always true for worker descriptors for non-callback
#                   interfaces.  Defaults to true for non-worker non-callback
#                   descriptors.
#   * nativeOwnership: Describes how the native object is held. 4 possible
#                      types: worker object ("worker"), non-refcounted object
#                      ("owned"), refcounted non-nsISupports object
#                      ("refcounted") or nsISupports ("nsisupports").
#                      Non-refcounted objects need to inherit from
#                      mozilla::dom::NonRefcountedDOMObject and preferably use
#                      MOZ_COUNT_CTOR/MOZ_COUNT_DTOR in their
#                      constructor/destructor so they participate in leak
#                      logging.
#                      This mostly determines how the finalizer releases the
#                      binding's hold on the native object. For a worker object
#                      it'll call Release, for a non-refcounted object it'll
#                      call delete through XPConnect's deferred finalization
#                      mechanism, for a refcounted object it'll call Release
#                      through XPConnect's deferred finalization mechanism.
#                      Always "worker" for worker descriptors. Defaults to
#                      "nsisupports".
#
#   The following fields are either a string, an array (defaults to an empty
#   array) or a dictionary with three possible keys (all, getterOnly and
#   setterOnly) each having such an array as the value
#
#   * implicitJSContext - attributes and methods specified in the .webidl file
#                         that require a JSContext as the first argument
#   * resultNotAddRefed - attributes and methods specified in the .webidl file
#                         that do not AddRef the return value
#
# A descriptor can also have 'skipGen': True specified if it should be skipped
# when deciding what header includes to generate and should never have an
# implementation generated for it.  This is only needed in special cases like
# worker descriptors for objects that will never actually appear in workers.

DOMInterfaces = {

'mozAudioContext': {
    'nativeType': 'AudioContext',
    'implicitJSContext': [ 'createBuffer' ],
    'nativeOwnership': 'refcounted',
    'resultNotAddRefed': [ 'destination', 'listener' ],
},

'AudioListener' : {
    'nativeOwnership': 'refcounted'
},

'AudioNode' : {
    'concrete': False,
},

'AudioParam' : {
    'nativeOwnership': 'refcounted'
},

'AudioSourceNode': {
    'concrete': False,
},

'BiquadFilterNode': {
    'resultNotAddRefed': [ 'frequency', 'q', 'gain' ],
},

'Blob': [
{
    'headerFile': 'nsIDOMFile.h',
},
{
    'workers': True,
}],

'CanvasRenderingContext2D': {
    'implicitJSContext': [
        'createImageData', 'getImageData', 'strokeStyle',
        'fillStyle', 'mozDash'
    ],
    'resultNotAddRefed': [ 'canvas' ],
    'binaryNames': {
        'mozImageSmoothingEnabled': 'imageSmoothingEnabled',
        'mozFillRule': 'fillRule'
    }
},

'ClientRectList': {
    'nativeType': 'nsClientRectList',
    'headerFile': 'nsClientRect.h',
    'resultNotAddRefed': [ 'item' ]
},

'CSS2Properties': {
  'nativeType': 'nsDOMCSSDeclaration'
},

'CSSStyleDeclaration': {
  'nativeType': 'nsICSSDeclaration'
},

'DelayNode': [
{
    'resultNotAddRefed': [ 'delayTime' ],
}],

'Document': [
{
    'nativeType': 'nsIDocument',
},
{
    'nativeType': 'JSObject',
    'workers': True,
    'skipGen': True
}],

'DOMSettableTokenList': {
    'nativeType': 'nsDOMSettableTokenList',
    'binaryNames': {
        '__stringifier': 'Stringify'
    }
},

'DOMStringMap': {
    'nativeType': 'nsDOMStringMap'
},

'DOMTokenList': {
    'nativeType': 'nsDOMTokenList',
    'binaryNames': {
        '__stringifier': 'Stringify'
    }
},

'DynamicsCompressorNode': [
{
    'resultNotAddRefed': [ 'threshold', 'knee', 'ratio',
                           'reduction', 'attack', 'release' ],
    'binaryNames': {
        'release': 'getRelease'
    }
}],

'Element': {
    # 'prefable' is True because some nodes are not on new bindings yet, so the
    # wrapping code for Element return values needs to fall back to XPConnect as
    # needed.
    'prefable': True,
    'hasXPConnectImpls': True,
    'hasInstanceInterface': 'nsIDOMElement',
    'resultNotAddRefed': [
        'classList', 'attributes', 'children', 'firstElementChild',
        'lastElementChild', 'previousElementSibling', 'nextElementSibling',
        'getAttributeNode', 'getAttributeNodeNS'
    ]
},

'Event': [
{
    'workers': True,
}],

'EventListener': [
{
    'workers': True,
}],

'EventTarget': [
{
    'nativeType': 'nsDOMEventTargetHelper',
    'hasInstanceInterface': 'nsIDOMEventTarget',
    'concrete': False,
    'prefable': True,
},
{
    'workers': True,
    'concrete': False
}],

'FileList': {
    'nativeType': 'nsDOMFileList',
    'headerFile': 'nsDOMFile.h',
    'resultNotAddRefed': [ 'item' ]
},

'FileReaderSync': {
    'workers': True,
},

'FormData': [
{
    'workers': True,
}],

'GainNode': [
{
    'resultNotAddRefed': [ 'gain' ],
}],

'HTMLCollection': {
    'nativeType': 'nsIHTMLCollection',
    'resultNotAddRefed': [ 'item' ]
},

'HTMLOptionsCollection': {
    'nativeType': 'nsHTMLOptionCollection',
    'headerFile': 'nsHTMLSelectElement.h',
    'resultNotAddRefed': [ 'item' ],
    'binaryNames': {
        '__indexedsettercreator': 'SetOption'
    }
},

'HTMLPropertiesCollection': {
    'headerFile': 'HTMLPropertiesCollection.h',
    'resultNotAddRefed': [ 'item', 'namedItem', 'names' ]
},

'IID': [
{
    'nativeType': 'nsIJSID',
    'headerFile': 'xpcjsid.h',
},
{
    'workers': True,
}],

'ImageData': {
   'wrapperCache': False
},

'InputStream': [
{
    'nativeType': 'nsIInputStream',
    'notflattened': True
},
{
    'workers': True,
}],

'MediaStreamList': {
    'headerFile': 'MediaStreamList.h',
    'wrapperCache': False,
    'nativeOwnership': 'owned',
    'resultNotAddRefed': [ '__indexedGetter' ],
    'binaryNames': { '__indexedGetter': 'IndexedGetter' }
},

'MozChannel': [
{
    'nativeType': 'nsIChannel',
    'notflattened': True
},
{
    'workers': True,
}],

'Node': {
    'nativeType': 'nsINode',
    # 'prefable' is True because some nodes are not on new bindings yet, so the
    # wrapping code for Node return values needs to fall back to XPConnect as
    # needed.
    'prefable': True,
    # 'castable' is False because we don't support prefable castable arguments
    # and we have Node arguments.
    'castable': False,
    'hasXPConnectImpls': True,
    'hasInstanceInterface': 'nsIDOMNode',
    'resultNotAddRefed': [ 'ownerDocument', 'parentNode', 'parentElement',
                           'childNodes', 'firstChild', 'lastChild',
                           'previousSibling', 'nextSibling', 'insertBefore',
                           'appendChild', 'replaceChild', 'removeChild',
                           'attributes' ]
},

'NodeList': {
    'nativeType': 'nsINodeList',
    'resultNotAddRefed': [ 'item' ]
},

'PaintRequestList': {
    'nativeType': 'nsPaintRequestList',
    'headerFile': 'nsPaintRequest.h',
    'resultNotAddRefed': [ 'item' ]
},

'PannerNode': [
{
    'resultNotAddRefed': [ 'coneGain', 'distanceGain' ],
}],

'Performance': {
    'nativeType': 'nsPerformance',
    'resultNotAddRefed': [ 'timing', 'navigation' ]
},

'PerformanceTiming': {
    'nativeType': 'nsPerformanceTiming',
    'headerFile': 'nsPerformance.h'
},

'PerformanceNavigation': {
    'nativeType': 'nsPerformanceNavigation',
    'headerFile': 'nsPerformance.h'
},

'PropertyNodeList': {
    'headerFile': 'HTMLPropertiesCollection.h',
    'resultNotAddRefed': [ 'item' ]
},

'Screen': {
    'nativeType': 'nsScreen',
    'prefable': True,
},

'SVGLengthList': {
    'nativeType': 'mozilla::DOMSVGLengthList',
    'headerFile': 'DOMSVGLengthList.h',
    'resultNotAddRefed': [ 'getItem' ]
},

'SVGNumberList': {
    'nativeType': 'mozilla::DOMSVGNumberList',
    'headerFile': 'DOMSVGNumberList.h',
    'resultNotAddRefed': [ 'getItem' ]
},

'SVGPathSegList': {
    'nativeType': 'mozilla::DOMSVGPathSegList',
    'headerFile': 'DOMSVGPathSegList.h',
    'resultNotAddRefed': [ 'getItem' ]
},

'SVGPointList': {
    'nativeType': 'mozilla::DOMSVGPointList',
    'headerFile': 'DOMSVGPointList.h',
    'resultNotAddRefed': [ 'getItem' ]
},

'SVGTransformList': {
    'nativeType': 'mozilla::DOMSVGTransformList',
    'headerFile': 'DOMSVGTransformList.h',
    'resultNotAddRefed': [ 'getItem' ]
},

'TextEncoder': {
    'implicitJSContext': [ 'encode' ],
},

'URL' : {
    'concrete': False,
},

'WebGLActiveInfo': {
   'nativeType': 'mozilla::WebGLActiveInfo',
   'headerFile': 'WebGLContext.h',
   'wrapperCache': False
},

'WebGLBuffer': {
   'nativeType': 'mozilla::WebGLBuffer',
   'headerFile': 'WebGLContext.h'
},

'WebGLExtensionCompressedTextureATC': {
   'nativeType': 'mozilla::WebGLExtensionCompressedTextureATC',
   'headerFile': 'WebGLExtensions.h'
},

'WebGLExtensionCompressedTexturePVRTC': {
   'nativeType': 'mozilla::WebGLExtensionCompressedTexturePVRTC',
   'headerFile': 'WebGLExtensions.h'
},

'WebGLExtensionCompressedTextureS3TC': {
   'nativeType': 'mozilla::WebGLExtensionCompressedTextureS3TC',
   'headerFile': 'WebGLExtensions.h'
},

'WebGLExtensionDepthTexture': {
   'nativeType': 'mozilla::WebGLExtensionDepthTexture',
   'headerFile': 'WebGLExtensions.h'
},

'WebGLExtensionDebugRendererInfo': {
   'nativeType': 'mozilla::WebGLExtensionDebugRendererInfo',
   'headerFile': 'WebGLExtensions.h'
},

'WebGLExtensionLoseContext': {
   'nativeType': 'mozilla::WebGLExtensionLoseContext',
   'headerFile': 'WebGLExtensions.h'
},

'WebGLExtensionStandardDerivatives': {
   'nativeType': 'mozilla::WebGLExtensionStandardDerivatives',
   'headerFile': 'WebGLExtensions.h'
},

'WebGLExtensionTextureFilterAnisotropic': {
   'nativeType': 'mozilla::WebGLExtensionTextureFilterAnisotropic',
   'headerFile': 'WebGLExtensions.h'
},

'WebGLExtensionTextureFloat': {
   'nativeType': 'mozilla::WebGLExtensionTextureFloat',
   'headerFile': 'WebGLExtensions.h'
},

'WebGLFramebuffer': {
   'nativeType': 'mozilla::WebGLFramebuffer',
   'headerFile': 'WebGLContext.h'
},

'WebGLProgram': {
   'nativeType': 'mozilla::WebGLProgram',
   'headerFile': 'WebGLContext.h'
},

'WebGLRenderbuffer': {
   'nativeType': 'mozilla::WebGLRenderbuffer',
   'headerFile': 'WebGLContext.h'
},

'WebGLRenderingContext': {
  'nativeType': 'mozilla::WebGLContext',
  'headerFile': 'WebGLContext.h',
  'resultNotAddRefed': [ 'canvas', 'getContextAttributes', 'getExtension',
                         'getAttachedShaders' ],
  'implicitJSContext': [ 'getSupportedExtensions' ],
},

'WebGLShader': {
   'nativeType': 'mozilla::WebGLShader',
   'headerFile': 'WebGLContext.h'
},

'WebGLShaderPrecisionFormat': {
   'nativeType': 'mozilla::WebGLShaderPrecisionFormat',
   'headerFile': 'WebGLContext.h',
   'wrapperCache': False
},

'WebGLTexture': {
   'nativeType': 'mozilla::WebGLTexture',
   'headerFile': 'WebGLContext.h'
},

'WebGLUniformLocation': {
   'nativeType': 'mozilla::WebGLUniformLocation',
   'headerFile': 'WebGLContext.h',
   'wrapperCache': False
},

'WebSocket': {
    'headerFile': 'WebSocket.h',
    'implicitJSContext': [ 'constructor' ]
},

'XMLHttpRequest': [
{
    'nativeType': 'nsXMLHttpRequest',
    'implicitJSContext': [ 'constructor', ],
    'resultNotAddRefed': [ 'upload', 'responseXML' ]
},
{
    'workers': True,
}],

'XMLHttpRequestEventTarget': [
{
    'nativeType': 'nsXHREventTarget',
    'headerFile': 'nsXMLHttpRequest.h',
    'concrete': False
},
{
    'workers': True,
    'concrete': False,
}],

'XMLHttpRequestUpload': [
{
    'nativeType': 'nsXMLHttpRequestUpload',
    'headerFile': 'nsXMLHttpRequest.h'
},
{
    'workers': True,
}],

####################################
# Test Interfaces of various sorts #
####################################

'TestInterface' : {
        # Keep this in sync with TestExampleInterface
        'headerFile': 'TestBindingHeader.h',
        'register': False,
        'resultNotAddRefed': [ 'receiveWeakSelf', 'receiveWeakNullableSelf',
                               'receiveWeakOther', 'receiveWeakNullableOther',
                               'receiveWeakExternal', 'receiveWeakNullableExternal',
                               'ReceiveWeakCallbackInterface',
                               'ReceiveWeakNullableCallbackInterface',
                               'receiveWeakCastableObjectSequence',
                               'receiveWeakNullableCastableObjectSequence',
                               'receiveWeakCastableObjectNullableSequence',
                               'receiveWeakNullableCastableObjectNullableSequence' ],
        'binaryNames': { 'methodRenamedFrom': 'methodRenamedTo',
                         'attributeGetterRenamedFrom': 'attributeGetterRenamedTo',
                         'attributeRenamedFrom': 'attributeRenamedTo',
                         '__stringifier' : 'Stringify' }
        },

'TestNonCastableInterface' : {
        'headerFile': 'TestBindingHeader.h',
        'register': False,
        'castable': False
        },

'TestExternalInterface' : {
        'nativeType': 'mozilla::dom::TestExternalInterface',
        'headerFile': 'TestBindingHeader.h',
        'register': False
        },

'TestNonWrapperCacheInterface' : {
        'headerFile': 'TestBindingHeader.h',
        'register': False,
        'wrapperCache': False
        },

'TestCallbackInterface': {
        'nativeType': 'mozilla::dom::TestCallbackInterface',
        'headerFile': 'TestBindingHeader.h',
        'register': False
        },

'IndirectlyImplementedInterface': {
        'headerFile': 'TestBindingHeader.h',
        'register': False,
        'castable': False,
        'concrete': False
        },

'OnlyForUseInConstructor' : {
        'headerFile': 'TestBindingHeader.h',
        'register': False
        },


'TestIndexedGetterInterface' : {
        'headerFile': 'TestBindingHeader.h',
        'register': False
        },

'TestNamedGetterInterface' : {
        'headerFile': 'TestBindingHeader.h',
        'register': False
        },

'TestIndexedGetterAndSetterAndNamedGetterInterface' : {
        'headerFile': 'TestBindingHeader.h',
        'register': False
        },

'TestIndexedAndNamedGetterInterface' : {
        'headerFile': 'TestBindingHeader.h',
        'register': False
        },

'TestIndexedSetterInterface' : {
        'headerFile': 'TestBindingHeader.h',
        'register': False
        },

'TestNamedSetterInterface' : {
        'headerFile': 'TestBindingHeader.h',
        'register': False
        },

'TestIndexedAndNamedSetterInterface' : {
        'headerFile': 'TestBindingHeader.h',
        'register': False
        },

'TestIndexedAndNamedGetterAndSetterInterface' : {
        'headerFile': 'TestBindingHeader.h',
        'register': False,
        'binaryNames': { '__stringifier': 'Stringify' }
        },

'TestRenamedInterface' : {
        'headerFile': 'TestBindingHeader.h',
        'register': False,
        'nativeType': 'nsRenamedInterface'
        },

'TestIndexedDeleterInterface' : {
        'headerFile': 'TestBindingHeader.h',
        'register': False
        },

'TestIndexedDeleterWithRetvalInterface' : {
        'headerFile': 'TestBindingHeader.h',
        'register': False
        },

'TestNamedDeleterInterface' : {
        'headerFile': 'TestBindingHeader.h',
        'register': False
        },

'TestNamedDeleterWithRetvalInterface' : {
        'headerFile': 'TestBindingHeader.h',
        'register': False
        },

'TestIndexedAndNamedDeleterInterface' : {
        'headerFile': 'TestBindingHeader.h',
        'register': False
        },

'TestCppKeywordNamedMethodsInterface' : {
        'headerFile': 'TestBindingHeader.h',
        'register': False
        },

'TestExampleInterface' : {
        # Keep this in sync with TestInterface
        'headerFile': 'TestExampleInterface-example.h',
        'register': False,
        'resultNotAddRefed': [ 'receiveWeakSelf', 'receiveWeakNullableSelf',
                               'receiveWeakOther', 'receiveWeakNullableOther',
                               'receiveWeakExternal', 'receiveWeakNullableExternal',
                               'ReceiveWeakCallbackInterface',
                               'ReceiveWeakNullableCallbackInterface',
                               'receiveWeakCastableObjectSequence',
                               'receiveWeakNullableCastableObjectSequence',
                               'receiveWeakCastableObjectNullableSequence',
                               'receiveWeakNullableCastableObjectNullableSequence' ],
        'binaryNames': { 'methodRenamedFrom': 'methodRenamedTo',
                         'attributeGetterRenamedFrom': 'attributeGetterRenamedTo',
                         'attributeRenamedFrom': 'attributeRenamedTo' }
        },

'TestExampleProxyInterface' : {
        'headerFile': 'TestExampleProxyInterface-example.h',
	'register': False
        }
}

# These are temporary, until they've been converted to use new DOM bindings
def addExternalIface(iface, nativeType=None, headerFile=None,
                     notflattened=False):
    if iface in DOMInterfaces:
        raise Exception('Interface declared both as WebIDL and External interface')
    domInterface = {
        'concrete': False
    }
    if not nativeType is None:
        domInterface['nativeType'] = nativeType
    if not headerFile is None:
        domInterface['headerFile'] = headerFile
    domInterface['notflattened'] = notflattened
    DOMInterfaces[iface] = domInterface

# If you add one of these, you need to make sure nsDOMQS.h has the relevant
# macros added for it
def addExternalHTMLElement(element):
   nativeElement = 'ns' + element
   addExternalIface(element, nativeType=nativeElement,
                    headerFile=nativeElement + '.h')

addExternalHTMLElement('HTMLCanvasElement')
addExternalHTMLElement('HTMLImageElement')
addExternalHTMLElement('HTMLOptionElement')
addExternalHTMLElement('HTMLOptGroupElement')
addExternalHTMLElement('HTMLVideoElement')
addExternalIface('Attr')
addExternalIface('CanvasGradient', headerFile='nsIDOMCanvasRenderingContext2D.h')
addExternalIface('CanvasPattern', headerFile='nsIDOMCanvasRenderingContext2D.h')
addExternalIface('ClientRect')
addExternalIface('CSSRule')
addExternalIface('CSSValue')
addExternalIface('DocumentType', nativeType='nsIDOMDocumentType')
addExternalIface('DOMStringList', nativeType='nsDOMStringList',
                 headerFile='nsDOMLists.h')
addExternalIface('File')
addExternalIface('HitRegionOptions', nativeType='nsISupports')
addExternalIface('HTMLElement')
addExternalIface('MediaStream')
addExternalIface('NamedNodeMap')
addExternalIface('PaintRequest')
addExternalIface('Principal', nativeType='nsIPrincipal',
                 headerFile='nsIPrincipal.h', notflattened=True)
addExternalIface('SVGLength')
addExternalIface('SVGMatrix')
addExternalIface('SVGNumber')
addExternalIface('SVGPathSeg')
addExternalIface('SVGPoint')
addExternalIface('SVGTransform')
addExternalIface('TextMetrics', headerFile='nsIDOMCanvasRenderingContext2D.h')
addExternalIface('Touch', headerFile='nsIDOMTouchEvent.h')
addExternalIface('URI', nativeType='nsIURI', headerFile='nsIURI.h',
                 notflattened=True)
addExternalIface('UserDataHandler')
addExternalIface('Window')
addExternalIface('XULElement')