esidl

Introduction

The IDL compiler, esidl, is a program that generates C++ header files from the interface definitions written in Web IDL. Web IDL is an interface definition language being developed at W3C and used in the HTML 5 and other specifications published from W3C.

Syntax

esidl [option] filename ...

Description

esidl creates C++ header files (.h) from IDL source files (.idl).

Note: To expand mixins specified by the implements Web IDL statement, related IDL files MUST be processed at once by specifying the every IDL filename in the argument list.

Preprocessing

In the IDL files, directives such as #ifdef, #include, etc. can be used (esidl currently calls cpp internally).

Note: In the IDL files, interface and method descriptions can be written in Javadoc format, and the esidl compiler copies the Javadoc comments in the IDL files to the C++ header files.

Options

-I directory

Adds directory to the IDL file search path. Header files are created retaining their hierarchical structure below directory.

-fno-exceptions

Disables exception specifications being generated for raises, getraises, and setraises clauses.

-indent style

Generates the C++ header files in the specified coding style. Currently style can be either google or webkit. If -indent option is not specified, the ES coding style is used.

-include file

Processes file as if it is included from the source file.

-isystem directory

Adds directory to the system IDL file search path. Header files and reflection data are created retaining their hierarchical structure below directory.

-namespace name

Ignores module names in the IDL files and all the definitions are grouped in a single namespace given by name.

-object name

If the defined interface does not extend any interface, esidl implicitly assumes the defined interface is derived from the interface specified by name. The default name is object.

-template

Generates a C++ header file for each IDL file that can be used for a bridge implementation between the C++ module and the Web browser like NPAPI bridge for Web IDL.

-skeleton

Generates a C++ header file for each IDL interface that can be used as a skeleton for the interface implementation.

-string name

Specifies the C++ class name that maps Web IDL's DOMString. The default is char*.

C++ mapping

The mapping from IDL source files (.idl) to C++ header files (.h) is as follows:

Modules

Modules create C++ namespaces if -namespace option is not used.

module dom { };

namespace dom { }

If -namespace option is used, module names are ignored.

module dom { };

NA

Interfaces

The interface creates a C++ abstract class.

interface CanvasRenderingContext2D { };

class CanvasRenderingContext2D : public Object { };

A static class method to retrieve the qualified name of the interface, which is a globally unique interface ID, is automatically generated by esidl.

[Constructor], [NamedConstructor]

If the [Constructor] extended attribute appears on an interface, Constructor class is defined inside the interface class.

