= Overview =

The [http://www.w3.org/TR/WebIDL/ Web IDL] is a language that defines how WebCore interfaces are bound to external languages such as JavaScriptCore, V8, ObjC, GObject and CPP. We need to write IDL files (e.g. XMLHttpRequest.idl, Element.idl, etc) to expose WebCore interfaces to those external languages. When WebKit is built, the IDL files are parsed, and the code to bind WebCore implementations and JavaScriptCore/V8/ObjC/GObject/CPP interfaces is automatically generated.

This page describes practical information about how the IDL binding works and how we can write IDL files in WebKit. The syntax of IDL files is fairly well documented in the [http://www.w3.org/TR/WebIDL/ Web IDL spec], but it is too formal to read:-) and there are several differences between the Web IDL spec and the WebKit IDL due to implementation issues.

= Basics of the IDL =

= How the IDL bindings work =

== JavaScriptCore ==

== V8 ==

== ObjC ==

== GObject ==

== CPP ==

= IDL attributes =

== Basic naming rules ==

== IDL attributes around operations, attributes and parameters ==

In the following explanations, (i), (o), (a) and (p) means that the IDL attribute can be specified on interfaces, operations, attributes and parameters, respectively. For example, (a,p) means that the IDL attribute can be specified on attributes and parameters.

=== * [TreatNullAs](a,p), [TreatUndefinedAs](a,p) ===

 * [http://dev.w3.org/2006/webapi/WebIDL/#TreatNullAs The spec of [TreatNullAs]] (Note: The WebKit IDL explained below behaves differently from the spec)
 * [http://dev.w3.org/2006/webapi/WebIDL/#TreatUndefinedAs The spec of [TreatUndefinedAs]] (Note: The WebKit IDL explained below behaves differently from the spec)

The possible usage is [TreatNullAs=NullString] or [TreatUndefinedAs=NullString].
They can be specified on attributes or parameters of type DOMString only, like this:

{{{
    attribute [TreatNullAs=NullString] DOMString str;
    void operation(in [TreatNullAs=NullString, TreatUndefinedAs=NullString] DOMString str);
}}}

[TreatNullAs=NullString] indicates that if JavaScript null is passed to the attribute/parameter,
then it is converted to the null string in WebKit, for which String::IsEmpty() and String::IsNull() will return true.
Without [TreatNullAs=NullString], JavaScript null is converted to a string "null" in WebKit.

[TreatNullAs=NullString] corresponds to [TreatNullAs=EmptyString] in the Web IDL spec.
Unless the spec does not specify [TreatNullAs=EmptyString], you should not specify [TreatNullAs=NullString] in WebKit.

[TreatUndefinedAs=NullString] indicates that if JavaScript undefined is passed to the attribute/parameter,
then it is converted to the null string in WebKit, for which IsEmpty() and IsNull() will return true.
Without [TreatUndefinedAs=NullString], JavaScript undefined is converted to a string "undefined" in WebKit.

[TreatUndefinedAs=NullString] corresponds to [TreatUndefinedAs=EmptyString] in the Web IDL spec.
Unless the spec does not specify [TreatUndefinedAs=EmptyString], you should not specify [TreatUndefinedAs=NullString] in WebKit.

Note: For now the sole usage of [TreatUndefinedAs=NullString] is not allowed in WebKit.
[TreatUndefinedAs=NullString] must be used with [TreatNullAs=NullString], i.e. [TreatNullAs=NullString, TreatUndefinedAs=NullString].


=== * [TreatReturnedNullStringAs](o,a,p) ===

=== * [Optional](p) ===

=== * [Callback](i,p) ===

=== * [Custom](o,a), [JSCustom](o,a), [V8Custom](o,a), [CustomGetter](a), [JSCustomGetter](a), [V8CustomGetter](a), [CustomSetter](a), [JSCustomSetter](a), [V8CustomSetter](a) ===

=== * [CallWith](o,a) ===

=== * [CheckAccessToNode](o,a) ===

=== * [StrictTypeChecking](o,a) ===

=== * [ReturnNewObject](o,a) ===

=== * [ImplementedAs](o) ===

=== * [Reflect](a) ===

=== * [Replaceable](a) ===

=== * [Deletable](a), [NotEnumerable](a), [V8ReadOnly](a) ===

=== * [CachedAttribute](a) ===

=== * [V8Unforgeable](a), [V8OnInstance](a), [V8OnProto](a) ===

=== * [URL](a) ===

=== * [JSWindowEventListener](a) ===

== IDL attributes around interfaces ==

=== * [Supplemental](i) ===

 * [http://dev.w3.org/2006/webapi/WebIDL/#dfn-supplemental-interface The spec of [Supplemental]]

 * [http://old.nabble.com/Things-missing-from-Web-IDL-for-HTML5-td24873773.html Easy explanation of [Supplemental]]

The [Supplemental] IDL helps WebKit modularization. The [Supplemental] IDL makes it possible to add XXX's APIs (e.g. XXX=WebAudio, WebSocket, Blob, GamePad, ...etc) without modifying code outside of WebCore/Modules/XXX/. This helps make XXX a "self-contained module".

Here is an example. Without the [Supplemental] IDL, if we want to add XXX's attributes or methods to DOMWindow,

 * we need to modify WebCore/page/DOMWindow.idl to add the IDLs of the XXX's attributes or methods

 * we need to modify WebCore/page/DOMWindow.{h,cpp} to add the C++ implementation of the attribute getters and setters or the method callbacks.

On the other hand, in the modularized world with the [Supplemental] IDL, we just need to modify the code under WebCore/Modules/XXX/, like this:

 * WebCore/Modules/XXX/DOMWindowXXX.idl
{{{
   interface [
       Conditional=XXX,
       Supplemental=DOMWindow    // The attributes and methods of this interface are exposed as those of DOMWindow.
   ] DOMWindowXXX {
       attribute foo;
       void bar();
   };
}}}

 * WebCore/Modules/XXX/DOMWindowXXX.h
{{{
   DOMWindowXXX::foo(...) { ... }   // The C++ implementation of the foo attribute getter.
   DOMWindowXXX::setFoo(...) { ... }   // The C++ implementation of the foo attribute setter.
   DOMWindowXXX::bar(...) { ... }   // The C++ implementation of the bar method callback.
}}}

As shown above, [Supplemental=DOMWindow] indicates that all the attributes and methods of DOMWindowXXX should be exposed on DOMWindow, but should be implemented in DOMWindowXXX. In this way, we can implement the attributes and methods without modifying code of DOMWindow.{h,cpp,idl}.

If you want to add APIs whose implementations are likely to be independent from WebCore, it is strongly recommended to put the APIs and .h/.cpp files into WebCore/Modules/XXX/ using the [Supplemental] IDL.

=== * [Constructor](i), [ConstructorCallWith](i), [ConstructorRaisesException](i) ===

=== * [ConstructorTemplate](i), [InitializedByEventConstructor](a) ===

=== * [NamedConstructor](i) ===

=== * [CustomConstructor](i), [JSCustomConstructor](i), [V8CustomConstructor](i) ===

=== * [Conditional](i,o,a) ===

=== * [V8EnabledAtRuntime](i,o,a) ===

=== * [CustomToJSObject](i), [JSCustomToJSObject](i), [V8CustomToJSObject](i) ===

=== * [CheckDomainSecurity](i), [DoNotCheckDomainSecurity](o,a), [DoNotCheckDomainSecurityOnGetter](a), [DoNotCheckDomainSecurityOnSetter](a) ===

=== * [IndexedGetter](i), [CustomIndexedGetter](i) ===

=== * [NamedGetter](i), [NamedCustomGetter](i), [NamedCustomSetter](i) ===

=== * [EventTarget](i) ===

=== * [DoNotCheckConstants](i) ===

=== * [ActiveDOMObject](i), [V8DependentLifeTime](i) ===

=== * [CustomEnumerateProperty](i), [CustomDeleteProperty](i) ===

=== * [IsWorkerContext](i) ===

=== * [CustomCall](i) ===

=== * [JSCustomToNativeObject](i), [JSCustomFinalize](i), [JSCustomIsReachable](i), [JSCustomMarkFunction](i), [JSCustomNamedGetterOnPrototype](i), [JSCustomPushEventHandlerScope](i), [JSCustomDefineOwnProperty](i), [JSCustomGetOwnPropertySlotAndDescriptor](i), [JSCustomDefineOwnPropertyOnPrototype](i) ===

=== * [JSCustomHeader](i) ===

=== * [JSGenerateToJSObject](i), [JSGenerateIsReachable](i), [JSGenerateToNativeObject](i) ===

=== * [JSLegacyParent](i) ===

=== * [JSInlineGetOwnPropertySlot](i) ===

=== * [JSNoStaticTables](i) ===

== IDL attributes used by ObjC, GObject and CPP bindings only ==

=== * [ObjCProtocol](i), [ObjCPolymorphic](i), [ObjCLegacyUnnamedParameters](o), [ObjCUseDefaultView](o), [ObjCImplementedAsUnsignedLongLong](a) ===

Used by ObjC bindings only.

=== * [CPPPureInterface](i) ===

Used by CPP bindings only.

=== * [CustomReturn](p) ===

Used by ObjC, GObject and CPP bindings only.

== IDL attributes which might be deprecated ==

=== * [OmitConstructor], [Immutable], [MasqueradesAsUndefined] ===

Might be deprecated. Discussion is on-going.

=== * [CustomGetOwnPropertySlot], [ConstructorParameters], [ReplaceableConstructor], [ExtendsDOMGlobalObject], [IsIndex], [V8DoNotCheckSignature], [NumericIndexedGetter] ===

Will be deprecated. Discussion is on-going.