web idl 接口定义语言数据类型与 C++绑定关系

Modules

Every IDL module corresponds to a C++ namespace. The name of that namespace is based on module's prefixed name.

IDL

 module dom {
  };

C++

 namespace org {
    namespace w3c {
      namespace dom {

IDL

 [Prefix=::com]
  module getfirebug {

C++

 namespace com {
    namespace getfirebug {

Note: Historically each W3C specification introduced its own module name. However, the recent specifications tend to omit the module specification in the IDL definition. At least it seems one module name per spec doesn't make sense any more.

cf. http://lists.w3.org/Archives/Public/public-webapps/2009AprJun/1380.html

Primitive types

IDL	C++
boolean	bool
byte	signed char
octet	unsigned char
short	short
unsigned short	unsigned short
long	int
unsigned long	unsigned int
long long	long long
unsigned long long	unsigned long long
float	float
double	double

Any

The any type is the union of all other possible types.

IDL

 any

C++

 class Any {
   public:
    Any();
    Any(const Any& value);
    template <typename T>
    Any(const T& x);
    Any& operator=(const Any& x);
    template<typename T>
    Any& operator=(const T& x);
    template<typename T>
    operator T() const;
    // snip
  };

Example

IDL

 interface CanvasRenderingContext2D {
    attribute any fillStyle;
  };

C++

 class CanvasRenderingContext2D : public Object {
  public:
    Any getFillStyle();
    void setFillStyle(Any fillStyle);
  };

  canvasRenderingContext2D->setFillStyle("black");

DOMString

The DOMString type corresponds to the set of all possible sequences of 16 bit unsigned integer code units to be interpreted as UTF-16 encoded strings.

IDL	C++
DOMString	std::u16string

Date

The Date type corresponds to a 64 bit unsigned integer value. In C++ DOM API, the DOMTimeStamp type is defined as Date following Chrome's implementation as specified in DOM Level3 Core (*).

IDL	C++
Date	unsigned long long

(*) It appears currently Chrome is the only browser that treats the DOMTimeStamp type as the Date object in ECMAScript.

Object

The object type corresponds to the set of all possible object references, plus the special value null, which indicates no object reference.

IDL	C++
object	Object
null	0

Interfaces

An interface is a specification of a set of interface members, which are the constants, attributes and operations.

IDL

 interface CanvasRenderingContext2D {
  };

C++

 class CanvasRenderingContext2D : public Object {
  };

Nullable types - T?

A nullable type is an IDL type that can represent an existing type (called the inner type) values, plus an additional value null.

IDL	C++
inner-type?	Nullable<inner-type>

C++

 template <typename T>
  class Nullable {
   public:
    bool hasValue() const;
    T value() const;
    Nullable();
    Nullable(const T& value);
    Nullable(const Nullable<T>& nullable);
    Nullable(const Any& any);
    // snip
  };

Example

IDL

 attribute DOMString? background;

C++

 Nullable<std::string> getBackground();
  void setBackground(Nullable<std::string> background);

Sequences -sequence<T>

Thesequence<T>type is a parameterized type whose values are (possibly zero-length) sequences of values of type T.

IDL	C++
sequence<T>	Sequence<T>

C++

 template <typename T>
  class Sequence
  {
   public:
    Sequence();
    Sequence(const T* array, unsigned int size);
    Sequence(std::initializer_list<T> list);
    Sequence(const Sequence& value);
    ~Sequence();
    T operator[](int index) const;
    T& operator[](int index);
    unsigned int getLength() const;
    // snip
  };

IDL

typedef stylesheets::StyleSheetList StyleSheetList;

  readonly attribute StyleSheetList styleSheets;

C++

 typedef Sequence<StyleSheet*> StyleSheetList;

  StyleSheetList getStyleSheets();

Constants

Constants can be defined in interfaces and exceptions.

IDL

 interface MediaError {
    const unsigned short MEDIA_ERR_ABORTED = 1;
    const unsigned short MEDIA_ERR_NETWORK = 2;
    const unsigned short MEDIA_ERR_DECODE = 3;
    const unsigned short MEDIA_ERR_NONE_SUPPORTED = 4;
  };

C++

 class MediaError : public Object {
    public:
      static const unsigned short MEDIA_ERR_ABORTED = 1;
      static const unsigned short MEDIA_ERR_NETWORK = 2;
      static const unsigned short MEDIA_ERR_DECODE = 3;
      static const unsigned short MEDIA_ERR_NONE_SUPPORTED = 4;
    };

Operations

Each operation defined in the IDL interface will be mapped to one or more member functions in the C++ interface class.

IDL

 interface CanvasRenderingContext2D {
    void fillRect(float x, float y, float w, float h);
  };

C++

 class CanvasRenderingContext2D : public Object {
   public:
    void fillRect(float x, float y, float w, float h);
  };

Optional argument

If the "optional" keyword appears on an operation argument, it indicates that the operation can be invoked by passing values only for the those arguments appearing before the optional argument in the operation’s argument list.

IDL

interface ColorCreator {
    object createColor(float v1, optional float v2, float v3, optional float alpha);
  };

C++

 class ColorCreator {
  public:
    Object createColor(float v1);
    Object createColor(float v1, float v2, float v3);
    Object createColor(float v1, float v2, float v3, float alpha);
  };  

Variadic operation

If the final argument uses the "..." terminal, it indicates that the operation is variadic, and can be passed zero or more arguments after the regular arguments. In C++, a varying number of arguments are represent as a Variadic value.

Example

IDL

  interface IntegerSet {
    readonly attribute unsigned long cardinality;

    void union(long... ints);
    void intersection(long... ints);
  };

C++

 class IntegerSet {
  public:
    unsigned int getCardinality();
    void union(Variadic<int> ints = Variadic<int>());
    void intersection(Variadic<int> ints = Variadic<int>());
  };
  template <typename T>
  class Variadic
  {
public:
    Variadic();
    Variadic(const Any* variadic, size_t length);
    Variadic(std::initializer_list<T> list);
    T operator[](int index) const;
    size_t size() const;
  };

Operations with no identifier

While it has been agreed to remove unnamed getters/setters at W3C WebApps WG (*), operations with no identifier are still in use in several W3C specifications. In C++, the default operation name as shown in the following table is used for operations with no identifier.

IDL	C++
getter	getElement
setter	setElement
creator	createElement
deleter	deleteElement
stringifier	toString

Example

IDL

interface CanvasPixelArray {
    readonly attribute unsigned long length;
    getter octet (in unsigned long index);
    setter void (in unsigned long index, in octet value);
  };

C++

class CanvasPixelArray : public Object {
   public:
    // CanvasPixelArray
    unsigned int getLength();
    unsigned char getElement(unsigned int index);
    void setElement(unsigned int index, unsigned char value);
    // snip
  };
(*) http://www.w3.org/2009/11/02-webapps-minutes.html#action07

Attributes

For each attribute defined on the IDL interface, a getter method is declared. For each attribute defined on the IDL interface that is not read only, a corresponding setter method is also declared.

IDL

interface CanvasRenderingContext2D {
    attribute float globalAlpha;
  };

C++

 class CanvasRenderingContext2D : public Object {
  public:
    float getGlobalAlpha();
    void setGlobalAlpha(float globalAlpha);
  };

Note: A getter is prefixed with "get", and the setter is prefixed with "set" following the Web IDL Java binding.

Exceptions

An exception is used to declare a type of exception that can be thrown by implementation.

IDL

 exception DOMException {
    const unsigned short INDEX_SIZE_ERR = 1;
    const unsigned short DOMSTRING_SIZE_ERR = 2;
    unsigned short code;
  };

C++

 struct DOMException {
    const unsigned short INDEX_SIZE_ERR = 1;
    const unsigned short DOMSTRING_SIZE_ERR = 2;
    unsigned short code;
  };

Note: The use of exceptions can be turned off with esidl.

Implements statements

An implements statement declares the all objects implementing an interface A (the first name) MUST also implement interface B (the second name). In C++, interface members in the mixin interface B are mixed into the primary interface A.

Example

IDL

 interface ElementTraversal {
    readonly attribute Element        firstElementChild;
    readonly attribute Element        lastElementChild;
    readonly attribute Element        previousElementSibling;
    readonly attribute Element        nextElementSibling;
  };

  Element implements ElementTraversal;

  interface Element : Node {
    // snip
  };

C++

 class Element : public Node
  {
   public:
    // snip
    Element getFirstElementChild();
    Element getLastElementChild();
    Element getPreviousElementSibling();
    Element getNextElementSibling();
    // snip

cf. http://lists.w3.org/Archives/Public/public-script-coord/2010OctDec/0071.html

Extended attributes

[Constructor],[NamedConstructor]

If the[Constructor]extended attribute appears on an interface, the corresponding C++ constructor(s) are defined.

IDL

[Constructor,
   Constructor(HTMLFormElement form)]
  interface FormData {
    void append(DOMString name, Blob value);
    void append(DOMString name, DOMString value);
  };

C++

 class FormData : public Object
  {
   public:
    // FormData
    void append(std::u16string name, file::Blob value);
    void append(std::u16string name, std::u16string value);

    // [Constructor]
    FormData();
    FormData(html::HTMLFormElement form);
    
    // snip
  };

Note: Unlike ECMAScript, you do not have to use the "new" operator to create an instance of the interface with the[Constructor]extended attribute.

[PutForwards]

If the[PutForwards]extended attribute appears on a read only attribute declaration whose type is an object implementing an interface, it indicates that assigning to the attribute will have specific behavior. Namely, the assignment is “forwarded” to the attribute (specified by the extended attribute argument) on the object that is currently referenced by the attribute being assigned to.

IDL

 interface Name {
    attribute DOMString full;
    attribute DOMString family;
    attribute DOMString given;
  };

  interface Person {
    [PutForwards=full] readonly attribute Name name;
  };

C++

  class Person {
  public:
    Name* getName();
    void setName(std::string name);
    // snip
  };

[Prefix]

See Modules.

[Supplemental]

cf.http://lists.w3.org/Archives/Public/public-webapps/2009JulSep/0528.html

Example

IDL

 interface Element : Node {
    readonly attribute DOMString tagName;
    // snip
  };

  [Supplemental] interface Element {
    ClientRectList getClientRects();
    ClientRect getBoundingClientRect();
  };

C++

 class Element : public Node {
   public:
    std::string getTagName();
    // snip
    ClientRectList getClientRects();
    ClientRect getBoundingClientRect();
  };