<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
	"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<!--
    FILE INFORMATION

    Description
       Guidelines for the handling and usage for WIDL (Web IDL) SUPporting files

    OMA Permanent Document
       File: OMA-INF-HTM_SupportFiles_WIDL-20110808
       Type: Text

    Private Reachable Information
       Path: http://www.openmobilealliance.org/ftp/REL/Procs
       Name: SupportFiles_WIDL-v1_0.htm

    NORMATIVE INFORMATION

    This File provides guidance on WIDL SUP files.  There is no 
    associated normative material.
	
    LEGAL DISCLAIMER

    Use of this document is subject to all of the terms and conditions
    of the Use Agreement located at
	http://www.openmobilealliance.org/UseAgreement.html

    You may use this document or any part of the document for internal
    or educational purposes only, provided you do not modify, edit or
    take out of context the information in this document in any manner.
    Information contained in this document may be used, at your sole
    risk, for any purposes.

    You may not use this document in any other manner without the prior
    written permission of the Open Mobile Alliance.  The Open Mobile
    Alliance authorizes you to copy this document, provided that you
    retain all copyright and other proprietary notices contained in the
    original materials on any copies of the materials and that you
    comply strictly with these terms.  This copyright permission does
    not constitute an endorsement of the products or services.  The
    Open Mobile Alliance assumes no responsibility for errors or
    omissions in this document.

    Each Open Mobile Alliance member has agreed to use reasonable
    endeavors to inform the Open Mobile Alliance in a timely manner of
    Essential IPR as it becomes aware that the Essential IPR is related
    to the prepared or published specification.  However, the members
    do not have an obligation to conduct IPR searches.  The declared
    Essential IPR is publicly available to members and non-members of
    the Open Mobile Alliance and may be found on the "OMA IPR
    Declarations" list at http://www.openmobilealliance.org/ipr.html.
    The Open Mobile Alliance has not conducted an independent IPR review
    of this document and the information contained herein, and makes no
    representations or warranties regarding third party IPR, including
    without limitation patents, copyrights or trade secret rights.  This
    document may contain inventions for which you must obtain licenses
    from third parties before making, using or selling the inventions.
    Defined terms above are set forth in the schedule to the Open Mobile
    Alliance Application Form.

    NO REPRESENTATIONS OR WARRANTIES (WHETHER EXPRESS OR IMPLIED) ARE
    MADE BY THE OPEN MOBILE ALLIANCE OR ANY OPEN MOBILE ALLIANCE MEMBER
    OR ITS AFFILIATES REGARDING ANY OF THE IPR'S REPRESENTED ON THE "OMA
    IPR DECLARATIONS" LIST, INCLUDING, BUT NOT LIMITED TO THE ACCURACY,
    COMPLETENESS, VALIDITY OR RELEVANCE OF THE INFORMATION OR WHETHER OR
    NOT SUCH RIGHTS ARE ESSENTIAL OR NON-ESSENTIAL.

    THE OPEN MOBILE ALLIANCE IS NOT LIABLE FOR AND HEREBY DISCLAIMS ANY
    DIRECT, INDIRECT, PUNITIVE, SPECIAL, INCIDENTAL, CONSEQUENTIAL, OR
    EXEMPLARY DAMAGES ARISING OUT OF OR IN CONNECTION WITH THE USE OF
    DOCUMENTS AND THE INFORMATION CONTAINED IN THE DOCUMENTS.

    Copyright 2010 Open Mobile Alliance Ltd.  All Rights Reserved.
    Used with the permission of the Open Mobile Alliance Ltd. under the
    terms set forth above.
-->

