doc/src/widl.md

   1 ## WIDL
   2
   3 ### Conventions
   4
   5 Currently WIDL version that is used in Samsung is described here: http://www.w3.org/TR/WebIDL/.
   6 This is document from 19 April 2012.
   7
   8 WIDL used for plugins creation is closer to previous drafts mainly this from
   9 21 October 2010. It is described here: http://www.w3.org/TR/2010/WD-WebIDL-20101021/.
  10
  11 ### Architecture
  12
  13 Each plugin is separated from each other as a different module.
  14 We do this by using module key name.
  15
  16 ```
  17 module identifer {
  18   definitions
  19 }
  20 ```
  21
  22 Each module describes space, binding many connected definitions in one namespace.
  23 Inside each module there are sets of **interface** defined.
  24 Most of the time there is one major interface defined, which is **NoInterfaceObject**.
  25 This is manager object which has only one property which is object that actually
  26 implements manager functionality.
  27
  28 ```
  29 interface identifier : indentifier-of-inherited-interface {
  30   interface-member...
  31 };
  32 ```
  33
  34 Interface is a definition of an object, which can be realized in a system
  35 (an inheritance and overloading is possible).
  36 In interface definition you can put following members:
  37 * Constants.
  38 * Attribute : Interface member, which represents variable inside object,
  39   can be changed, if it is not read only.
  40 * Operation: Interface member, which represents method inside object.
  41   It is a function of programming language, which can be executed and returns a result.
  42 * Special operation: Performs a specific task. i.e. deleter, getter.
  43 * Static operation: It is not called for a specific instance of the interface,
  44   is called for static object regardless of an instance creation.
  45   It is connected with the interface itself.
  46
  47 ```
  48 interface identifier {
  49   attribute type identifier;
  50   [extended-attribute] const type identifier = value;
  51   [extended-attribute] attribute type identifier;
  52   readonly attribute type identifier;
  53   attribute type identifier inherits getter; ///Declared to change read only attribute //inherited from interface
  54   attribute type identifier getraises (NoSuchValue); ///Exception declaration
  55   return-type identifier(arguments…);
  56   return-type identifier(argument-type argument-identifier); ///regular operation
  57   return-type identifier(optional argument);
  58   special-keywords return-type identifier(arguments); ///special operation
  59   [extended-attribute]return-type identifier(arguments…); ///A variable number of //arguments
  60   return-type identifier(arguments) raises (identifier) ///raises exception
  61   caller return-type identifier(argument);
  62   caller return-type (argument);
  63   static return-type identifier(arguments);
  64 };
  65 ```
  66
  67 Next step is to connect manager implementation with Tizen object.
  68
  69 ```
  70 Tizen implements ManagerObject
  71 ```
  72
  73 To provide actual implementations of ManagerObject, instance of its Manager
  74 interface definition has to be made. Inside this Manager interface all attributes
  75 and functions that will be available from manager namespace, should be defined.
  76 There can be attributes, which are other interfaces, operations and everything
  77 that interfaces allows.
  78
  79 Additional interface can be available as a standalone types not connected to
  80 global namespace. Those are either obtained from operation of other interfaces
  81 or constructed with theirs constructor method. Interface which are constructible
  82 are described as follows:
  83
  84 ```
  85 [Constructor(type arg1, optional type? Arg2)]
  86 Interface ConstructibleInterface {
  87   attributes
  88   operations
  89   an so on...
  90 };
  91 ```
  92
  93 As one can see list of parameters is specified for such constructor.
  94 Not all parameters are mandatory, some can be preceded by ```optional```
  95 keyword and ```?``` mark, after type to mark that this is not obligatory argument.
  96 Additionally some operations can be followed by ```raises``` key word to mark that,
  97 described exception type can be thrown during execution of such method.
  98
  99 Because some operations can be asynchronous, it is necessary to provide callbacks
 100 objects that can be executed by such operation. Callback object is special type
 101 of ```interface``` object with ```Callback=FunctionOnly``` extended attribute.
 102
 103 ```
 104 [Callback=FunctionOnly, NoInterfaceObject] interface SomeCallback {
 105   void someMethod(type agr1, ...)
 106 };
 107 ```
 108
 109 On the purpose of listeners which accepts dictionaries, there are callbacks that
 110 support more than one method. There is another definition of callback which
 111 lacks of keyword ```FunctionOnly```.
 112
 113 ```
 114 [Callback, NoInterfaceObject] interface SomeDictionaryCallback {
 115   void firstmethod(type somearg1, ... );
 116   void secondmethod(type somearg2, ... );
 117   any additional methods...
 118 };
 119 ```
 120
 121 ### Example code style
 122
 123 Coding style for example codes put in the between ``\code``  and ``\endcode`` tags
 124 should be written with respect to rules described in [the Appendix B](#appendices/appendix-b-javascript-code-example-style-guide).
 125
 126 ### Example
 127
 128 Example of WIDL file:
 129 ```
 130 module Sample {
 131
 132   enum SampleEnums {
 133     "ENUM1",
 134     "ENUM2",
 135     "ENUM3",
 136   };
 137
 138   typedef (SampleEnums) SampleType;
 139
 140   [NoInterfaceObject] interface SampleManagerObject {
 141     readonly attribute SampleManager sample;
 142   };
 143
 144   Tizen implements SampleManagerObject;
 145
 146   [NoInterfaceObject] interface SampleManager {
 147     void sampleMethod(SampleType param1, Sample2 param2) raises(WebAPIException);
 148     double sampleMethod2(SampleType param1) raises(WebAPIException);
 149     void sampleMethod3(SampleCallback callback) raises(WebAPIException);
 150   };
 151
 152   [Callback=FunctionOnly, NoInterfaceObject]
 153   interface SampleCallback {
 154     void onsuccess(Sample1 param1, Sample2 param2);
 155   };
 156 };
 157 ```