Changes between Version 122 and Version 123 of WebKitIDL


Ignore:
Timestamp:
Jun 10, 2013 4:25:40 AM (8 years ago)
Author:
Christophe Dumez
Comment:

Add documentation for RaisesException, harmonize with Blink IDL

Legend:

Unmodified
Added
Removed
Modified
  • WebKitIDL

    v122 v123  
    2222 - [#CachedAttribute CachedAttribute(a)][[br]]
    2323 - [#JSWindowEventListener JSWindowEventListener(a)][[br]]
    24  - [#Constructor Constructor(i), CallWith(i,m,a), ConstructorRaisesException(i)][[br]]
     24 - [#Constructor Constructor(i), CallWith(i,m,a)][[br]]
    2525 - [#ConstructorTemplate ConstructorTemplate(i), InitializedByEventConstructor(a)][[br]]
    2626 - [#NamedConstructor NamedConstructor(i)][[br]]
     
    5656 - [#NoInterfaceObject NoInterfaceObject(i), GlobalContext(i)][[br]]
    5757 - [#EnabledAtRuntime EnabledAtRuntime(i)][[br]]
    58  - [#RaisesException GetterRaisesException(a), SetterRaisesException(a)][[br]]
     58 - [#RaisesException RaisesException(i,m) GetterRaisesException(a), SetterRaisesException(a)][[br]]
    5959
    6060= Overview = #Overview
     
    649649ADD EXPLANATIONS
    650650
    651 == `[Constructor]`(i), `[CallWith]`(i,m,a), `[ConstructorRaisesException]`(i) == #Constructor
     651== `[Constructor]`(i), `[CallWith]`(i,m,a) == #Constructor
    652652
    653653 * [http://dev.w3.org/2006/webapi/WebIDL/#Constructor The spec of Constructor]
    654654
    655655Summary: `[Constructor]` indicates that the interface should have constructor, i.e. "new XXX()".
    656 `[CallWith]` and `[ConstructorRaisesException]` adds information when the constructor callback is called in WebCore.
    657 
    658 Usage: `[Constructor]`, `[CallWith]` and `[ConstructorRaisesException]` can be specified on interfaces:
     656`[CallWith]`adds information when the constructor callback is called in WebCore.
     657
     658Usage: `[Constructor]` and `[CallWith]` can be specified on interfaces:
    659659{{{
    660660    [
    661661        Constructor(float x, float y, DOMString str),
    662         ConstructorRaisesException,
    663662        CallWith=ScriptExecutionContext|ScriptState
    664663    ] interface XXX {
     
    682681
    683682`[Constructor()]` is equivalent to `[Constructor]`.
    684 
    685 If `XXX::create(...)` can throw Exception, you can use `[ConstructorRaisesException]`.
    686 With `[ConstructorRaisesException]`, a placeholder for ExceptionCode is added to the tail argument of `XXX::create(...)`.
    687 {{{
    688     PassRefPtr<XXX> XXX::create(float x, float y, String str, ExceptionCode& ec)
    689     {
    690         ...;
    691         if (...) {
    692             ec = TYPE_MATCH_ERR;
    693             return 0;
    694         }
    695     }
    696 }}}
    697683
    698684If `XXX::create(...)` needs additional information like ScriptExecutionContext and ScriptState,
     
    14961482}}}
    14971483
    1498 == `[GetterRaisesException]`(a), `[SetterRaisesException]`(a) == #RaisesException
     1484== `[RaisesException]`(i,m), `[GetterRaisesException]`(a), `[SetterRaisesException]`(a) == #RaisesException
    14991485
    15001486Standard: This is a non-standard attribute.
    15011487
    1502 Summary: Indicates that the attribute getter / setter may raise exceptions.
    1503 
    1504 The generator will pass by reference an additional "ExceptionCode" parameter to the corresponding implementation method so that an exception code can be returned.
    1505 
    1506 Usage: `[GetterRaisesException]` / `[SetterRaisesException]` can be specified on attributes.
    1507 
     1488Summary: Tells the code generator to append an ExceptionCode& argument when calling the WebCore implementation.
     1489
     1490Implementations may assign a DOMException code to this reference parameter, and the generated binding code will create and throw the appropriate exception type.
     1491
     1492Usage: [RaisesException] can be specified on methods and interfaces, and [GetterRaisesException] and [SetterRaisesException] can be specified on attributes. On methods and attributes, the IDL looks like:
    15081493{{{
    15091494    interface XXX {
    1510         [GetterRaisesException] attribute DOMString a;
    1511         [SetterRaisesException] attribute DOMString b;
    1512         [GetterRaisesException, SetterRaisesException] attribute DOMString c;
    1513     };
    1514 }}}
     1495        [GetterRaisesException, SetterRaisesException] attribute long count;
     1496        [RaisesException] void foo();
     1497    };
     1498}}}
     1499
     1500And the WebCore implementations would look like:
     1501{{{
     1502    long XXX::count(ExceptionCode& ec) {
     1503        if (...) {
     1504            ec = TYPE_MISMATCH_ERROR;
     1505            return;
     1506        }
     1507        ...;
     1508    }
     1509
     1510    void XXX::setCount(long value, ExceptionCode& ec) {
     1511        if (...) {
     1512            ec = TYPE_MISMATCH_ERROR;
     1513            return;
     1514        }
     1515        ...;
     1516    }
     1517
     1518    void XXX::foo(ExceptionCode& ec) {
     1519        if (...) {
     1520            ec = TYPE_MISMATCH_ERROR;
     1521            return;
     1522        }
     1523        ...;
     1524    };
     1525}}}
     1526
     1527If [RaisesException] is specified on an interface and [Constructor] is also specified then an ExceptionCode& argument is added when calling the XXX::create(...) constructor callback.
     1528{{{
     1529    [
     1530        Constructor(float x),
     1531        RaisesException
     1532    ]
     1533    interface XXX {
     1534        ...
     1535    };
     1536}}}
     1537
     1538WebCore needs to implement the following method as a constructor callback:
     1539{{{
     1540PassRefPtr<XXX> XXX::create(float x, ExceptionCode& ec)
     1541{
     1542        ...;
     1543        if (...) {
     1544            ec = TYPE_MATCH_ERR;
     1545            return 0;
     1546        }
     1547        ...;
     1548    }
     1549}}}