<div class="separator"></div>
<a title="Tizen Avengers - WebApi Guidelines" class="brand" href="#" style="background-image:url(images/tizen-logo_32h.png)"></a>
<div class="separator"></div>
- <ul id="sections"><li class="l2"><a href="#revision-history">Revision History</a></li><li class="l2"><a href="#overview">Overview</a></li><li class="l2"><a href="#guideline">Guideline</a><ul><li class="l3"><a href="#guideline/languages">Languages</a></li><li class="l3"><a href="#guideline/coding-style">Coding style</a></li><li class="l3"><a href="#guideline/api-guide">API guide</a></li><li class="l3"><a href="#guideline/unit-test-criteria">Unit test criteria</a></li><li class="l3"><a href="#guideline/source-code">Source code</a></li><li class="l3"><a href="#guideline/license-and-boilerplate">License and Boilerplate</a></li></ul></li><li class="l2"><a href="#plugin-structure">Plugin Structure</a><ul><li class="l3"><a href="#plugin-structure/conventions">Conventions</a></li><li class="l3"><a href="#plugin-structure/structure">Structure</a></li><li class="l3"><a href="#plugin-structure/spec-file">Spec file</a></li><li class="l3"><a href="#plugin-structure/manifest-file">Manifest file</a></li><li class="l3"><a href="#plugin-structure/gyp-file">GYP file</a></li><li class="l3"><a href="#plugin-structure/implementation-files">Implementation files</a></li><li class="l3"><a href="#plugin-structure/plugin-flow">Plugin flow</a></li></ul></li><li class="l2"><a href="#widl">WIDL</a><ul><li class="l3"><a href="#widl/conventions">Conventions</a></li><li class="l3"><a href="#widl/architecture">Architecture</a></li><li class="l3"><a href="#widl/example">Example</a></li></ul></li><li class="l2"><a href="#tools">Tools</a><ul><li class="l3"><a href="#tools/generate-stub-code">Generate stub code</a></li><li class="l3"><a href="#tools/using-multiple-javascript-files">Using multiple JavaScript files</a></li></ul></li><li class="l2"><a href="#implementation-javascript">Implementation - JavaScript</a><ul><li class="l3"><a href="#implementation-javascript/interface-creation">Interface creation</a></li><li class="l3"><a href="#implementation-javascript/creating-manager-entity">Creating Manager entity</a></li><li class="l3"><a href="#implementation-javascript/properties-definition">Properties definition</a></li><li class="l3"><a href="#implementation-javascript/methods-definition">Methods definition</a></li><li class="l3"><a href="#implementation-javascript/exporting-interface">Exporting interface</a></li><li class="l3"><a href="#implementation-javascript/utils">Utils</a></li><li class="l3"><a href="#implementation-javascript/exceptions">Exceptions</a></li><li class="l3"><a href="#implementation-javascript/synchronous-methods">Synchronous methods</a></li><li class="l3"><a href="#implementation-javascript/asynchronous-methods">Asynchronous methods</a></li><li class="l3"><a href="#implementation-javascript/listeners">Listeners</a></li></ul></li><li class="l2"><a href="#implementation-c">Implementation - C++</a><ul><li class="l3"><a href="#implementation-c/lifecycle-and-plugin-state">Lifecycle and plugin state</a></li><li class="l3"><a href="#implementation-c/privileges">Privileges</a></li><li class="l3"><a href="#implementation-c/namespace-and-entry-points">Namespace and entry points</a></li><li class="l3"><a href="#implementation-c/plugin-structure">Plugin structure</a></li><li class="l3"><a href="#implementation-c/asynchronous-calls">Asynchronous calls</a></li><li class="l3"><a href="#implementation-c/listeners">Listeners</a></li><li class="l3"><a href="#implementation-c/logger">Logger</a></li><li class="l3"><a href="#implementation-c/error-handling">Error handling</a></li></ul></li><li class="l2"><a href="#devel-package">Devel package</a><ul><li class="l3"><a href="#devel-package/package-structure">Package structure</a></li><li class="l3"><a href="#devel-package/creating-custom-web-device-plugins-module">Creating custom web device plugins module</a></li></ul></li></ul>
+ <ul id="sections"><li class="l2"><a href="#revision-history">Revision History</a></li><li class="l2"><a href="#overview">Overview</a></li><li class="l2"><a href="#guideline">Guideline</a><ul><li class="l3"><a href="#guideline/languages">Languages</a></li><li class="l3"><a href="#guideline/coding-style">Coding style</a></li><li class="l3"><a href="#guideline/api-guide">API guide</a></li><li class="l3"><a href="#guideline/unit-test-criteria">Unit test criteria</a></li><li class="l3"><a href="#guideline/source-code">Source code</a></li><li class="l3"><a href="#guideline/license-and-boilerplate">License and Boilerplate</a></li></ul></li><li class="l2"><a href="#plugin-structure">Plugin Structure</a><ul><li class="l3"><a href="#plugin-structure/conventions">Conventions</a></li><li class="l3"><a href="#plugin-structure/structure">Structure</a></li><li class="l3"><a href="#plugin-structure/spec-file">Spec file</a></li><li class="l3"><a href="#plugin-structure/manifest-file">Manifest file</a></li><li class="l3"><a href="#plugin-structure/gyp-file">GYP file</a></li><li class="l3"><a href="#plugin-structure/implementation-files">Implementation files</a></li><li class="l3"><a href="#plugin-structure/plugin-flow">Plugin flow</a></li><li class="l3"><a href="#plugin-structure/tizen-unified">Tizen Unified</a></li></ul></li><li class="l2"><a href="#widl">WIDL</a><ul><li class="l3"><a href="#widl/conventions">Conventions</a></li><li class="l3"><a href="#widl/architecture">Architecture</a></li><li class="l3"><a href="#widl/example-code-style">Example code style</a></li><li class="l3"><a href="#widl/example">Example</a></li></ul></li><li class="l2"><a href="#tools">Tools</a><ul><li class="l3"><a href="#tools/generate-stub-code">Generate stub code</a></li><li class="l3"><a href="#tools/using-multiple-javascript-files">Using multiple JavaScript files</a></li><li class="l3"><a href="#tools/format-code">Format code</a></li></ul></li><li class="l2"><a href="#implementation-javascript">Implementation - JavaScript</a><ul><li class="l3"><a href="#implementation-javascript/interface-creation">Interface creation</a></li><li class="l3"><a href="#implementation-javascript/creating-manager-entity">Creating Manager entity</a></li><li class="l3"><a href="#implementation-javascript/properties-definition">Properties definition</a></li><li class="l3"><a href="#implementation-javascript/methods-definition">Methods definition</a></li><li class="l3"><a href="#implementation-javascript/exporting-interface">Exporting interface</a></li><li class="l3"><a href="#implementation-javascript/utils">Utils</a></li><li class="l3"><a href="#implementation-javascript/exceptions">Exceptions</a></li><li class="l3"><a href="#implementation-javascript/synchronous-methods">Synchronous methods</a></li><li class="l3"><a href="#implementation-javascript/asynchronous-methods">Asynchronous methods</a></li><li class="l3"><a href="#implementation-javascript/listeners">Listeners</a></li></ul></li><li class="l2"><a href="#implementation-c">Implementation - C++</a><ul><li class="l3"><a href="#implementation-c/lifecycle-and-plugin-state">Lifecycle and plugin state</a></li><li class="l3"><a href="#implementation-c/privileges">Privileges</a></li><li class="l3"><a href="#implementation-c/namespace-and-entry-points">Namespace and entry points</a></li><li class="l3"><a href="#implementation-c/plugin-structure">Plugin structure</a></li><li class="l3"><a href="#implementation-c/dependencies-between-plugins">Dependencies between plugins</a></li><li class="l3"><a href="#implementation-c/asynchronous-calls">Asynchronous calls</a></li><li class="l3"><a href="#implementation-c/listeners">Listeners</a></li><li class="l3"><a href="#implementation-c/logger">Logger</a></li><li class="l3"><a href="#implementation-c/error-handling">Error handling</a></li></ul></li><li class="l2"><a href="#devel-package">Devel package</a><ul><li class="l3"><a href="#devel-package/package-structure">Package structure</a></li><li class="l3"><a href="#devel-package/creating-custom-web-device-plugins-module">Creating custom web device plugins module</a></li></ul></li><li class="l2"><a href="#appendices">Appendices</a><ul><li class="l3"><a href="#appendices/appendix-a-type-conversion-tables">Appendix A - type conversion tables</a></li><li class="l3"><a href="#appendices/appendix-b-javascript-code-example-style-guide">Appendix B - Javascript code example style guide</a></li></ul></li></ul>
<div class="separator"></div>
<div class="extra generated">
Generated by <a href="https://github.com/DimitarChristoff/doctor" target="_blank" title="generate documentation from markdown">Doctor, MD</a>
<td>0.1.0</td>
<td>2015-05-15</td>
<td>Initial Draft</td>
-<td>Wojciech Kosowicz<br><a href="mailto:w.kosowicz@samsung.com">w.kosowicz@samsung.com</a></td>
+<td>Wojciech Kosowicz<br><a href="mailto:w.kosowicz@samsung.com">w.kosowicz@samsung.com</a></td>
</tr>
<tr>
<td>0.2.0</td>
<td>2015-05-22</td>
<td>Extended version</td>
-<td>Pawel Kaczmarek<br><a href="mailto:p.kaczmarek3@samsung.com">p.kaczmarek3@samsung.com</a></td>
+<td>Pawel Kaczmarek<br><a href="mailto:p.kaczmarek3@samsung.com">p.kaczmarek3@samsung.com</a></td>
</tr>
<tr>
<td>0.2.1</td>
<td>2015-06-01</td>
<td>Proofreading</td>
-<td>Rafal Galka<br><a href="mailto:r.galka@samsung.com">r.galka@samsung.com</a></td>
+<td>Rafal Galka<br><a href="mailto:r.galka@samsung.com">r.galka@samsung.com</a></td>
</tr>
<tr>
<td>0.3.0</td>
<td>2015-06-08</td>
<td>Supplemented C++ implementation guide</td>
-<td>Rafal Galka<br><a href="mailto:r.galka@samsung.com">r.galka@samsung.com</a></td>
+<td>Rafal Galka<br><a href="mailto:r.galka@samsung.com">r.galka@samsung.com</a></td>
</tr>
<tr>
<td>0.4.0</td>
<td>2015-06-16</td>
<td>Guideline</td>
-<td>Pawel Kaczmarek<br><a href="mailto:p.kaczmarek3@samsung.com">p.kaczmarek3@samsung.com</a></td>
+<td>Pawel Kaczmarek<br><a href="mailto:p.kaczmarek3@samsung.com">p.kaczmarek3@samsung.com</a></td>
</tr>
<tr>
<td>0.5.0</td>
<td>2015-06-18</td>
<td>Devel package</td>
-<td>Pawel Kaczmarek<br><a href="mailto:p.kaczmarek3@samsung.com">p.kaczmarek3@samsung.com</a></td>
+<td>Pawel Kaczmarek<br><a href="mailto:p.kaczmarek3@samsung.com">p.kaczmarek3@samsung.com</a></td>
</tr>
<tr>
<td>0.5.1</td>
<td>2015-06-24</td>
<td>Add info about WAPIOven.py</td>
-<td>Pawel Kaczmarek<br><a href="mailto:p.kaczmarek3@samsung.com">p.kaczmarek3@samsung.com</a></td>
+<td>Pawel Kaczmarek<br><a href="mailto:p.kaczmarek3@samsung.com">p.kaczmarek3@samsung.com</a></td>
</tr>
<tr>
<td>0.6.0</td>
<td>2016-10-28</td>
<td>update devel package for tizen 3.0</td>
-<td>Annie Park<br><a href="mailto:hj.na.park@samsung.com">hj.na.park@samsung.com</a></td>
+<td>Annie Park<br><a href="mailto:hj.na.park@samsung.com">hj.na.park@samsung.com</a></td>
+</tr>
+<tr>
+<td>0.7.0</td>
+<td>2017-11-09</td>
+<td>Update guidelines for Tizen 4.0</td>
+<td>Szymon Jastrzębski<br><a href="mailto:s.jastrzebsk@partner.samsung.com">s.jastrzebsk@partner.samsung.com</a></td>
</tr>
</tbody>
</table>
<h3 id="guideline/languages">Languages</h3>
<p>C++, JavaScript</p>
<h3 id="guideline/coding-style">Coding style</h3>
-<p>Use Google style guide,
-C++: <a href="http://google-styleguide.googlecode.com/svn/trunk/cppguide.html">http://google-styleguide.googlecode.com/svn/trunk/cppguide.html</a></p>
-<p>JavaScript: <a href="http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml">http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml</a></p>
+<p>Use Google style guides (with small exceptions):</p>
+<p>C++: <a href="https://google.github.io/styleguide/cppguide.html">https://google.github.io/styleguide/cppguide.html</a></p>
+<p>JavaScript: <a href="https://google.github.io/styleguide/jsguide.html">https://google.github.io/styleguide/jsguide.html</a></p>
+<p>On branches <code>tizen_3.0</code> and higher, the C++ <del>and JavaScript</del> files are formatted using scripts,
+which its usage is described in the <a href="#tools/format-code">Format code</a> section of this document.
+The section also describes where the exceptions from Google coding style are defined.</p>
<h3 id="guideline/api-guide">API guide</h3>
<p>Tizen Web Device API Guide Lines.pptx
<a href="http://platform.sec.samsung.net/slp/Tizen/Tizen%20Managed%20API/Web%20Device%20API/Tizen%20Web%20Device%20API%20Guide%20Lines.pptx">http://platform.sec.samsung.net/slp/Tizen/Tizen%20Managed%20API/Web%20Device%20API/Tizen%20Web%20Device%20API%20Guide%20Lines.pptx</a></p>
$ cd webapi-plugins
$ git checkout origin/tizen_2.4
</code></pre>
-<p>For Tizen 3.0</p>
-<pre><code class="lang-sh">$ git clone ssh://<user.id>@168.219.209.56:29418/framework/web/webapi-plugins
+<p>For Tizen 3.0 and higher</p>
+<pre><code class="lang-sh">$ git clone ssh://<user.id>@review.tizen.org:29418/platform/core/api/webapi-plugins && scp -p -P 29418 <user.id>@review.tizen.org:hooks/commit-msg webapi-plugins/.git/hooks/
$ cd webapi-plugins
-$ git checkout origin/tizen_3.0
+$ git checkout origin/tizen_<tizen_version>
</code></pre>
<h3 id="guideline/license-and-boilerplate">License and Boilerplate</h3>
<p>Use this boilerplate in every new created source files.</p>
<pre><code class="lang-sh">/*
- * Copyright (c) 2015 Samsung Electronics Co., Ltd All Rights Reserved
+ * Copyright (c) <year of file creation> Samsung Electronics Co., Ltd All Rights Reserved
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
<li><code><pluginname>_instance.h</code></li>
<li><code><pluginname>_instance.cc</code></li>
</ul>
+<p>Additionally, plugins may contain below structure, depending on the WIDL specification file:</p>
+<ul>
+<li><code><pluginname>_client.h</code></li>
+<li><code><pluginname>_client.cc</code></li>
+<li><code><pluginname>_server.h</code></li>
+<li><code><pluginname>_server.cc</code></li>
+<li><code><pluginname>_service.h</code></li>
+<li><code><pluginname>_service.cc</code></li>
+<li><code><pluginname>_util.h</code></li>
+<li><code><pluginname>_util.cc</code></li>
+</ul>
+<p>and other files with similar naming-convention needed by the developer.</p>
<h3 id="plugin-structure/spec-file">Spec file</h3>
<p>Spec file (<code>webapi-plugins.spec</code>) kept inside <code>packaging/</code> directory
-is build specification file used by RPM packaging system where variables are defined.
+is a build specification file used by RPM packaging system where variables are defined.
Those variables can be used to include or exclude particular modules from
build for each profile (mobile, TV, wearable).</p>
<h3 id="plugin-structure/manifest-file">Manifest file</h3>
-<p>Each RPM package must have a manifest file where developers can specify the access control domain
+<p>Each RPM package must have a manifest file, where developers can specify the access control domain
in which their application should be running and potentially additional security policies for the
application. It is necessary to build the project. The manifest file (<code>webapi-plugins.manifest</code>)
is located in the root directory of the project.</p>
This file contains all methods required by each API.
All operation should be done by JavaScript as much as possible.
If JavaScript can do something, it should do it.
-This file is responsible for checking arguments, calling C++ methods etc.</li>
+This file is responsible for checking and validating arguments, calling C++ methods etc.</li>
</ul>
<h3 id="plugin-structure/plugin-flow">Plugin flow</h3>
<p><img src="images/plugin_flow.png" alt="Plugin flow"></p>
This information consists of type of call (asynchronous, synchronous)
arguments given by user, any additional information that is required to
successfully acquire required data. Data is sent in form of JSON.</li>
-<li>C++ parses acquired JSON. After the data is processed. Appropriate platform
+<li>C++ parses acquired JSON. After the data is processed, appropriate platform
functions are called with the specified arguments.</li>
<li>Platform returns specified values to C++ layer.</li>
-<li>Another JSON is formed. It consists of data that was acquired from platform.</li>
+<li>Another JSON is formed. It consists of data that was acquired from platform.
+The data is sent to JavaScript layer.</li>
</ol>
+<h3 id="plugin-structure/tizen-unified">Tizen Unified</h3>
+<p>With Tizen 4.0 an idea of Tizen Unified was introduced.</p>
+<p>Before Tizen 4.0, each profile specified in <code>.gbs.conf</code> file defined the package repositories
+for a single device type and a particular architecture.</p>
+<p>Since Tizen 4.0, each GBS profile is associated with a particular architecture and all device types.</p>
+<p>Each device with given profile and architecture requires to have at least 2 RPM files installed:</p>
+<pre><code class="lang-sh">webapi-plugins-x.y-z.ARCH.rpm
+webapi-plugins-profile_PROFILE_NAME-x.y-z.ARCH.rpm
+</code></pre>
+<p>However, emulators require to have 3 RPM files installed:</p>
+<pre><code class="lang-sh">webapi-plugins-x.y-z.i686.rpm
+webapi-plugins-profile_PROFILE_NAME-x.y-z.i686.rpm
+webapi-plugins-PROFILE_NAME-extension-emulator-x.y-z.i686.rpm
+</code></pre>
<h2 id="widl">WIDL</h2>
<h3 id="widl/conventions">Conventions</h3>
<p>Currently WIDL version that is used in Samsung is described here: <a href="http://www.w3.org/TR/WebIDL/">http://www.w3.org/TR/WebIDL/</a>.
can be changed, if it is not read only.</li>
<li>Operation: Interface member, which represents method inside object.
It is a function of programming language, which can be executed and returns a result.</li>
-<li>Special operation: Performs a specific task. i.e. deleter, getter</li>
+<li>Special operation: Performs a specific task. i.e. deleter, getter.</li>
<li>Static operation: It is not called for a specific instance of the interface,
is called for static object regardless of an instance creation.
It is connected with the interface itself.</li>
<pre class="prettyprint linenums"><code>Tizen implements ManagerObject
</code></pre><p>To provide actual implementations of ManagerObject, instance of its Manager
interface definition has to be made. Inside this Manager interface all attributes
-and functions that will be available form manager namespace, should be defined.
-There can be attributes which are other interfaces, operations and everything
+and functions that will be available from manager namespace, should be defined.
+There can be attributes, which are other interfaces, operations and everything
that interfaces allows.</p>
<p>Additional interface can be available as a standalone types not connected to
global namespace. Those are either obtained from operation of other interfaces
void secondmethod(type somearg2, ... );
any additional methods...
};
-</code></pre><h3 id="widl/example">Example</h3>
+</code></pre><h3 id="widl/example-code-style">Example code style</h3>
+<p>Coding style for example codes put in the between <code>\code</code> and <code>\endcode</code> tags
+should be written with respect to rules described in <a href="#appendices/appendix-b-javascript-code-example-style-guide">the Appendix B</a>.</p>
+<h3 id="widl/example">Example</h3>
<p>Example of WIDL file:</p>
<pre class="prettyprint linenums"><code>module Sample {
};
</code></pre><h2 id="tools">Tools</h2>
<h3 id="tools/generate-stub-code">Generate stub code</h3>
+<h4 id="-span-style-color-red-the-generator-is-no-longer-maintained-span-"><span style="color:red"><strong>The generator is no longer maintained.</strong></span></h4>
<p>To generate stub files from the widl you can use stub generator located in
<code>tools/skeleton_generator/</code> directory and run the python command:</p>
<pre><code class="lang-sh">$ python WAPIOven.py -d <stub code destination directory name> <widl directory/pluginname>.widl
<p>WIDL files can be found in the project repository:</p>
<pre><code class="lang-sh">$ git clone ssh://<username>@168.219.209.56:29418/doc/web-device-api
</code></pre>
-<p>The widl files are placed in: <code>web-device-api/web/widl/tizen/</code></p>
+<p>The widl files are placed in: <code>web-device-api/web/widl/tizen/</code> directory.</p>
<p>Stub files generated by above command:</p>
<pre><code class="lang-sh"><pluginname>_api.js
<pluginname>_extension.h
<p>To merge all JavaScript files <code>tools/mergejs.py</code> file is used.
This script merge all files mentioned in <code><pluginname>_api.js</code> file into one
file before build process.</p>
+<h3 id="tools/format-code">Format code</h3>
+<p>To format code use scripts provided in the <code>tools/codestyle</code> directory.</p>
+<p><code>cpplint</code> is used to validate C++ and <code>eslint</code> for JavaScript files.</p>
+<p><strong>Currently, the JavaScript validator and formatter seems to be a little buggy,
+thus it is not recommended to use.</strong></p>
+<p>The developer needs to have <code>python</code>, <code>node.js</code>, <code>eslint</code>, <code>Closure Linter</code> and <code>clang-format</code> installed.</p>
+<p>It is worth to make life easier by creating symbolic link to <code>clang-format</code>.</p>
+<pre><code class="lang-sh">sudo ln -s /usr/bin/clang-format-<clang format version> /usr/bin/clang-format
+</code></pre>
+<p>For convenience, in the root of the project links were provided for easier access:</p>
+<ul>
+<li><code>code_format -> tools/codestyle/code_formatter.sh</code></li>
+<li><code>code_validate -> tools/codestyle/code_validation.sh</code></li>
+</ul>
+<p>Those scripts consist of configuration for rules regarding the Google style guides, with few exceptions.</p>
+<p>To format and validate C++ and JavaScript code run in the root of the project:</p>
+<pre><code class="lang-sh">./code_validate -a # -a for all, -c for C++, -js for JavaScript files
+./code_format -a # use -h or --help for help
+</code></pre>
+<p>The scripts also accept a path to module's directory.
+By default every directory module in the <code>src</code> directory is used.</p>
+<p>For more details, please see <code>tools/codestyle/README</code> file.</p>
+<p>This rule concerns to branches <code>tizen_3.0</code> and above.</p>
<h2 id="implementation-javascript">Implementation - JavaScript</h2>
<p>Each plugin contains JavaScript files. This is the place where user input is
-being processed validated before send to C++ layer.</p>
-<p>Badge API will be used to show the creation of JavaScript file (lot of content
-of this file will be already generated via Stub Generator).</p>
+being processed validated before sending to C++ layer.</p>
+<p>Badge API will be used to show the creation of JavaScript file.</p>
<h3 id="implementation-javascript/interface-creation">Interface creation</h3>
<p>The WIDL of BadgeManager – main entity that holds all the API methods
looks like following:</p>
</code></pre>
<h4 id="validator">Validator</h4>
<p>When API JavaScript method is called first thing that has to be done in
-JavaScript layer of api implementation is to process and validate arguments
+JavaScript layer of API implementation is to process and validate arguments
given by the user. The process of validation consists of ensuring that the
proper amount of arguments was given and that they were of the expected
type and throwing exception if necessary.</p>
<p>Validator helps to ensure that user sent proper values. Validator is available
-at <code>xwalk.utils.validator</code> and predefined js types at <code>xwalk.utils.validator.types</code></p>
+at <code>xwalk.utils.validator</code> and predefined JavaScript types at <code>xwalk.utils.validator.types</code></p>
<p>Below can be found example of using validator inside <code>setBadgeCount</code> method
that requires appId in form of string and long count value:</p>
<pre class="prettyprint linenums"><code class="lang-js">var validator_ = xwalk.utils.validator;
{name: 'count', type: types_.LONG}
]);
</code></pre>
+<p>The <code>validateArgs</code> method may also validate optional and nullable arguments.
+See its definition in file <code>src/utils/utils_api.js</code>.</p>
+<p>This method respecting the JavaScript type conversion rules is presented <a href="#appendices/appendix-a-type-conversion-tables">the Appendix A - type conversion tables</a>.</p>
<h3 id="implementation-javascript/exceptions">Exceptions</h3>
<p>At some point whether improper data is received or given to JavaScript might
require to throw exceptions. The example below shows how to throw properly
</code></pre>
<p>WebAPIException constructor takes as argument the type of error to be thrown.
The second additional argument is error message.</p>
+<p>There might be a need to throw expception because of failure received from C++ layer,
+for this case see below section.</p>
<h3 id="implementation-javascript/synchronous-methods">Synchronous methods</h3>
<p>In order to perform synchronous operation (one that does not require callback
and the result is given instantly) callSync() method of Native manager needs
<h3 id="implementation-javascript/asynchronous-methods">Asynchronous methods</h3>
<p>In order to work with method that requires callback instead of callSync(),
call() method needs to be called. Apart from the first two arguments that are
-exactly the same as in call() method (c++ method binding, object) it takes
+exactly the same as in callSync() method (C++ method binding, object) it takes
additional argument that is a function that will be called when the native
-call is processed:</p>
+call response is processed:</p>
<pre class="prettyprint linenums"><code class="lang-js">var native_ = new xwalk.utils.NativeManager(extension);
var callback = function(result) {
if (native_.isFailure(result)) {
Example: If operation should change some object retrieved from platform,
identifier should be passed again and additional check if object still exists
should be made.</p>
+<p>According to <a href="https://google.github.io/styleguide/cppguide.html#Static_and_Global_Variables">Google C++ Style Guide</a> static variables should <strong>NOT</strong> be used.</p>
+<p>This rule concerns especially to <code><pluginname>Manager</code>, <code><pluginname>Client</code>,
+<code><pluginname>Server</code> etc. classes, which tend to implement the Singleton design pattern.
+Because of this, the above mentioned classes' instances should <strong>NOT</strong> be declared as <code>static</code>
+and should <strong>NOT</strong> be got through <code>getInstance</code> methods.
+Instead, the classes's instances should be declared as an <code>private</code> attribute of
+<code><pluginname>Instance</code> class.</p>
<h3 id="implementation-c/privileges">Privileges</h3>
<p>Some of the API methods require privilege access. The privilege engine used in the project is Cynara.
In Tizen 3.0 checking if application has privilege to call method has been moved to C++ layer. It's the
ReportSuccess(data, out);
</code></pre>
+<h3 id="implementation-c/dependencies-between-plugins">Dependencies between plugins</h3>
+<p>To allow using methods from module <code>A</code> in module <code>B</code>, you need to add dependencies in <code><pluginname>.gyp</code> files
+and add <code>XW_EXPORT</code> macro to the definition of methods in module <code>A</code>.</p>
+<p>In below example, linking <code>GetNotiHandleFromJson</code> method of <code>CommonNotification</code> class in module <code>Notification</code>
+is added to the <code>Alarm</code> module.</p>
+<ol>
+<li>Add dependency in <code>.gyp</code> file in module <code>B</code>, in this example it is <code>alarm.gyp</code>:<pre class="prettyprint linenums"><code>'dependencies': [
+'../common/common.gyp:tizen_common',
+'../notification/notification.gyp:tizen_notification', # add this line
+],
+</code></pre></li>
+<li>Add <code>XW_EXPORT</code> macro available in <code>src/common/XW_Extension.h</code> file to the definition of method from module <code>A</code>:<pre class="prettyprint linenums"><code class="lang-cpp">class UserNotification : public CommonNotification {
+// ...
+XW_EXPORT static common::PlatformResult GetNotiHandleFromJson(const picojson::value& noti_val,
+ bool is_update,
+ notification_h* noti_handle);
+// ...
+}
+</code></pre>
+</li>
+<li>Add dependency in <code>.gyp</code> file in module <code>A</code>, in this example it is <code>notification.gyp</code>:<pre class="prettyprint linenums"><code>{
+'includes': [
+ '../common/common.gypi',
+],
+'targets': [
+ {
+ 'target_name': 'tizen_notification',
+ 'type': 'loadable_module',
+ 'dependencies': [
+ '../common/common.gyp:tizen_common',
+ ],
+ 'sources': [
+ # ...
+ ],
+ 'conditions': [
+ # ...
+ ],
+ 'direct_dependent_settings': { # add this property
+ 'libraries': [
+ '-ltizen_notification',
+ ],
+ },
+ },
+],
+}
+</code></pre></li>
+</ol>
+<p>To make sure you did the good work, you can list dynamic dependencies of given <code>.so</code> file with the <code>ldd</code> command:</p>
+<pre><code class="lang-sh">sh-user-3.2# ldd /usr/lib/tizen-extensions-crosswalk/libtizen_alarm.so | grep noti
+ldd: warning: you do not have execution permission for `/usr/lib/tizen-extensions-crosswalk/libtizen_alarm.so'
+libtizen_notification.so => /usr/lib/tizen-extensions-crosswalk/libtizen_notification.so (0xb6e52000) # OK!
+libnotification.so.0 => /lib/libnotification.so.0 (0xb6c93000)
+</code></pre>
<h3 id="implementation-c/asynchronous-calls">Asynchronous calls</h3>
<p>To perform asynchronous request <code>common::TaskQueue</code> component should be used.
You should use lambda expression which calls business logic and passes result to
JavaScript layer by calling <code>PostMessage(const char* msg)</code>.</p>
<p>Asynchronous response is not matched to request automatically. You should pass
<code>callbackId</code> received from JavaScript layer as an argument. It allows to
-call the appropriate user callback in JS async message handler.</p>
+call the appropriate user callback in JavaScript async message handler.</p>
<pre class="prettyprint linenums"><code class="lang-cpp">auto search = [this, args]() -> void {
// business logic
LoggerW("Data in %s object is empty", object->name);
LoggerE("Error occurred while getting data [%d]", error);
</code></pre>
+<p>Upon entering and leaving function's scope, a message should be printed with <code>DEBUG</code> priority using <code>ScopeLogger</code> macro:</p>
+<pre class="prettyprint linenums"><code class="lang-cpp">// print simply, default "Enter" log
+ScopeLogger();
+// print more detailed message
+ScopeLogger("state: %d; err: %s", (int) state, err);
+</code></pre>
<h3 id="implementation-c/error-handling">Error handling</h3>
-<p>Regarding to <a href="http://google-styleguide.googlecode.com/svn/trunk/cppguide.html#Exceptions">Google C++ Style Guide</a> we do not use Exceptions.</p>
+<p>Regarding to <a href="https://google.github.io/styleguide/cppguide.html#Exceptions">Google C++ Style Guide</a> we do not use Exceptions.</p>
<p>To deliver error conditions to JavaScript layer, that can occur in the platform,
<code>LogAndReportError</code> or <code>ReportError</code> method should be used. All available error codes are defined
in <code>common/platform_result.h</code></p>
<pre class="prettyprint linenums"><code class="lang-javascript">var test = webapis.test.ping();
console.log(test); // Hello!
</code></pre>
+<h2 id="appendices">Appendices</h2>
+<h3 id="appendices/appendix-a-type-conversion-tables">Appendix A - type conversion tables</h3>
+<h4 id="type-conversion-tables">Type conversion tables</h4>
+<p>Below tables present convertions, which are performed by <code>validateArgs</code> method in
+<code>src/utils/utils_api.js</code> file before sending data to C++ layer.</p>
+<ul>
+<li>Boolean</li>
+</ul>
+<table class="table table-striped">
+<thead>
+<tr>
+<th>Input Type</th>
+<th>Input Value</th>
+<th>Result</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>undefined</td>
+<td>undefined</td>
+<td>false</td>
+</tr>
+<tr>
+<td>null</td>
+<td>null</td>
+<td>false</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>NaN</td>
+<td>false</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>Number.POSITIVE_INFINITY</td>
+<td>true</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>Number.NEGATIVE_INFINITY</td>
+<td>true</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>-1</td>
+<td>true</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>0</td>
+<td>false</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>1</td>
+<td>true</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>3.14</td>
+<td>true</td>
+</tr>
+<tr>
+<td>String</td>
+<td>"" (Empty String)</td>
+<td>false</td>
+</tr>
+<tr>
+<td>String</td>
+<td>"0"</td>
+<td>true</td>
+</tr>
+<tr>
+<td>String</td>
+<td>"TIZEN"</td>
+<td>true</td>
+</tr>
+<tr>
+<td>Object</td>
+<td>{ name : "TIZEN" }</td>
+<td>true</td>
+</tr>
+<tr>
+<td>Function Object</td>
+<td>function () { }</td>
+<td>true</td>
+</tr>
+</tbody>
+</table>
+<ul>
+<li>Number : long</li>
+</ul>
+<table class="table table-striped">
+<thead>
+<tr>
+<th>Input Type</th>
+<th>Input Value</th>
+<th>Result</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>undefined</td>
+<td>undefined</td>
+<td>0</td>
+</tr>
+<tr>
+<td>null</td>
+<td>null</td>
+<td>0</td>
+</tr>
+<tr>
+<td>Boolean</td>
+<td>true</td>
+<td>1</td>
+</tr>
+<tr>
+<td>Boolean</td>
+<td>false</td>
+<td>0</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>NaN</td>
+<td>0</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>Number.POSITIVE_INFINITY</td>
+<td>0</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>Number.NEGATIVE_INFINITY</td>
+<td>0</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>-1</td>
+<td>-1</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>0</td>
+<td>0</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>1</td>
+<td>1</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>3.14</td>
+<td>3</td>
+</tr>
+<tr>
+<td>String</td>
+<td>"" (Empty String)</td>
+<td>0</td>
+</tr>
+<tr>
+<td>String</td>
+<td>"-1"</td>
+<td>-1</td>
+</tr>
+<tr>
+<td>String</td>
+<td>"0"</td>
+<td>0</td>
+</tr>
+<tr>
+<td>String</td>
+<td>"1"</td>
+<td>1</td>
+</tr>
+<tr>
+<td>String</td>
+<td>"3.14"</td>
+<td>3</td>
+</tr>
+<tr>
+<td>String</td>
+<td>"TIZEN"</td>
+<td>0</td>
+</tr>
+<tr>
+<td>Object</td>
+<td>{ name : "TIZEN" }</td>
+<td>0</td>
+</tr>
+<tr>
+<td>Function Object</td>
+<td>function () { }</td>
+<td>0</td>
+</tr>
+</tbody>
+</table>
+<ul>
+<li>Number : unsigned long</li>
+</ul>
+<table class="table table-striped">
+<thead>
+<tr>
+<th>Input Type</th>
+<th>Input Value</th>
+<th>Result</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>undefined</td>
+<td>undefined</td>
+<td>0</td>
+</tr>
+<tr>
+<td>null</td>
+<td>null</td>
+<td>0</td>
+</tr>
+<tr>
+<td>Boolean</td>
+<td>true</td>
+<td>1</td>
+</tr>
+<tr>
+<td>Boolean</td>
+<td>false</td>
+<td>0</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>NaN</td>
+<td>0</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>Number.POSITIVE_INFINITY</td>
+<td>0</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>Number.NEGATIVE_INFINITY</td>
+<td>0</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>-1</td>
+<td>4294967295</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>0</td>
+<td>0</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>1</td>
+<td>1</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>3.14</td>
+<td>3</td>
+</tr>
+<tr>
+<td>String</td>
+<td>"" (Empty String)</td>
+<td>0</td>
+</tr>
+<tr>
+<td>String</td>
+<td>"-1"</td>
+<td>4294967295</td>
+</tr>
+<tr>
+<td>String</td>
+<td>"0"</td>
+<td>0</td>
+</tr>
+<tr>
+<td>String</td>
+<td>"1"</td>
+<td>1</td>
+</tr>
+<tr>
+<td>String</td>
+<td>"TIZEN"</td>
+<td>0</td>
+</tr>
+<tr>
+<td>Object</td>
+<td>{ name : "TIZEN" }</td>
+<td>0</td>
+</tr>
+<tr>
+<td>Function Object</td>
+<td>function () { }</td>
+<td>0</td>
+</tr>
+</tbody>
+</table>
+<ul>
+<li>Number : unsigned long long</li>
+</ul>
+<table class="table table-striped">
+<thead>
+<tr>
+<th>Input Type</th>
+<th>Input Value</th>
+<th>Result</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>undefined</td>
+<td>undefined</td>
+<td>0</td>
+</tr>
+<tr>
+<td>null</td>
+<td>null</td>
+<td>0</td>
+</tr>
+<tr>
+<td>Boolean</td>
+<td>true</td>
+<td>1</td>
+</tr>
+<tr>
+<td>Boolean</td>
+<td>false</td>
+<td>0</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>NaN</td>
+<td>0</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>Number.POSITIVE_INFINITY</td>
+<td>0</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>Number.NEGATIVE_INFINITY</td>
+<td>0</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>-1</td>
+<td>18446744073709551615</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>0</td>
+<td>0</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>1</td>
+<td>1</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>3.14</td>
+<td>3</td>
+</tr>
+<tr>
+<td>String</td>
+<td>"" (Empty String)</td>
+<td>0</td>
+</tr>
+<tr>
+<td>String</td>
+<td>"-1"</td>
+<td>18446744073709551615</td>
+</tr>
+<tr>
+<td>String</td>
+<td>"0"</td>
+<td>0</td>
+</tr>
+<tr>
+<td>String</td>
+<td>"1"</td>
+<td>1</td>
+</tr>
+<tr>
+<td>String</td>
+<td>"TIZEN"</td>
+<td>0</td>
+</tr>
+<tr>
+<td>Object</td>
+<td>{ name : "TIZEN" }</td>
+<td>0</td>
+</tr>
+<tr>
+<td>Function Object</td>
+<td>function () { }</td>
+<td>0</td>
+</tr>
+</tbody>
+</table>
+<ul>
+<li>Number : byte [-128, 127]</li>
+</ul>
+<table class="table table-striped">
+<thead>
+<tr>
+<th>Input Type</th>
+<th>Input Value</th>
+<th>Result</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>undefined</td>
+<td>undefined</td>
+<td>0</td>
+</tr>
+<tr>
+<td>null</td>
+<td>null</td>
+<td>0</td>
+</tr>
+<tr>
+<td>Boolean</td>
+<td>true</td>
+<td>1</td>
+</tr>
+<tr>
+<td>Boolean</td>
+<td>false</td>
+<td>0</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>NaN</td>
+<td>0</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>Number.POSITIVE_INFINITY</td>
+<td>0</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>Number.NEGATIVE_INFINITY</td>
+<td>0</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>-1</td>
+<td>-1</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>0</td>
+<td>0</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>1</td>
+<td>1</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>3.14</td>
+<td>3</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>-128</td>
+<td>-128</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>-192</td>
+<td>64</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>-256</td>
+<td>0</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>127</td>
+<td>127</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>128</td>
+<td>-128</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>256</td>
+<td>0</td>
+</tr>
+<tr>
+<td>String</td>
+<td>"" (Empty String)</td>
+<td>0</td>
+</tr>
+<tr>
+<td>String</td>
+<td>"0"</td>
+<td>0</td>
+</tr>
+<tr>
+<td>String</td>
+<td>"1"</td>
+<td>1</td>
+</tr>
+<tr>
+<td>String</td>
+<td>"256"</td>
+<td>0</td>
+</tr>
+<tr>
+<td>String</td>
+<td>"TIZEN"</td>
+<td>0</td>
+</tr>
+<tr>
+<td>Object</td>
+<td>{ name : "TIZEN" }</td>
+<td>0</td>
+</tr>
+<tr>
+<td>Function Object</td>
+<td>function () { }</td>
+<td>0</td>
+</tr>
+</tbody>
+</table>
+<ul>
+<li>Number : double</li>
+</ul>
+<table class="table table-striped">
+<thead>
+<tr>
+<th>Input Type</th>
+<th>Input Value</th>
+<th>Result</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>undefined</td>
+<td>undefined</td>
+<td>TypeMismatchError</td>
+</tr>
+<tr>
+<td>null</td>
+<td>null</td>
+<td>0</td>
+</tr>
+<tr>
+<td>Boolean</td>
+<td>true</td>
+<td>1</td>
+</tr>
+<tr>
+<td>Boolean</td>
+<td>false</td>
+<td>0</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>NaN</td>
+<td>TypeMismatchError</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>Number.POSITIVE_INFINITY</td>
+<td>TypeMismatchError</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>Number.NEGATIVE_INFINITY</td>
+<td>TypeMismatchError</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>-1</td>
+<td>-1</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>0</td>
+<td>0</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>1</td>
+<td>1</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>3.14</td>
+<td>3.14</td>
+</tr>
+<tr>
+<td>String</td>
+<td>"" (Empty String)</td>
+<td>0</td>
+</tr>
+<tr>
+<td>String</td>
+<td>"0"</td>
+<td>0</td>
+</tr>
+<tr>
+<td>String</td>
+<td>"-3.14"</td>
+<td>-3.14</td>
+</tr>
+<tr>
+<td>String</td>
+<td>"3.14"</td>
+<td>3.14</td>
+</tr>
+<tr>
+<td>String</td>
+<td>"TIZEN"</td>
+<td>TypeMismatchError</td>
+</tr>
+<tr>
+<td>Object</td>
+<td>{ name : "TIZEN" }</td>
+<td>TypeMismatchError</td>
+</tr>
+<tr>
+<td>Function Object</td>
+<td>function () { }</td>
+<td>TypeMismatchError</td>
+</tr>
+</tbody>
+</table>
+<ul>
+<li>String</li>
+</ul>
+<table class="table table-striped">
+<thead>
+<tr>
+<th>Input Type</th>
+<th>Input Value</th>
+<th>Result</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>undefined</td>
+<td>undefined</td>
+<td>"undefined"</td>
+</tr>
+<tr>
+<td>null</td>
+<td>null</td>
+<td>"null"</td>
+</tr>
+<tr>
+<td>Boolean</td>
+<td>true</td>
+<td>"true"</td>
+</tr>
+<tr>
+<td>Boolean</td>
+<td>false</td>
+<td>"false"</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>NaN</td>
+<td>"NaN"</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>Number.POSITIVE_INFINITY</td>
+<td>"Infinity"</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>Number.NEGATIVE_INFINITY</td>
+<td>"-Infinity"</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>-1</td>
+<td>"-1"</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>0</td>
+<td>"0"</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>1</td>
+<td>"1"</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>3.14</td>
+<td>"3.14"</td>
+</tr>
+<tr>
+<td>Object</td>
+<td>{ }</td>
+<td>"[object Object]"</td>
+</tr>
+<tr>
+<td>Function Object</td>
+<td>function () { }</td>
+<td>"function () { }"</td>
+</tr>
+</tbody>
+</table>
+<ul>
+<li>Platform Object</li>
+</ul>
+<table class="table table-striped">
+<thead>
+<tr>
+<th>Input Type</th>
+<th>Input Value</th>
+<th>Result</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>undefined</td>
+<td>undefined</td>
+<td>TypeMismatchError</td>
+</tr>
+<tr>
+<td>null</td>
+<td>null</td>
+<td>nullable: null; non-nullable: TypeMismatchError</td>
+</tr>
+<tr>
+<td>Boolean</td>
+<td>true</td>
+<td>TypeMismatchError</td>
+</tr>
+<tr>
+<td>Boolean</td>
+<td>false</td>
+<td>TypeMismatchError</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>NaN</td>
+<td>TypeMismatchError</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>0</td>
+<td>TypeMismatchError</td>
+</tr>
+<tr>
+<td>String</td>
+<td>"TIZEN"</td>
+<td>TypeMismatchError</td>
+</tr>
+<tr>
+<td>Object</td>
+<td>{}</td>
+<td>TypeMismatchError</td>
+</tr>
+<tr>
+<td>Function Object</td>
+<td>function () { }</td>
+<td>TypeMismatchError</td>
+</tr>
+</tbody>
+</table>
+<ul>
+<li>Function Object</li>
+</ul>
+<table class="table table-striped">
+<thead>
+<tr>
+<th>Input Type</th>
+<th>Input Value</th>
+<th>Result</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>undefined</td>
+<td>undefined</td>
+<td>TypeMismatchError</td>
+</tr>
+<tr>
+<td>null</td>
+<td>null</td>
+<td>nullable: null; non-nullable: TypeMismatchError</td>
+</tr>
+<tr>
+<td>Boolean</td>
+<td>true</td>
+<td>TypeMismatchError</td>
+</tr>
+<tr>
+<td>Boolean</td>
+<td>false</td>
+<td>TypeMismatchError</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>NaN</td>
+<td>TypeMismatchError</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>0</td>
+<td>TypeMismatchError</td>
+</tr>
+<tr>
+<td>String</td>
+<td>"TIZEN"</td>
+<td>TypeMismatchError</td>
+</tr>
+<tr>
+<td>Object</td>
+<td>{ }</td>
+<td>TypeMismatchError</td>
+</tr>
+</tbody>
+</table>
+<ul>
+<li>Array Object</li>
+</ul>
+<table class="table table-striped">
+<thead>
+<tr>
+<th>Input Type</th>
+<th>Input Value</th>
+<th>Result</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>undefined</td>
+<td>undefined</td>
+<td>TypeMismatchError</td>
+</tr>
+<tr>
+<td>null</td>
+<td>null</td>
+<td>nullable: null; non-nullable: TypeMismatchError</td>
+</tr>
+<tr>
+<td>Boolean</td>
+<td>true</td>
+<td>TypeMismatchError</td>
+</tr>
+<tr>
+<td>Boolean</td>
+<td>false</td>
+<td>TypeMismatchError</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>NaN</td>
+<td>TypeMismatchError</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>0</td>
+<td>TypeMismatchError</td>
+</tr>
+<tr>
+<td>String</td>
+<td>"TIZEN"</td>
+<td>TypeMismatchError</td>
+</tr>
+<tr>
+<td>Object</td>
+<td>{ }</td>
+<td>TypeMismatchError</td>
+</tr>
+<tr>
+<td>Function Object</td>
+<td>function () { }</td>
+<td>TypeMismatchError</td>
+</tr>
+</tbody>
+</table>
+<ul>
+<li>Dictionary</li>
+</ul>
+<table class="table table-striped">
+<thead>
+<tr>
+<th>Input Type</th>
+<th>Input Value</th>
+<th>Result</th>
+<th>Comment</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>undefined</td>
+<td>undefined</td>
+<td>TypeMismatchError</td>
+</tr>
+<tr>
+<td>null</td>
+<td>null</td>
+<td>nullable: null; non-nullable: TypeMismatchError</td>
+</tr>
+<tr>
+<td>Boolean</td>
+<td>true</td>
+<td>TypeMismatchError</td>
+</tr>
+<tr>
+<td>Boolean</td>
+<td>false</td>
+<td>TypeMismatchError</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>NaN</td>
+<td>TypeMismatchError</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>0</td>
+<td>TypeMismatchError</td>
+</tr>
+<tr>
+<td>String</td>
+<td>"TIZEN"</td>
+<td>TypeMismatchError</td>
+</tr>
+<tr>
+<td>Object</td>
+<td>{ }</td>
+<td>{}</td>
+<td>No exception is thrown</td>
+</tr>
+<tr>
+<td>Function Object</td>
+<td>function () { }</td>
+<td>function () { }</td>
+<td>No exception is thrown</td>
+</tr>
+</tbody>
+</table>
+<ul>
+<li>Octet [0, 255]</li>
+</ul>
+<table class="table table-striped">
+<thead>
+<tr>
+<th>Input Type</th>
+<th>Input Value</th>
+<th>Result</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>undefined</td>
+<td>undefined</td>
+<td>0</td>
+</tr>
+<tr>
+<td>null</td>
+<td>null</td>
+<td>0</td>
+</tr>
+<tr>
+<td>Boolean</td>
+<td>true</td>
+<td>1</td>
+</tr>
+<tr>
+<td>Boolean</td>
+<td>false</td>
+<td>0</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>NaN</td>
+<td>0</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>Number.POSITIVE_INFINITY</td>
+<td>0</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>Number.NEGATIVE_INFINITY</td>
+<td>0</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>-1</td>
+<td>255</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>0</td>
+<td>0</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>1</td>
+<td>1</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>3.14</td>
+<td>3</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>-128</td>
+<td>128</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>-192</td>
+<td>64</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>-256</td>
+<td>0</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>256</td>
+<td>0</td>
+</tr>
+<tr>
+<td>String</td>
+<td>"" (Empty String)</td>
+<td>0</td>
+</tr>
+<tr>
+<td>String</td>
+<td>"0"</td>
+<td>0</td>
+</tr>
+<tr>
+<td>String</td>
+<td>"1"</td>
+<td>1</td>
+</tr>
+<tr>
+<td>String</td>
+<td>"256"</td>
+<td>0</td>
+</tr>
+<tr>
+<td>String</td>
+<td>"TIZEN"</td>
+<td>0</td>
+</tr>
+<tr>
+<td>Object</td>
+<td>{ name : "TIZEN" }</td>
+<td>0</td>
+</tr>
+<tr>
+<td>Function Object</td>
+<td>function () { }</td>
+<td>0</td>
+</tr>
+</tbody>
+</table>
+<ul>
+<li>Enum</li>
+</ul>
+<table class="table table-striped">
+<thead>
+<tr>
+<th>Input Type</th>
+<th>Input Value</th>
+<th>Result</th>
+<th>Comment</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>undefined</td>
+<td>undefined</td>
+<td>TypeMismatchError</td>
+<td>unless "undefined" is on the list of the Enum values</td>
+</tr>
+<tr>
+<td>null</td>
+<td>null</td>
+<td>TypeMismatchError</td>
+<td>unless "null" is one of the Enum values</td>
+</tr>
+<tr>
+<td>Number</td>
+<td>0</td>
+<td>TypeMismatchError</td>
+<td>unless "0" is one of the Enum values</td>
+</tr>
+<tr>
+<td>Boolean</td>
+<td>true</td>
+<td>TypeMismatchError</td>
+<td>unless "true" is one of the Enum values</td>
+</tr>
+<tr>
+<td>String</td>
+<td>"TIZEN"</td>
+<td>TypeMismatchError</td>
+<td>unless "TIZEN" is one of the Enum values</td>
+</tr>
+<tr>
+<td>String</td>
+<td>any of the Enum values</td>
+<td>given string</td>
+<td>Enum defines valid values, any of those values can be used and are accepted without conversion</td>
+</tr>
+<tr>
+<td>Object</td>
+<td>{ }</td>
+<td>TypeMismatchError</td>
+</tr>
+</tbody>
+</table>
+<h3 id="appendices/appendix-b-javascript-code-example-style-guide">Appendix B - Javascript code example style guide</h3>
+<h4 id="code-example-style-guide">Code Example Style Guide</h4>
+<p>Below guide lists rules of writing example code placed in the WIDL files.</p>
+<p><strong>Whitespaces</strong></p>
+<ul>
+<li>Use only spaces (do not use tabs), one level indent has two spaces</li>
+<li>No whitespace at the end of line</li>
+<li>One extra space after keywords which use round brackets (if, for, while, switch, catch, …)</li>
+<li>Add space between variables and operators</li>
+<li>Initialization lists<ul>
+<li>Space after colon but not before</li>
+<li>Space after comma</li>
+</ul>
+</li>
+</ul>
+<p><strong>Comments</strong></p>
+<ul>
+<li>Use double slash // (do not use /<em> </em>/)</li>
+<li>Start sentence with capital letter</li>
+<li>Do not use dot at the end</li>
+</ul>
+<pre class="prettyprint linenums"><code class="lang-js">// This is a simple comment
+</code></pre>
+<p><strong>Brackets</strong></p>
+<ul>
+<li>Body brackets<ul>
+<li>Opening and closing brackets in new lines</li>
+</ul>
+</li>
+<li>No extra whitespace inside brackets (after opening nor before closing)</li>
+</ul>
+<pre class="prettyprint linenums"><code class="lang-js">try
+{
+ var messages = ["A", "B"];
+}
+catch (err)
+{
+ console.log("Error: " + err.message);
+}
+</code></pre>
+<p><strong>Strings</strong></p>
+<ul>
+<li>Use only quotation marks (“), do not use apostrophes (‘) to create strings</li>
+</ul>
+<p><strong>console.log()</strong></p>
+<ul>
+<li>Start log with capital letter</li>
+<li>Do not use dots</li>
+<li>Add space after colon</li>
+</ul>
+<pre class="prettyprint linenums"><code class="lang-js">console.log(“This is example error: “ + err.message);
+</code></pre>
+<p><strong>Multi-line</strong></p>
+<ul>
+<li>Each line should not be more than 100 characters long</li>
+<li>Indentation in second line must match opening bracket</li>
+</ul>
+<pre class="prettyprint linenums"><code class="lang-js">console.log("This is console log information error: " + error.message +
+ " and there is more”);
+</code></pre>
+<p><strong>Functions with function as an argument</strong></p>
+<ul>
+<li>Name of the function should be written in line with previous function's closing bracket</li>
+<li>Other parameters can be put in the same line as function's closing bracket</li>
+</ul>
+<pre class="prettyprint linenums"><code class="lang-js">functionCalculate("First argument", function(e)
+{
+ console.log("Information: " + e.message);
+}, function(e)
+{
+ console.log("Error: " + e.message);
+}, "Last argument");
+</code></pre>
+<p><strong>Statement separation</strong></p>
+<ul>
+<li>Each statement has to be in new line and has to end with semicolon</li>
+</ul>
</div>
<script src="js/mootools-yui-compressed.js"></script>
--- /dev/null
+### Appendix A - type conversion tables
+
+#### Type conversion tables
+
+Below tables present convertions, which are performed by ``validateArgs`` method in
+``src/utils/utils_api.js`` file before sending data to C++ layer.
+
+* Boolean
+
+|Input Type|Input Value|Result|
+|----------|-----------|------|
+|undefined|undefined|false|
+|null|null|false|
+|Number|NaN|false|
+|Number|Number.POSITIVE_INFINITY|true|
+|Number|Number.NEGATIVE_INFINITY|true|
+|Number|-1|true|
+|Number|0|false|
+|Number|1|true|
+|Number|3.14|true|
+|String|"" (Empty String)|false|
+|String|"0"|true|
+|String|"TIZEN"|true|
+|Object|{ name : "TIZEN" }|true|
+|Function Object|function () { }|true|
+
+* Number : long
+
+|Input Type|Input Value|Result|
+|----------|-----------|------|
+|undefined|undefined|0|
+|null|null|0|
+|Boolean|true|1|
+|Boolean|false|0|
+|Number|NaN|0|
+|Number|Number.POSITIVE_INFINITY|0|
+|Number|Number.NEGATIVE_INFINITY|0|
+|Number|-1|-1|
+|Number|0|0|
+|Number|1|1|
+|Number|3.14|3|
+|String|"" (Empty String)|0|
+|String|"-1"|-1|
+|String|"0"|0|
+|String|"1"|1|
+|String|"3.14"|3|
+|String|"TIZEN"|0|
+|Object|{ name : "TIZEN" }|0|
+|Function Object|function () { }|0|
+
+* Number : unsigned long
+
+|Input Type|Input Value|Result|
+|----------|-----------|------|
+|undefined|undefined|0|
+|null|null|0|
+|Boolean|true|1|
+|Boolean|false|0|
+|Number|NaN|0|
+|Number|Number.POSITIVE_INFINITY|0|
+|Number|Number.NEGATIVE_INFINITY|0|
+|Number|-1|4294967295|
+|Number|0|0|
+|Number|1|1|
+|Number|3.14|3|
+|String|"" (Empty String)|0|
+|String|"-1"|4294967295|
+|String|"0"|0|
+|String|"1"|1|
+|String|"TIZEN"|0|
+|Object|{ name : "TIZEN" }|0|
+|Function Object|function () { }|0|
+
+* Number : unsigned long long
+
+|Input Type|Input Value|Result|
+|----------|-----------|------|
+|undefined|undefined|0|
+|null|null|0|
+|Boolean|true|1|
+|Boolean|false|0|
+|Number|NaN|0|
+|Number|Number.POSITIVE_INFINITY|0|
+|Number|Number.NEGATIVE_INFINITY|0|
+|Number|-1|18446744073709551615|
+|Number|0|0|
+|Number|1|1|
+|Number|3.14|3|
+|String|"" (Empty String)|0|
+|String|"-1"|18446744073709551615|
+|String|"0"|0|
+|String|"1"|1|
+|String|"TIZEN"|0|
+|Object|{ name : "TIZEN" }|0|
+|Function Object|function () { }|0|
+
+* Number : byte [-128, 127]
+
+|Input Type|Input Value|Result|
+|----------|-----------|------|
+|undefined|undefined|0|
+|null|null|0|
+|Boolean|true|1|
+|Boolean|false|0|
+|Number|NaN|0|
+|Number|Number.POSITIVE_INFINITY|0|
+|Number|Number.NEGATIVE_INFINITY|0|
+|Number|-1|-1|
+|Number|0|0|
+|Number|1|1|
+|Number|3.14|3|
+|Number|-128|-128|
+|Number|-192|64|
+|Number|-256|0|
+|Number|127|127|
+|Number|128|-128|
+|Number|256|0|
+|String|"" (Empty String)|0|
+|String|"0"|0|
+|String|"1"|1|
+|String|"256"|0|
+|String|"TIZEN"|0|
+|Object|{ name : "TIZEN" }|0|
+|Function Object|function () { }|0|
+
+* Number : double
+
+|Input Type|Input Value|Result|
+|----------|-----------|------|
+|undefined|undefined|TypeMismatchError|
+|null|null|0|
+|Boolean|true|1|
+|Boolean|false|0|
+|Number|NaN|TypeMismatchError|
+|Number|Number.POSITIVE_INFINITY|TypeMismatchError|
+|Number|Number.NEGATIVE_INFINITY|TypeMismatchError|
+|Number|-1|-1|
+|Number|0|0|
+|Number|1|1|
+|Number|3.14|3.14|
+|String|"" (Empty String)|0|
+|String|"0"|0|
+|String|"-3.14"|-3.14|
+|String|"3.14"|3.14|
+|String|"TIZEN"|TypeMismatchError|
+|Object|{ name : "TIZEN" }|TypeMismatchError|
+|Function Object|function () { }|TypeMismatchError|
+
+* String
+
+|Input Type|Input Value|Result|
+|----------|-----------|------|
+|undefined|undefined|"undefined"|
+|null|null|"null"|
+|Boolean|true|"true"|
+|Boolean|false|"false"|
+|Number|NaN|"NaN"|
+|Number|Number.POSITIVE_INFINITY|"Infinity"|
+|Number|Number.NEGATIVE_INFINITY|"-Infinity"|
+|Number|-1|"-1"|
+|Number|0|"0"|
+|Number|1|"1"|
+|Number|3.14|"3.14"|
+|Object|{ }|"[object Object]"|
+|Function Object|function () { }|"function () { }"|
+
+* Platform Object
+
+|Input Type|Input Value|Result|
+|----------|-----------|------|
+|undefined|undefined|TypeMismatchError|
+|null|null|nullable: null; non-nullable: TypeMismatchError|
+|Boolean|true|TypeMismatchError|
+|Boolean|false|TypeMismatchError|
+|Number|NaN|TypeMismatchError|
+|Number|0|TypeMismatchError|
+|String|"TIZEN"|TypeMismatchError|
+|Object|{}|TypeMismatchError|
+|Function Object|function () { }|TypeMismatchError|
+
+* Function Object
+
+|Input Type|Input Value|Result|
+|----------|-----------|------|
+|undefined|undefined|TypeMismatchError|
+|null|null|nullable: null; non-nullable: TypeMismatchError|
+|Boolean|true|TypeMismatchError|
+|Boolean|false|TypeMismatchError|
+|Number|NaN|TypeMismatchError|
+|Number|0|TypeMismatchError|
+|String|"TIZEN"|TypeMismatchError|
+|Object|{ }|TypeMismatchError|
+
+* Array Object
+
+|Input Type|Input Value|Result|
+|----------|-----------|------|
+|undefined|undefined|TypeMismatchError|
+|null|null|nullable: null; non-nullable: TypeMismatchError|
+|Boolean|true|TypeMismatchError|
+|Boolean|false|TypeMismatchError|
+|Number|NaN|TypeMismatchError|
+|Number|0|TypeMismatchError|
+|String|"TIZEN"|TypeMismatchError|
+|Object|{ }|TypeMismatchError|
+|Function Object|function () { }|TypeMismatchError|
+
+* Dictionary
+
+|Input Type|Input Value|Result|Comment|
+|----------|-----------|------|-------|
+|undefined|undefined|TypeMismatchError|
+|null|null|nullable: null; non-nullable: TypeMismatchError|
+|Boolean|true|TypeMismatchError|
+|Boolean|false|TypeMismatchError|
+|Number|NaN|TypeMismatchError|
+|Number|0|TypeMismatchError|
+|String|"TIZEN"|TypeMismatchError|
+|Object|{ }|{}|No exception is thrown
+|Function Object|function () { }|function () { }|No exception is thrown
+
+* Octet [0, 255]
+
+|Input Type|Input Value|Result|
+|----------|-----------|------|
+|undefined|undefined|0|
+|null|null|0|
+|Boolean|true|1|
+|Boolean|false|0|
+|Number|NaN|0|
+|Number|Number.POSITIVE_INFINITY|0|
+|Number|Number.NEGATIVE_INFINITY|0|
+|Number|-1|255|
+|Number|0|0|
+|Number|1|1|
+|Number|3.14|3|
+|Number|-128|128|
+|Number|-192|64|
+|Number|-256|0|
+|Number|256|0|
+|String|"" (Empty String)|0|
+|String|"0"|0|
+|String|"1"|1|
+|String|"256"|0|
+|String|"TIZEN"|0|
+|Object|{ name : "TIZEN" }|0|
+|Function Object|function () { }|0|
+
+* Enum
+
+|Input Type|Input Value|Result|Comment|
+|----------|-----------|------|-------|
+|undefined|undefined|TypeMismatchError|unless "undefined" is on the list of the Enum values
+|null|null|TypeMismatchError|unless "null" is one of the Enum values
+|Number|0|TypeMismatchError|unless "0" is one of the Enum values
+|Boolean|true|TypeMismatchError|unless "true" is one of the Enum values
+|String|"TIZEN"|TypeMismatchError|unless "TIZEN" is one of the Enum values
+|String|any of the Enum values|given string|Enum defines valid values, any of those values can be used and are accepted without conversion
+|Object|{ }|TypeMismatchError|
projects / platform / core / api / webapi-plugins.git / commitdiff