[NamedConstructor=Image(), NamedConstructor=Image(unsigned long width), NamedConstructor=Image(unsigned long width, unsigned long height)] interface HTMLImageElement : HTMLElement { // snip };

class HTMLImageElement : public HTMLElement { public: class Constructor : public Object { public: virtual HTMLImageElement* createInstance() = 0; virtual HTMLImageElement* createInstance(unsigned long width) = 0; virtual HTMLImageElement* createInstance(unsigned long width, unsigned long height) = 0; }; static HTMLImageElement* createInstance(); static HTMLImageElement* createInstance(unsigned long width); static HTMLImageElement* createInstance(unsigned long width, unsigned long height); static Constructor* getConstructor(); static void setConstructor(Constructor* ctor); private: static Constructor* constructor; // snip };

Note: If the [NamedConstructor] extended attribute appears on an interface, it indicates the ECMAScript global object will have a property with the specified name whose value is a constructor function that can create objects that implement the interface.

Constants

Constants defined in interfaces and exceptions are defined as static class/struct members.

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; };

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 virtual member functions in the C++ interface class.

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

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

Optional

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.

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

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


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.

``` interface IntegerSet { readonly attribute unsigned long cardinality;

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

}; ```

class IntegerSet { public: virtual uint32_t getCardinality() = 0; virtual void union(const int* ints = 0, size_t intsLength = 0) = 0; virtual void intersection(const int* ints = 0, size_t intsLength = 0) = 0; };

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.

interface CanvasRenderingContext2D { attribute float globalAlpha; };

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

[PutForwards]

If the [PutForwards] extended attribute appears on a read only attribute, a setter method is declared taking the specified attribute type as an argument.

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

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

class Person { public: virtual Name* getName() = 0; virtual void setName(const char* name) = 0; // setName() does not take Name* as an argument. };

Primitive types

Primitive types are handled as follows:

| Web IDL | C++ header file | Comments | |:--------|:----------------|:---------| | octet | unsigned char | | char | char | | short | short | | long | int | 4 bytes | | long long | long long | 8 bytes | | boolean | bool | | float | float | | double | double |

DOMString

DOMString is converted to char* by default.

attribute DOMString name;

virtual char* getName(char* name, int nameLength) = 0; virtual void setName(const char* name) = 0;

If -string option is used, the specified C++ type name is used instead of char*. If -string std::string is specified, DOMString is mapped as below:

attribute DOMString name;

virtual std::string getName() = 0; virtual void setName(const std::string name) = 0;

Notice the getter method does not take any argument if -string option is used.

Note: esidl allows string as a string type name in addition to DOMString.

Interface names

An interface name used as a method argument or return value will be treated as an interface pointer in the header file.

void mount(in Stream disk); Cache create(in Stream backingStore);

virtual void mount(es::Stream* disk) = 0; virtual es::Cache* create(es::Stream* backingStore) = 0;

any

any is converted to Any.

attribute any strokeStyle;

virtual Any getStrokeStyle(void* strokeStyle, int strokeStyleLength) = 0; virtual void setStrokeStyle(const Any strokeStyle) = 0;

Note: If -string option is used, methods that return Any type value do not take any argument.

Object

object is converted to object. If it is used for a return type or an argument type, it is converted to object*.

Note: If -object option is used, the specified name will be used instead of object.

Exceptions

exception is converted to struct in header files.

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

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

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 B are mixed in the C++ interface class A.

``` interface Node { readonly attribute unsigned short nodeType; // ... };

interface EventTarget { void addEventListener(DOMString type, EventListener listener, boolean useCapture); // ... };

Node implements EventTarget; ```

class Node : public Object { unsigned short getNodeType(); void addEventListener(DOMString type, EventListener listener, bool useCapture); // ... };

C++ mapping - TBD

Sequences

Note: Maybe a sequence is represented by an object with the index setter and getter methods.

A sequence is a data structure where the number of elements are specified at runtime. In the header files, an argument specifying the length of the sequence is added automatically.

typedef sequence<unsigned short> Name; Name getName(); long setName(in Name name);

typedef unsigned short* Name; virtual int getName(Name name, int nameLength) = 0; virtual int setName(const Name name, int nameLength) = 0;

Octet sequences

sequence<octet> is converted to void* and not unsigned char* in the header file.

Note: ByteArray is under consideration at W3C.

interface Stream { sequence<octet> read(); long write(sequence<octet> src); };

class IStream { public: virtual int read(void* sequence, int sequenceLength) = 0; virtual int write(const void* src, int srcLength) = 0; };

Arrays

TBD: The grammar for Arrays is not defined yet in the specification.

typedef octet Mac[6]; long addMulticastAddress(in Mac mac);

typedef unsigned char Mac[6]; virtual int addMulticastAddress(const Mac mac) = 0;

C++ mapping - ES extension

native

native void_pointer is converted to void*.

``` native void_pointer;

void exit(void_pointer val); ```

virtual void exit(void* val); = 0;

Getting the source code

The source code of the esidl Web IDL compiler can be obtained via Subversion:

svn checkout http://es-operating-system.googlecode.com/svn/trunk/esidl esidl

Please read the README file for the build instruction.

Note: esidl can be used without ES operating system. The above source code contains an example code using Web IDL for NPAPI plug-in development.