<head>
	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
	<title>Guidelines for Support Files - Web Interface Definition Language Document (WIDL)</title>
	<meta name="description" content="Guidelines for Support Files - Web Interface Definition Language Document (WIDL)" />
	<link rel="stylesheet" href="http://member.openmobilealliance.org/ftp/rel/P-n-g/../../GI_template/accessible_StaticPages.css" type="text/css" />
	<link rel="stylesheet" href="http://member.openmobilealliance.org/ftp/rel/P-n-g/ProcStyle.css" type="text/css" />
	<style type="text/css">
		h2 a, a:hover, a:visited{
			color: #993333;
			font-family: Tahoma,Verdana,"Myriad Web",Syntax,sans-serif;
			font-weight: bold;
			text-decoration:none;
		}
		A:hover { COLOR: #993333; }
	</style>
</head>

<body>

<!--  Document Header  -->

<table border="0" width="100%" cellspacing="0" cellpadding="0">
	<tr>
		<td align="left"><img src="imgOMAlogo.gif" border="0" alt=""/></td>
		<td align="right">
			<p class="dochead">Guidelines for Support Files - Web Interface Definition Language (WIDL)</p>
			<p class="docfile">OMA-INF-HTM_SupportFiles_WIDL-XXXXX</p>
		</td>
	</tr>
</table>

<!--  Navigation Bar  -->

<table width="100%" cellspacing="0" cellpadding="0">
	<tr><td colspan="2"><img height="5" width="100%" src="http://member.openmobilealliance.org/ftp/rel/P-n-g/imgBitWht.gif" border="0" alt=""/></td></tr>
	<tr><td colspan="2"><img height="5" width="100%" src="http://member.openmobilealliance.org/ftp/rel/P-n-g/imgBitSep.gif" border="0" alt=""/></td></tr>
	<tr>
		<td class="navbar">
			<a href="Procs-n-Guides.htm">Procs-n-Guides</a>&nbsp;>>
			<a href="SupportFiles.htm">SupportFiles</a>&nbsp;>>
			<b>WIDL</b>
		</td>
		<td class="navbar" align="right">Updated: 05 Aug 2011</td>
	</tr>
	<tr><td colspan="2"><img height="5" width="100%" src="http://member.openmobilealliance.org/ftp/rel/P-n-g/imgBitSep.gif" border="0" alt=""/></td></tr>
	<tr><td colspan="2"><img height="5" width="100%" src="http://member.openmobilealliance.org/ftp/rel/P-n-g/imgBitWht.gif" border="0" alt=""/></td></tr>
</table>

<!--  Start of Document  -->

<h1>Web Interface Definition Language (WIDL) Files</h1>

<h3>Contents</h3>
<ul>
<li><a href="#desc">Description of WIDL Files</a></li>
<li><a href="#namesp">Namespaces in OMA WIDL Files</a></li>
<li><a href="#naming">Naming of OMA WIDL Files</a></li>
<li><a href="#handling">Handling of WIDL Files</a></li>
<li><a href="#package">WIDL Files in Enabler Releases</a></li>
<li><a href="#public">Getting WIDL Files into Public Directory</a></li>
<li><a href="#header">Embedded Header in OMA WIDL Files</a></li>
<li><a href="#reference">References</a></li>
</ul>

<h2><a name="desc">Description of Web IDL Files</a></h2>
<p>
Web Interface Definition Language (WIDL) files provide a mechanism to describe interfaces in a language independent manner
and that are intended to be implemented in web browsers and other contexts.
Web IDL is a description language specified by <a href="#ref1">[1]</a>.
</p>

<p>
Web IDL is an IDL variant with a number of features that allow the behavior of common script 
objects in the web platform to be specified more readily. Interfaces described with Web IDL can be implemented in
specific execution environments (i.e. ECMASCript, Java, etc); WIDL file can be use by tools to generate automatically specific language implementation stub.<br/>
WIDL files can be also used to generate automatically documentation in different target format (i.e. HTML pages): this can be achieve including descriptions in widl file as comment, following specific format which can be handled by <i>documentation generator tools</i> (i.e., Doxygen <a href="#ref2">[2]</a>).
</p>
<p>
For OMA, WIDL files are normally loaded and available in a proscribed location.  That location is:
</p>
<pre>
<a href="http://www.openmobilealliance.org/tech/profiles/" target="_blank">http://www.openmobilealliance.org/tech/profiles/</a>
</pre>


<br/>
<h2><a name="namesp">Qualified Identifier in OMA WIDL Files</a></h2>
<p>
A WIDL file generally should contain a <i>module</i> definition; each module is identified by a <i>qualified name</i> determined by rules described in <a href="#ref1">[1]</a>;
this <i>qualified name</i> should be unique for each module, in order to avoid conflicts with different specifications.
</p>

<br/>
<h2><a name="naming">Naming of WIDL Files</a></h2>
<p>The public readable WIDL file names are generally shorter and simpler than OMA permanent documents.  There is generally no need to have superfluous text in the file names and they usually avoid constructs like date strings and document status.  As a consequence, the following file name construction scheme is used for the 'SUP' files in the permanent document area and public file names.
</p>
<pre>
&nbsp;&nbsp;&nbsp;&nbsp;Perm Doc - <b>OMA-SUP-WIDL_</b><i>{publicNamePart}</i><b>-V</b><i>{versionNumbers}</i><b>-{DateStr}-{State}.txt</b>
&nbsp;&nbsp;&nbsp;&nbsp;Public   - <i>{publicNamePart}</i><b>-v</b><i>{versionNumbers}</i><b>.widl</b>
</pre>
<p>
Where possible, the {publicNamePart} is derived from the specific parts of the qualified identifier.
The following is an example of the desired relationship.
</p>
<pre>
&nbsp;&nbsp;&nbsp;&nbsp;identifier&nbsp;&nbsp;&nbsp;- <span style="color:red;font-weight:bold;">::FOO</span>
&nbsp;&nbsp;&nbsp;&nbsp;perm doc&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;- <span style="font-weight:bold;">OMA-SUP-WIDL_<span style="color:red;">foo</span>-V<span style="color:red;">1_0</span>-20110826-C.txt</span>
&nbsp;&nbsp;&nbsp;&nbsp;public doc&nbsp;&nbsp;&nbsp;- <span style="font-weight:bold;"><span style="color:red;">foo</span>-v<span style="color:red;">1_0</span>.widl</span>
</pre>

<br/>
<h2><a name="handling">Handling of WIDL Files</a></h2>
<p>
The WIDL SUP file is maintained in the OMA Portal Permanent Document area as with the specifications in the enabler.  It is subject to revision using the normal CR process.  Application of CRs to a WIDL SUP file will result in an updated file with the appropriate date associated.
</p>
<p>
The WIDL SUP file should be treated as if it has the ".txt" file extension while in the permanent doc area.  Though it will be stored in zip format, it will simplify usage and edit.
</p>
<p>
References to OMA defined WIDLs in specifications should be done <span style="color:blue;font-style:italic;">(This needs to be aligned with the Referencing Policy)</span> to the developed SUP file.  This will permit easy reference and retrieval of current or past versions using the normal PD file mechanisms.  An example reference would look like:
</p>
<center>
	<table border="1">
		<tr><td style="font-size:10px;font-weight:bold;">[FOO_WIDL]&nbsp;&nbsp;&nbsp;</td><td style="font-size:10px;">FOO API Description, Version 1.0, Open Mobile Alliance,<br/>OMA-SUP-WIDL_foo-V1_0, URL:http://www.openmobilealliance.org/&nbsp;&nbsp;&nbsp;&nbsp;</td></tr>
	</table>
</center>

<br/>
<h2><a name="package">WIDL Files in Enabler Releases</a></h2>
<p>
As with Specifications, WIDLs are normally components of an Enabler Release.
So, similar to how Specifications are released, WIDL files are packaged in the Enabler Release Package to be made available.<br/>
This packaging also includes appropriate linkages in the ERELD.</p>
<p>
The following is an example WIDL entry in the ERELD:
</p>
<center>
	<table border="1">
		<tr bgcolor="cyan">
		  <td colspan="3" style="font-size:10px;font-weight:bold;">Supporting Files</td>
		</tr>
		<tr>
		  <td style="font-size:10px;font-weight:bold;">[FOO_WIDL]&nbsp;&nbsp;&nbsp;&nbsp;</td>
		  <td style="font-size:10px;">OMA-SUP-WIDL_foo-V1_0-20110826-C&nbsp;&nbsp;&nbsp;&nbsp;</td>
		  <td style="font-size:10px;">
		This WIDL describes the foo API FOO Enabler.<br/>
		Working file in WIDL directory:<br/>
		&nbsp;&nbsp;&nbsp;file: foo-v1_0.widl<br/>
		&nbsp;&nbsp;&nbsp;path: http://www.openmobilealliance.org/tech/profiles/&nbsp;&nbsp;&nbsp;&nbsp;
		  </td>
		</tr>
	</table>
</center>

<br/>
<h2><a name="public">Getting WIDL Files into Public Directory</a></h2>
<p>
As the public reachable WIDL files permit tools to create stub for API interfaces, it is sometimes required to get a copy of the WIDL file into the public reachable directory.
</p>
<p>
The primary means of publishing the WIDL file is the advancement of the enabler release to Candidate.
At that time, the DSO will review the ERELD and for each WIDL listed, copy the material in the listed SUP file to the named version of the public WIDL file.  This will also result in the WIDL file being listed in the WIDL index page.
</p>
<p>
The DSO would perform the needed copy action like:
</p>
<pre>
Copy from <b>OMA-SUP-WIDL_foo-V1_0-20110826-C.txt</b><br/>
       to <b>http://www.openmobilealliance.org/tech/widl/foo-v1_0.widl</b>
</pre>
<p>
In cases where a draft version of the WIDL file is needed in the public directory, the DSO can perform the copy dependent on the following conditions:
</p>
<ul>
	<li>The WIDL file has the proper header which provides name information for both the PD SUP file and the public file name</li>
	<li>The draft WIDL in the public area would not overlay an existing Candidate or Approved WIDL already in the public schema directory</li>
	<li>The schema directory will not be updated to show the WIDL (done for Candidate) so users will need to know the URL by other means</li>
</ul>

<br/>
<h2><a name="header">Embedded Header in OMA WIDL Files</a></h2>
<p>The public WIDL files are the products of OMA and should properly represent the associated terms and conditions.
This is done by providing information in the file itself that can be viewed by users.
For WIDLs, this is done using commented material.
</p>
<p>
The following is an example header.
</p>

<center>
<table border="1" bgcolor="#DDEEFF"><tr><td><pre><span style="font-size:10px;">
/** FILE INFORMATION
*
* Description:
*    This schema provides the API description for the FOO enabler
* 
* Version: 1.0  (1.0.1)
* Date:    23 Aug 2011
* 
* OMA Permanent Document
*    File: OMA-SUP-WIDL_<span style="color:red;">foo-V1_0</span>_1-20110823-C
*    Type: Text
* 
* Public Reachable Information
*    Path: http://www.openmobilealliance.org/tech/profiles
*    Name: <span style="color:red;">foo-v1_0</span>.widl
* 
* NORMATIVE INFORMATION
* 
* Information about this file can be found in the latest revision of the specification
* <span style="color:red;">OMA-TS-FOO-V1_0</span> available at
*    http://www.openmobilealliance.org/
* 
* Send comments to technical-comments@mail.openmobilealliance.org
* 	
* LEGAL DISCLAIMER

* Use of this document is subject to all of the terms and conditions
* of the Use Agreement located at
* http://www.openmobilealliance.org/UseAgreement.html
* 
* You may use this document or any part of the document for internal
* or educational purposes only, provided you do not modify, edit or
* take out of context the information in this document in any manner.
* Information contained in this document may be used, at your sole
* risk, for any purposes.
* 
* You may not use this document in any other manner without the prior
* written permission of the Open Mobile Alliance.  The Open Mobile
* Alliance authorizes you to copy this document, provided that you
* retain all copyright and other proprietary notices contained in the
* original materials on any copies of the materials and that you
* comply strictly with these terms.  This copyright permission does
* not constitute an endorsement of the products or services.  The
* Open Mobile Alliance assumes no responsibility for errors or
* omissions in this document.
* 
* Each Open Mobile Alliance member has agreed to use reasonable
* endeavors to inform the Open Mobile Alliance in a timely manner of
* Essential IPR as it becomes aware that the Essential IPR is related
* to the prepared or published specification.  However, the members
* do not have an obligation to conduct IPR searches.  The declared
* Essential IPR is publicly available to members and non-members of
* the Open Mobile Alliance and may be found on the "OMA IPR
* Declarations" list at http://www.openmobilealliance.org/ipr.html.
* The Open Mobile Alliance has not conducted an independent IPR review
* of this document and the information contained herein, and makes no
* representations or warranties regarding third party IPR, including
* without limitation patents, copyrights or trade secret rights.  This
* document may contain inventions for which you must obtain licenses
* from third parties before making, using or selling the inventions.
* Defined terms above are set forth in the schedule to the Open Mobile
* Alliance Application Form.
* 
* NO REPRESENTATIONS OR WARRANTIES (WHETHER EXPRESS OR IMPLIED) ARE
* MADE BY THE OPEN MOBILE ALLIANCE OR ANY OPEN MOBILE ALLIANCE MEMBER
* OR ITS AFFILIATES REGARDING ANY OF THE IPR'S REPRESENTED ON THE "OMA
* IPR DECLARATIONS" LIST, INCLUDING, BUT NOT LIMITED TO THE ACCURACY,
* COMPLETENESS, VALIDITY OR RELEVANCE OF THE INFORMATION OR WHETHER OR
* NOT SUCH RIGHTS ARE ESSENTIAL OR NON-ESSENTIAL.
* 
* THE OPEN MOBILE ALLIANCE IS NOT LIABLE FOR AND HEREBY DISCLAIMS ANY
* DIRECT, INDIRECT, PUNITIVE, SPECIAL, INCIDENTAL, CONSEQUENTIAL, OR
* EXEMPLARY DAMAGES ARISING OUT OF OR IN CONNECTION WITH THE USE OF
* DOCUMENTS AND THE INFORMATION CONTAINED IN THE DOCUMENTS.
* 
* Copyright 20<span style="color:red;">11</span> Open Mobile Alliance Ltd.  All Rights Reserved.
* Used with the permission of the Open Mobile Alliance Ltd. under the
* terms set forth above.
*/</span></pre></td></tr></table>
</center>
<p>
This commented header would normally be inserted in the WIDL file near the beginning.
</p>


<h2><a name="reference">References</a></h2>
<ol>
<li><a name="ref1"/><a href="http://www.w3.org/TR/WebIDL/" target="_blank">&quot;Web IDL&quot;, W3C</a></li>
<li><a name="ref2"/><a href="http://www.doxygen.org/" target="_blank">Doxygen</a></li>
</ol>
<br/>
The public WIDL files are the products of OMA and should properly represent the associated terms and conditions.
This is done by providing information in the file itself that can be viewed by users.
For WIDLs, this is done using commented material.

<!--  Document Footer  -->


<table width="100%" cellspacing="0" cellpadding="0">
	<tr><td colspan="2"><img height="5" width="100%" src="http://member.openmobilealliance.org/ftp/rel/P-n-g/imgBitWht.gif" alt="" border="0"/></td></tr>
	<tr><td colspan="3"><img height="5" width="100%" src="http://member.openmobilealliance.org/ftp/rel/P-n-g/imgBitSep.gif" alt="" border="0"/></td></tr>
	<tr>
		<td class="footer" align="left">&copy; 2011 Open Mobile Alliance, Ltd.<br/>All Rights Reserved</td>
		<td class="footer" align="right"><a href="http://www.openmobilealliance.org/AboutOMA/useterms.aspx">Website Terms of Use</a></td>
	</tr>
</table>

</body>
</html>