Changes between Version 34 and Version 35 of WebKitIDL

Timestamp:

Feb 16, 2012, 10:44:25 PM (14 years ago)

Author:

haraken@chromium.org

Comment:

--

WebKitIDL

@@ -291 +291 @@
 In terms of security, node.contentDocument should return undefined if the parent frame and the child frame are from different origins.
 If the security check is needed, you should specify [CheckAccessToNode].
+This is really important for security.
 
 === * [StrictTypeChecking](m,a) FIXME ===
@@ -496 +497 @@
 If you forgot to specify [URL], then the attribute getter might cause a bug.
 
-=== * [JSWindowEventListener](a) ===
+=== * [JSWindowEventListener](a) FIXME ===
 
 Summary: ADD SUMMARY
@@ -839 +840 @@
 }}}
 
-=== * [CheckDomainSecurity](i), [DoNotCheckDomainSecurity](m,a), [DoNotCheckDomainSecurityOnGetter](a), [DoNotCheckDomainSecurityOnSetter](a) ===
-
-=== * [IndexedGetter](i), [CustomIndexedGetter](i) ===
-
-=== * [NamedGetter](i), [CustomNamedGetter](i), [CustomNamedSetter](i) ===
-
-=== * [EventTarget](i) ===
+=== * [CheckAccessToFrame](i), [DoNotCheckAccessToFrame](m,a), [DoNotCheckAccessToFrameOnGetter](a), [DoNotCheckAccessToFrameOnSetter](a) ===
+
+Summary: It checks if a given Frame access is allowed or not, in terms of security.
+
+Usage: [CheckAccessToFrame] can be specified on interfaces.
+[DoNotCheckAccessToFrame] can be specified on methods or attributes which belong to interfaces which have [CheckAccessToFrame].
+[DoNotCheckAccessToFrameOnGetter] and [DoNotCheckAccessToFrameOnSetter] can be specified on attributes
+which belong to interfaces which have [CheckAccessToFrame]:
+{{{
+    interface [
+        CheckAccessToFrame
+    ] DOMWindow {
+        attribute DOMString str1;
+        attribute [DoNotCheckAccessToFrame] DOMString str2:
+        attribute [DoNotCheckAccessToFrameOnGetter] DOMString str3:
+        attribute [DoNotCheckAccessToFrameOnSetter] DOMString str4:
+        void func1();
+        [DoNotCheckAccessToFrame] void func2();
+    }
+}}}
+
+Consider the case where you access window.parent from inside iframe which comes from a different origin.
+While it is allowed to access window.parent, it is not allowed to access window.parent.document.
+In such cases, you need to specify [CheckAccessToFrame] in order to check
+whether a given Frame is allowed to access the attribute or method.
+This is really important for security.
+
+If you specify [CheckAccessToFrame] on an interface, the security check is enabled on all the attributes and methods in the interface.
+To disable the security check for some attribute or method, you can use
+[DoNotCheckAccessToFrame], [DoNotCheckAccessToFrameOnGetter] or [DoNotCheckAccessToFrameOnSetter].
+
+ * [DoNotCheckAccessToFrame] on a method disables the security check for the method.
+ * [DoNotCheckAccessToFrame] on an attribute disables the security check for a getter and setter of the attribute.
+ * [DoNotCheckAccessToFrameOnGetter] on an attribute disables the security check for a getter of the attribute.
+ * [DoNotCheckAccessToFrameOnSetter] on an attribute disables the security check for a setter of the attribute.
+ * [DoNotCheckAccessToFrame] on an attribute is equivalent to [DoNotCheckAccessToFrameOnGetter, DoNotCheckAccessToFrameOnSetter].
+
+=== * [IndexedGetter](i) ===
+
+ * [http://dev.w3.org/2006/webapi/WebIDL/#idl-indexed-properties The spec of indexed properties] (Note: The WebKit IDL explained below behaves differently from the spec)
+
+Summary: [IndexedGetter] means that a given interface should have a getter of indexed properties.
+
+Usage: [IndexedGetter] can be specified on interfaces:
+{{{
+    interface [
+        IndexedGetter
+    ] XXX {
+    }
+}}}
+
+Indexed getters define the behavior when XXX[i] is evaluated.
+The bindings code is generated automatically so that XXX[i] behaves equivalent to XXX.item(i).
+
+=== * [CustomIndexedSetter](i) ===
+
+ * [http://dev.w3.org/2006/webapi/WebIDL/#idl-indexed-properties The spec of indexed properties] (Note: The WebKit IDL explained below behaves differently from the spec)
+
+Summary: [CustomIndexedSetter] allows us to write custom bindings for a setter of indexed properties.
+
+Usage: [CustomIndexedSetter] can be specified on interfaces:
+{{{
+    interface [
+        CustomIndexedSetter
+    ] XXX {
+    }
+}}}
+
+Indexed setters define the behavior when "XXX[i] = ..." is evaluated.
+[CustomIndexedSetter] allows us to write the custom bindings.
+
+ * In JavaScriptCore, you can write JSXXX::indexSetter(...) in WebCore/bindings/js/JSXXXCustom.cpp:
+{{{
+    void JSXXX::indexSetter(JSC::ExecState* exec, unsigned index, JSC::JSValue value)
+    {
+        ...;
+    }
+}}}
+ * In V8, you can write V8XXX::indexedPropertyGetter(...) in WebCore/bindings/v8/custom/V8XXXCustom.cpp:
+{{{
+    v8::Handle<v8::Value> V8XXX::indexedPropertyGetter(uint32_t index, const v8::AccessorInfo& info)
+    {
+        ...;
+    }
+}}}
+
+=== * [NamedGetter](i) ===
+
+ * [http://dev.w3.org/2006/webapi/WebIDL/#idl-named-properties The spec of named properties] (Note: The WebKit IDL explained below behaves differently from the spec)
+
+Summary: [NamedGetter] means that a given interface should have a getter of named properties.
+
+Usage: [NamedGetter] can be specified on interfaces:
+{{{
+    interface [
+        NamedGetter
+    ] XXX {
+    }
+}}}
+
+Named getters define the behavior when XXX.foooooooo is evaluated, where foooooooo is not an attribute of a given interface.
+The bindings code is generated automatically so that XXX.foooooooo behaves equivalent to XXX.namedItem(i).
+
+=== [CustomNamedGetter](i), [CustomNamedSetter](i) ===
+
+ * [http://dev.w3.org/2006/webapi/WebIDL/#idl-named-properties The spec of named properties] (Note: The WebKit IDL explained below behaves differently from the spec)
+
+Summary: [CustomNamedGetter]/[CustomNamedSetter] allows us to write custom bindings for a getter/setter of named properties.
+
+Usage: They can be specified on interfaces:
+{{{
+    interface [
+        CustomNamedGetter,
+        CustomNamedSetter
+    ] XXX {
+    }
+}}}
+
+Named getters define the behavior when XXX.foooooooo is evaluated, where foooooooo is not an attribute of a given interface.
+Named setters define the behavior when "XXX.foooooooo = ..." is evaluated.
+[CustomNamedGetter] and [CustomNamedSetter] allow us to write the custom bindings.
+
+ * With [CustomNamedGetter] in JavaScriptCore, you can write JSXXX::canGetItemsForName(...) and JSXXX::nameGetter(...) in WebCore/bindings/js/JSXXXCustom.cpp:
+{{{
+    bool JSXXX::canGetItemsForName(ExecState*, XXX* impl, const Identifier& propertyName)
+    {
+        ...;
+    }
+
+    JSValue JSXXX::nameGetter(ExecState* exec, JSValue slotBase, const Identifier& propertyName)
+    {
+        ...;
+    }
+}}}
+ * With [CustomNamedGetter] in V8, you can write V8XXX::namedPropertyGetter(...) in WebCore/bindings/v8/custom/V8XXXCustom.cpp:
+{{{
+    v8::Handle<v8::Value> V8XXX::namedPropertyGetter(v8::Local<v8::String>, v8::Local<v8::Value>, const v8::AccessorInfo&)
+    {
+        ...;
+    }
+}}}
+ * With [CustomNamedSetter] in JavaScriptCore, you can write JSXXX::putDelegate(...) in WebCore/bindings/js/JSXXXCustom.cpp:
+{{{
+    bool JSXXX::putDelegate(ExecState* exec, const Identifier& propertyName, JSValue value, PutPropertySlot&)
+    {
+        ...;
+    }
+}}}
+ * With [CustomNamedSetter] in V8, you can write V8XXX::namedPropertySetter(...) in WebCore/bindings/v8/custom/V8XXXCustom.cpp:
+{{{
+    v8::Handle<v8::Value> V8XXX::namedPropertySetter(v8::Local<v8::String>, v8::Local<v8::Value>, const v8::AccessorInfo&)
+    {
+        ...;
+    }
+}}}
+
+=== * [EventTarget](i) FIXME ===
+
+Summary: ADD SUMMARY
+
+Usage: [EventTarget] can be specified on interfaces.
+{{{
+    interface [
+        EventTarget
+    ] XXX {
+    }
+}}}
+
+ADD EXPLANATIONS
 
 === * [DoNotCheckConstants](i) ===
 
-=== * [ActiveDOMObject](i), [V8DependentLifeTime](i) ===
+Summary: [DoNotCheckConstants] stops inserting compile-time assertions for constants of a given interface.
+
+Usage: [DoNotCheckConstants] can be specified on interfaces:
+{{{
+    interface [
+        DoNotCheckConstants
+    ] XXX {
+        const unsigned short NOT_FOUND_ERR = 123;
+        const unsigned short SYNTAX_ERR = 124;
+    }
+}}}
+
+Without [DoNotCheckConstants], compile-time assertions are generated to check if the constant values defined in IDL files
+are equal to the constant values in WebKit implementation.
+In the above example, if NOT_FOUND_ERR were 100 in WebKit implementation, the build will fail.
+Basically values of all constants are defined in the spec,
+and thus the values defined in IDL files and the values in WebKit implementations should be equal to the values defined in the spec.
+
+If you want to introduce non-speced constant values and allow different values between IDL files and WebKit implementation,
+you can specify [DoNotCheckConstants] on the interface to skip the compile-time assertions.
+
+=== * [ActiveDOMObject](i) ===
+
+Summary: [ActiveDOMObject] indicates that a DOM object should be kept alive when the DOM object has pending activities.
+
+Usage: [ActiveDOMObject] can be specified on interfaces:
+{{{
+    interface [
+        ActiveDOMObject
+    ] XMLHttpRequest {
+    }
+}}}
+
+If a given DOM object needs to be kept alive as long as the DOM object has pending activities, you need to specify [ActiveDOMObject].
+For example, [ActiveDOMObject] can be used when the DOM object is expecting events to be raised.
+
+If an interface X has [ActiveDOMObject] and an interface Y inherits the interface X,
+then the interface Y should also have [ActiveDOMObject].
+
+=== * [V8DependentLifeTime](i) FIXME ===
+
+Summary: ADD SUMMARY
+
+Usage: [V8DependentLifeTime] can be specified on interfaces.
+{{{
+    interface [
+        V8DependentLifeTime
+    ] XXX {
+    }
+}}}
+
+ADD EXPLANATIONS
 
 === * [CustomEnumerateProperty](i), [CustomDeleteProperty](i) ===
+
+Summary: [CustomEnumerateProperty] allows us to write custom bindings for the case where properties of a given interface are enumerated.
+[CustomDeleteProperty] allows us to write custom bindings for the case where a property of a given interface is deleted.
+
+Usage: They can be specified on interfaces:
+{{{
+    interface [
+        CustomEnumerateProperty,
+        CustomDeleteProperty
+    ] XXX {
+    }
+}}}
+
+With [CustomEnumerateProperty], you can write custom bindings when properties of XXX are enumerated.
+Specifically, you can write JSXXX::getOwnPropertyNames(...) in WebCore/bindings/js/JSXXXCustom.cpp:
+{{{
+    void JSXXX::getOwnPropertyNames(JSObject* object, ExecState* exec, PropertyNameArray& propertyNames, EnumerationMode mode)
+    {
+        ...;
+    }
+}}}
+and V8XXX::namedPropertyQuery(...) and V8XXX::namedPropertyEnumerator(...) in WebCore/bindings/v8/custom/V8XXXCustom.cpp:
+{{{
+    v8::Handle<v8::Integer> V8XXX::namedPropertyQuery(v8::Local<v8::String> name, const v8::AccessorInfo& info)
+    {
+        ...;
+    }
+
+    v8::Handle<v8::Array> V8XXX::namedPropertyEnumerator(const v8::AccessorInfo& info)
+    {
+        ...;
+    }
+}}}
+
+With [CustomDeleteProperty], you can write custom bindings for the case where a property of XXX is deleted.
+Specifically, you can write JSXXX::deleteProperty(...) in WebCore/bindings/js/JSXXXCustom.cpp:
+{{{
+    bool JSXXX::deleteProperty(JSCell* cell, ExecState* exec, const Identifier& propertyName)
+    {
+        ...;
+    }
+}}}
+and V8XXX::namedPropertyDeleter(...) in WebCore/bindings/v8/custom/V8XXXCustom.cpp:
+{{{
+    v8::Handle<v8::Boolean> V8XXX::namedPropertyDeleter(v8::Local<v8::String> name, const v8::AccessorInfo& info)
+    {
+        ...;
+    }
+}}}
 
 === * [IsWorkerContext](i) ===
@@ -866 +1129 @@
 }}}
 
-
 === * [CustomCall](i) ===
+
+Summary: [CustomCall] allows us to write custom bindings for call(...) of a given interface.
+
+Usage: [CustomCall] can be specified on interfaces:
+{{{
+    interface [
+        CustomCall
+    ] XXX {
+    }
+}}}
+
+If you want to write custom bindings for XXX.call(...), you can use [CustomCall].
+
+ * In JavaScriptCore, you can write JSXXX::getCallData(...) in WebCore/bindings/js/JSXXXCustom.cpp:
+{{{
+    JSC::CallType JSXXX::getCallData(JSC::JSCell* cell, JSC::CallData& callData)
+    {
+        ...;
+    }
+}}}
+ * In V8, you can write V8XXX::callAsFunctionCallback(...) in WebCore/bindings/v8/custom/V8XXXCustom.cpp:
+{{{
+    v8::Handle<v8::Value> V8XXX::callAsFunctionCallback(const v8::Arguments& args)
+    {
+        ...;
+    }
+}}}
 
 === * [JSCustomToNativeObject](i), [JSCustomFinalize](i), [JSCustomIsReachable](i), [JSCustomMarkFunction](i), [JSCustomNamedGetterOnPrototype](i), [JSCustomPushEventHandlerScope](i), [JSCustomDefineOwnProperty](i), [JSCustomDefineOwnPropertyOnPrototype](i), [JSCustomGetOwnPropertySlotAndDescriptor](i) ===
@@ -1022 +1311 @@
 }}}
 
-=== * [JSNoStaticTables](i) ===
+=== * [JSNoStaticTables](i) FIXME ===
 
 Summary: ADD SUMMARY