Changes between Version 49 and Version 50 of WebKitIDL


Ignore:
Timestamp:
Feb 20, 2012 12:48:02 AM (12 years ago)
Author:
haraken@chromium.org
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • WebKitIDL

    v49 v50  
    2525 - [#CallWith CallWith(i,m,a)]
    2626
     27 - [#StrictTypeChecking StrictTypeChecking(m,a)]
     28
     29 - [#ReturnNewObject ReturnNewObject(m,a)]
     30
     31 - [#ImplementedAs ImplementedAs(m)]
     32
     33 - [#Reflect Reflect(a)]
     34
     35 - [#Replaceable Replaceable(a)]
     36
     37 - [#Deletable Deletable(a), NotEnumerable(a), V8ReadOnly(a)]
     38
     39 - [#CachedAttribute CachedAttribute(a)]
     40
     41 - [#V8Unforgeable V8Unforgeable(m,a), V8OnProto(m,a)]
     42
     43 - [#URL URL(a)]
     44
     45 - [#JSWindowEventListener JSWindowEventListener(a)]
     46
     47 - [#Supplemental Supplemental(i)]
     48
     49 - [#Constructor Constructor(i), CallWith(i,m,a), ConstructorRaisesException(i)]
     50
     51 - [#ConstructorTemplate ConstructorTemplate(i), InitializedByEventConstructor(a)]
     52
     53 - [#NamedConstructor NamedConstructor(i)]
     54
     55 - [#CustomConstructor CustomConstructor(i), JSCustomConstructor(i), V8CustomConstructor(i), ConstructorParameters(i)]
     56
     57 - [#Conditional Conditional(i,m,a)]
     58
     59 - [#V8EnabledAtRuntime V8EnabledAtRuntime(i,m,a)]
     60
     61 - [#CustomToJSObject CustomToJSObject(i), JSCustomToJSObject(i), V8CustomToJSObject(i)]
     62
     63 - [#CheckSecurity CheckSecurity(i), DoNotCheckSecurity(m,a), DoNotCheckSecurityOnGetter(a), DoNotCheckSecurityOnSetter(a)]
     64
    2765 - [#CheckSecurityForNode CheckSecurityForNode(m,a)]
    28 
    29  - [#StrictTypeChecking StrictTypeChecking(m,a)]
    30 
    31  - [#ReturnNewObject ReturnNewObject(m,a)]
    32 
    33  - [#ImplementedAs ImplementedAs(m)]
    34 
    35  - [#Reflect Reflect(a)]
    36 
    37  - [#Replaceable Replaceable(a)]
    38 
    39  - [#Deletable Deletable(a), NotEnumerable(a), V8ReadOnly(a)]
    40 
    41  - [#CachedAttribute CachedAttribute(a)]
    42 
    43  - [#V8Unforgeable V8Unforgeable(m,a), V8OnProto(m,a)]
    44 
    45  - [#URL URL(a)]
    46 
    47  - [#JSWindowEventListener JSWindowEventListener(a)]
    48 
    49  - [#Supplemental Supplemental(i)]
    50 
    51  - [#Constructor Constructor(i), CallWith(i,m,a), ConstructorRaisesException(i)]
    52 
    53  - [#ConstructorTemplate ConstructorTemplate(i), InitializedByEventConstructor(a)]
    54 
    55  - [#NamedConstructor NamedConstructor(i)]
    56 
    57  - [#CustomConstructor CustomConstructor(i), JSCustomConstructor(i), V8CustomConstructor(i), ConstructorParameters(i)]
    58 
    59  - [#Conditional Conditional(i,m,a)]
    60 
    61  - [#V8EnabledAtRuntime V8EnabledAtRuntime(i,m,a)]
    62 
    63  - [#CustomToJSObject CustomToJSObject(i), JSCustomToJSObject(i), V8CustomToJSObject(i)]
    64 
    65  - [#CheckSecurity CheckSecurity(i), DoNotCheckSecurity(m,a), DoNotCheckSecurityOnGetter(a), DoNotCheckSecurityOnSetter(a)]
    6666
    6767 - [#IndexedGetter IndexedGetter(i)]
     
    294294==  [Optional](p) == #Optional
    295295
    296 Summary: It allows method overloading for methods whose argument count are different with each other.
     296Summary: [Optional] allows method overloading for methods whose argument counts are different with each other.
    297297
    298298Usage: The possible usage is [Optional], [Optional=DefaultIsUndefined] or [Optional=DefaultIsNullString].
    299299[Optional] and [Optional=DefaultIsUndefined] can be specified on parameters.
    300 [Optional=DefaultIsNullString] can be specified on DOMString parameters:
     300[Optional=DefaultIsNullString] can be specified on DOMString parameters only:
    301301{{{
    302302    interface HTMLFoo {
     
    307307}}}
    308308
    309 The parameters marked with [Optional=...] are optional, and JavaScript can omit the parameters. Obviously, if parameter X is marked with [Optional=...], then all subsequent parameters of X must be marked with [Optional=...]. The difference between [Optional] and [Optional=DefaultIsUndefined] is whether your WebCore implementation has overloaded methods or not, as explained below.
     309The parameters marked with [Optional=...] are optional, and JavaScript can omit the parameters. Obviously, if parameter X is marked with [Optional=...], then all subsequent parameters of X should be marked with [Optional=...].
     310
     311The difference between [Optional] and [Optional=DefaultIsUndefined] is whether the WebCore implementation has overloaded methods or not, as explained below.
    310312
    311313In case of func1(...), if JavaScript calls func1(100, 200), then HTMLFoo::func1(int a, int b) is called in WebCore.
    312314If JavaScript calls func1(100, 200, 300), then HTMLFoo::func1(int a, int b, int c) is called in WebCore.
    313 If JavaScript calls func1(100, 200, 300, 400), then HTMLFoo::func1(int a, int b, int c, int d) is called in WebCore. In other words, if your WebCore implementation has overloaded methods, you can use [Optional].
    314 
    315 In case of func2(...), if JavaScript calls func2(100, 200), then it behaves as if JavaScript called func2(100, 200, undefined, undefined).
    316 Consequently, HTMLFoo::func1(int a, int b, int c, int d) is called in WebCore.
    317 100 is passed to a, 200 is passed to b, 0 is passed to c, and 0 is passed to d.
     315If JavaScript calls func1(100, 200, 300, 400), then HTMLFoo::func1(int a, int b, int c, int d) is called in WebCore.
     316In other words, if the WebCore implementation has overloaded methods, you can use [Optional].
     317
     318In case of func2(...), if JavaScript calls func2(100, 200), then it behaves as if JavaScript called func2(100, 200, undefined).
     319Consequently, HTMLFoo::func2(int a, int b, int c) is called in WebCore.
     320100 is passed to a, 200 is passed to b, and 0 is passed to c.
    318321(A JavaScript undefined is converted to 0, following the value conversion rule in the Web IDL spec.)
    319 In this way, WebCore needs to implement func2(int a, int b, int c, int d) only, and needs not to implement overloaded methods like func2(int a, int b) or func2(int a, int b, int c).
     322In this way, WebCore needs to just implement func2(int a, int b, int c) and needs not to implement both func2(int a, int b) and func2(int a, int b, int c).
    320323
    321324The difference between [Optional=DefalutIsUndefined] and [Optional=DefaultIsNullString] appears only when the parameter type is DOMString.
    322 While in [Optional=DefalutIsUndefined] the "supplemented" JavaScript undefined is converted to a WebKit string "undefined", in [Optional=DefaultIsNullString] the "supplemented" JavaScript undefined is converted to a WebKit null string. Specifically, if JavaScript calls func3(100, 200), then HTMLFoo::func3(int a, int b, String c, String d) is called in WebCore. Here 100 is passed to a, 200 is passed to b, a WebKit string "undefined" is passed to c, and a WebKit null string is passed to d.
     325In [Optional=DefalutIsUndefined], the "supplemented" JavaScript undefined is converted to a WebKit string "undefined".
     326On the other hand, in [Optional=DefaultIsNullString], the "supplemented" JavaScript undefined is converted to a WebKit null string.
     327For example, if JavaScript calls func3(100, 200), then HTMLFoo::func3(int a, int b, String c, String d) is called in WebCore.
     328At this point, 100 is passed to a, 200 is passed to b, a WebKit string "undefined" is passed to c, and a WebKit null string is passed to d.
     329d.IsEmpty() and d.IsNull() return true.
    323330
    324331==  [Callback](i,p) FIXME == #Callback
     
    339346==  [Custom](m,a), [JSCustom](m,a), [V8Custom](m,a), [CustomGetter](a), [JSCustomGetter](a), [V8CustomGetter](a), [CustomSetter](a), [JSCustomSetter](a), [V8CustomSetter](a) == #Custom
    340347
    341 Summary: If your bindings require special (i.e. "custom") handling, you can write the bindings code as you like.
     348Summary: They allow you to write bindings code manually as you like.
    342349
    343350Usage: [Custom], [JSCustom] and [V8Custom] can be specified on methods or attributes. [CustomGetter], [JSCustomGetter], [V8CustomGetter], [CustomSetter], [JSCustomSetter], [V8CustomSetter] can be specified on attributes:
     
    347354}}}
    348355
    349 We should minimize the number of custom bindings as less as possible.
     356We should minimize the number of custom bindings as less as possible, since they are likely to be buggy.
    350357Before using [Custom], you should doubly consider if you really need custom bindings.
    351358You are recommended to modify code generators to avoid using [Custom].
     
    353360Before explaining the details, let us clarify the relationship of these IDL attributes.
    354361
    355  * [JSCustom] on a method indicates that you want to write JavaScriptCore custom bindings for the method.
    356  * [V8Custom] on a method indicates that you want to write V8 custom bindings for the method.
     362 * [JSCustom] on a method indicates that you can write JavaScriptCore custom bindings for the method.
     363 * [V8Custom] on a method indicates that you can write V8 custom bindings for the method.
    357364 * [Custom] on a method is equivalent to [JSCustom, V8Custom].
    358  * [JSCustomGetter] or [JSCustomSetter] on an attribute indicates that you want to write JavaScriptCore custom bindings for the attribute getter or setter.
    359  * [V8CustomGetter] or [V8CustomSetter] on an attribute indicates that you want to write V8 custom bindings for the attribute getter or setter.
     365 * [JSCustomGetter] or [JSCustomSetter] on an attribute indicates that you can write JavaScriptCore custom bindings for the attribute getter or setter.
     366 * [V8CustomGetter] or [V8CustomSetter] on an attribute indicates that you can write V8 custom bindings for the attribute getter or setter.
    360367 * [JSCustom] on an attribute is equivalent to [JSCustomGetter, JSCustomSetter].
    361368 * [V8Custom] on an attribute is equivalent to [V8CustomGetter, V8CustomSetter].
     
    364371For example, if you want to write custom bindings only for an attribute getter of JavaScriptCore and V8 and an attribute setter of JavaScriptCore, you can specify [CustomGetter, JSCustomSetter].
    365372
    366 How to write custom bindings are different between JavaScriptCore and V8 or between a method and an attribute getter/setter.
     373How to write custom bindings is different between JavaScriptCore and V8 or between a method and an attribute getter/setter, as follows:
    367374
    368375 * Method in JavaScriptCore: Consider the following example:
     
    373380    };
    374381}}}
    375 You need to prepare WebCore/bindings/js/JSXXXCustom.cpp and write custom bindings:
     382You can write custom bindings in WebCore/bindings/js/JSXXXCustom.cpp:
    376383{{{
    377384    JSValue JSXXX::func(ExecState* exec)
     
    389396    };
    390397}}}
    391 You need to prepare WebCore/bindings/js/JSXXXCustom.cpp and write custom bindings:
     398You can write custom bindings in WebCore/bindings/js/JSXXXCustom.cpp:
    392399{{{
    393400    JSValue JSXXX::str(ExecState* exec) const
     
    405412    };
    406413}}}
    407 You need to prepare WebCore/bindings/js/JSXXXCustom.cpp and write custom bindings:
     414You can write custom bindings in WebCore/bindings/js/JSXXXCustom.cpp:
    408415{{{
    409416    void JSXXX::setStr(ExecState*, JSValue value)
     
    421428    };
    422429}}}
    423 You need to prepare WebCore/bindings/v8/custom/V8XXXCustom.cpp and write custom bindings in the following signature:
     430You can write custom bindings in WebCore/bindings/v8/custom/V8XXXCustom.cpp:
    424431{{{
    425432    v8::Handle<v8::Value> V8XXX::funcCallback(const v8::Arguments& args)
     
    437444    };
    438445}}}
    439 You need to prepare WebCore/bindings/v8/custom/V8XXXCustom.cpp and write custom bindings in the following signature:
     446You can write custom bindings in WebCore/bindings/v8/custom/V8XXXCustom.cpp:
    440447{{{
    441448    v8::Handle<v8::Value> V8XXX::strAccessorGetter(v8::Local<v8::String> name, const v8::AccessorInfo& info)
     
    453460    };
    454461}}}
    455 You need to prepare WebCore/bindings/v8/custom/V8XXXCustom.cpp and write custom bindings in the following signature:
    456 {{{
    457     void V8XXX::eventAccessorSetter(v8::Local<v8::String> name, v8::Local<v8::Value> value, const v8::AccessorInfo& info)
     462You can write custom bindings in WebCore/bindings/v8/custom/V8XXXCustom.cpp:
     463{{{
     464    void V8XXX::strAccessorSetter(v8::Local<v8::String> name, v8::Local<v8::Value> value, const v8::AccessorInfo& info)
    458465    {
    459466        ...;
     
    466473==  [CallWith](i,m,a) == #CallWith
    467474
    468 Summary: It calls a WebCore method with additional information.
     475Summary: [CallWith] indicates that the bindings code calls a WebCore method with additional information.
    469476
    470477Usage: The possible usage is [CallWith=X1|X2|X3|...], where X1, X2, X3, ... is "ScriptExecutionContext", "ScriptState", "ScriptArguments" or "CallStack".
     
    480487    };
    481488}}}
    482 [CallWith] can be specified on interfaces but it has a different meaning. Refer to the [Constructor] section for [CallWith] on interfaces.
    483 
    484 In case of func1(...), HTMLFoo::func1(ScriptExecutionContext* context, int a, int b) is called.
    485 Thus, in HTMLFoo::func1(...) you can retrieve document or window through context.
    486 
    487 In case of func2(...), HTMLFoo::func2(ScriptState* state, int a, int b) is called.
    488 
    489 In case of func3(...), HTMLFoo::func3(ScriptArguments* arguments, ScriptCallStack* callstack, int a, int b) is called.
     489
     490Note: [CallWith] can be also specified on interfaces but it has a different meaning.
     491Refer to [#Constructor the [Constructor] section] for [CallWith] on interfaces.
     492
     493In case of func1(...), HTMLFoo::func1(ScriptExecutionContext* context, int a, int b) is called in WebCore.
     494Thus, in HTMLFoo::func1(...) you can retrieve document or window from context.
     495
     496In case of func2(...), HTMLFoo::func2(ScriptState* state, int a, int b) is called in WebCore.
     497
     498In case of func3(...), HTMLFoo::func3(ScriptArguments* arguments, ScriptCallStack* callstack, int a, int b) is called in WebCore.
    490499
    491500In this way, the additional information is added at the head of normal arguments.
    492501The order of additional information is "ScriptExecutionContext", "ScriptState", "ScriptArguments", and then "CallStack",
    493 despite the order of [CallWith=X1|X2|X3|...]. Thus, in case of func4(...),
    494 HTMLFoo::func3(ScriptArguments* arguments, ScriptCallStack* callstack, int a, int b) is called.
    495 
    496 ==  [CheckSecurityForNode](m,a) == #CheckSecurityForNode
    497 
    498 Summary: It checks if a given Node access is allowed in terms of security.
    499 
    500 Usage: [CheckSecurityForNode] can be specified on methods and attributes:
    501 {{{
    502     attribute [CheckSecurityForNode] Node contentDocument;
    503     [CheckSecurityForNode] SVGDocument getSVGDocument();
    504 }}}
    505 
    506 In terms of security, node.contentDocument should return undefined if the parent frame and the child frame are from different origins.
    507 If the security check is needed, you should specify [CheckSecurityForNode].
    508 This is really important for security.
     502despite the order specified in [CallWith=X1|X2|X3|...].
     503For example, in case of func4(...), HTMLFoo::func3(ScriptArguments* arguments, ScriptCallStack* callstack, int a, int b) is called in WebCore.
    509504
    510505==  [StrictTypeChecking](m,a) FIXME == #StrictTypeChecking
     
    522517==  [ReturnNewObject](m,a) == #ReturnNewObject
    523518
    524 Summary: It controls whether WebCore can return a cached wrapper object or not.
     519Summary: [ReturnNewObject] controls whether WebCore can return a cached wrapper object or WebCore needs to return a newly created wrapper object every time.
    525520
    526521Usage: [ReturnNewObject] can be specified on methods or attributes:
     
    533528For example, consider the case where node.firstChild is accessed:
    534529
    535  1. Node::firstChild() is called
    536  1. The result is passed to toJS() or toV8()
    537  1. toJS() or toV8() checks if a wrapper object of the result is already cached on the node
    538  1. If cached, the cached wrapper object is returned
    539  1. Otherwise, toJS() or toV8() creates the wrapper object of the result
    540  1. The created wrapper object is cached on the node
    541  1. The wrapper object is returned
     530 1. Node::firstChild() is called in WebCore.
     531 1. The result of Node::firstChild() is passed to toJS() or toV8().
     532 1. toJS() or toV8() checks if a wrapper object of the result is already cached on the node.
     533 1. If cached, the cached wrapper object is returned. That's it.
     534 1. Otherwise, toJS() or toV8() creates the wrapper object of the result.
     535 1. The created wrapper object is cached on the node.
     536 1. The wrapper object is returned.
    542537
    543538On the other hand, if you do not want to cache the wrapper object and want to create the wrapper object every time,
    544539you can specify [ReturnNewObject].
    545540
    546 
    547541==  [ImplementedAs](m) == #ImplementedAs
    548542
    549 Summary: It specifies a method name in WebCore implementation, if the IDL method name and the WebCore method name are different.
    550 
    551 Usage: The possible usage is [ImplementedAs=XXX], where XXX is a method name of the WebCore implementation. [ImplementedAs] can be specified on methods:
     543Summary: [ImplementedAs] specifies a method name in WebCore, if the method name in an IDL file and the method name in WebCore are different.
     544
     545Usage: The possible usage is [ImplementedAs=XXX], where XXX is a method name in WebCore.
     546[ImplementedAs] can be specified on methods:
    552547{{{
    553548    [ImplementedAs=deleteFunction] void delete();
    554549}}}
    555550
    556 Basically, the WebCore method name should be equal to the IDL method name.
    557 That being said, sometimes you cannot use the same method name; e.g. "delete" is a C++ keyword.
    558 In such cases, you can explicitly specify the WebCore method name by [ImplementedAs].
     551Basically a method name in WebCore should be the same as the method name in an IDL file.
     552That being said, sometimes you cannot use the same method name; e.g. "delete" is reserved for a C++ keyword.
     553In such cases, you can explicitly specify the method name in WebCore by [ImplementedAs].
    559554You should avoid using [ImplementedAs] as much as possible though.
    560555
     
    10941089 * [DoNotCheckSecurityOnSetter] on an attribute disables the security check for a setter of the attribute.
    10951090 * [DoNotCheckSecurity] on an attribute is equivalent to [DoNotCheckSecurityOnGetter, DoNotCheckSecurityOnSetter].
     1091
     1092==  [CheckSecurityForNode](m,a) == #CheckSecurityForNode
     1093
     1094Summary: It checks if a given Node access is allowed in terms of security.
     1095
     1096Usage: [CheckSecurityForNode] can be specified on methods and attributes:
     1097{{{
     1098    attribute [CheckSecurityForNode] Node contentDocument;
     1099    [CheckSecurityForNode] SVGDocument getSVGDocument();
     1100}}}
     1101
     1102In terms of security, node.contentDocument should return undefined if the parent frame and the child frame are from different origins.
     1103If the security check is needed, you should specify [CheckSecurityForNode].
     1104This is really important for security.
    10961105
    10971106==  [IndexedGetter](i) == #IndexedGetter