telephony.html

Android Porting Guide

<p><ol>
<li>RIL daemon reads <code>rild.lib</code> path and <code>rild.libargs</code> system properties to determine the Vendor RIL library to use and any initialization arguments to provide to the Vendor RIL</li>
<li>RIL daemon loads the Vendor RIL library and calls <code>RIL_Init</code> to initialize the RIL and obtain a reference to RIL functions</li>
<li>RIL daemon calls <code>RIL_register</code> on the Android telephony stack, providing a reference to the Vendor RIL functions</li></ol>
</p>
<p>See the RIL Daemon source code at <code>//device/commands/rild/rild.c</code> for details.</p>


<a name="androidTelephonyRILIntro"></a><h2>RIL Interaction</h2>

<p>There are two forms of communication that the RIL handles:</p>
<ul>
  <li>Solicited commands: Solicited commands originated by RIL lib, such as <code>DIAL</code> and <code>HANGUP</code>.</li>
  <li>Unsolicited responses: Unsolicited responses that originate from the baseband, such as <code>CALL_STATE_CHANGED</code> and <code>NEW_SMS</code>.</li>
</ul>


<a name="androidTelephonyRILSolicited"></a><h3>Solicited</h3>

<p>The following snippet illustrates the interface for solicited commands:</p>
<pre class="prettify">
void OnRequest (int request_id, void *data, size_t datalen, RIL_Token t);&#13;
void OnRequestComplete (RIL_Token t, RIL_Error e, void *response, size_t responselen);&#13;
</pre>
<p>There are over sixty solicited commands grouped by the following families:</p>
<p>
<ul>
  <li>SIM PIN, IO, and IMSI/IMEI (11)</li>
  <li>Call status and handling (dial, answer, mute&hellip;) (16)</li>
  <li>Network status query (4)</li>
  <li>Network setting (barring, forwarding, selection&hellip;) (12)</li>
  <li>SMS (3)</li>
  <li>PDP connection (4)</li>
  <li>Power and reset (2)</li>
  <li>Supplementary Services (5)</li>
  <li>Vendor defined and support (4)<br/>
                    </li>
</ul>
</p>
<p>The following diagram illustrates a solicited call in Android.</p>
<p><img src="telephony_solicted_example.gif"></p>


<a name="androidTelephonyRILUnsolicited"></a><h3>Unsolicited</h3>

<p>The following snippet illustrates the interface for unsolicited commands:</p>
<pre class="prettify">
void OnUnsolicitedResponse (int unsolResponse, void *data, size_t datalen);
</pre>
<p>There are over ten unsolicited commands grouped by the following families:</p>
<p>
<ul>
<li>Network status changed (4)</li>
<li>New SMS notify (3)</li>
<li>New USSD notify (2)</li>
<li>Signal strength or time changed (2)</li>
</ul>
</p>
<p>The following diagram illustrates an unsolicited call in Android.</p>
<p><img src="telephony_unsolicted_example.gif"></p>


<a name="androidTelephonyRILImplementing"></a><h2>Implementing the RIL</h2>

<p>To implement a radio-specific RIL, create a shared library that implements a set of functions required by Android to process radio requests. The required functions are defined in the RIL header (<code>/include/telephony/ril.h</code>).</p>
<p>The Android radio interface is radio-agnostic and the Vendor RIL can use any protocol to communicate with the radio.&nbsp;Android provides a reference Vendor RIL, using the Hayes AT command set, that you can use as a quick start for telephony testing and a guide for commercial vendor RILs. The source code for the reference RIL is found at <code>/commands/reference-ril/</code>.</p>
<p>Compile your Vendor RIL as a shared library using the convention <code>libril-&lt;companyname&gt;-&lt;RIL version&gt;.so</code>, for example, libril-acme-124.so, where:</p>
<p><ul>
<li><b>libril</b>: all vendor RIL implementations start with 'libril'</li>
<li><b>&lt;companyname&gt;</b>: a company-specific abbreviation</li>
<li><b>&lt;RIL version&gt;</b>: RIL version number</li>
<li><b>so</b>: file extension</li>
</ul>
</p>


<a name="androidTelephonyRILInit"></a><h3>RIL_Init</h3>

<p>Your Vendor RIL must define a RIL_Init function that provides a handle to the functions which will process all radio requests.  RIL_Init will be called by the Android RIL Daemon at boot time to initialize the RIL.</p>

<pre class="prettify">
RIL_RadioFunctions *RIL_Init (RIL_Env* env, int argc, char **argv);
</pre>

<p>RIL_Init should return a RIL_RadioFunctions structure containing the handles to the radio functions:</p>
<pre class="prettify">
type structure {
	int RIL_version;
	RIL_RequestFunc onRequest;
	RIL_RadioStateRequest onStateRequest;      
	RIL_Supports supports;
	RIL_Cancel onCancel;
	RIL_GetVersion getVersion;
} 
RIL_RadioFunctions;
</pre>


<a name="androidTelephonyRILFunctions"></a><h2>RIL Functions</h2>

<p><code>ril.h</code> defines RIL states and variables, such as <code>RIL_UNSOL_STK_CALL_SETUP</code>, <code>RIL_SIM_READY</code>, <code>RIL_SIM_NOT_READY</code>, as well as the functions described in the tables below. Skim the header file (<code>/device/include/telephony/ril.h</code>) for details.</p>


<a name="androidRilFunctionsSolicited"></a><h3>RIL Solicited Command Requests</h3>

<p>The vendor RIL must provide the functions described in the table below to handle solicited commands. The RIL solicited command request types are defined in <code>ril.h</code> with the <code>RIL_REQUEST_</code> prefix. Check the header file for details.</p>
<p><table>
  <tr><th scope="col">Name</th><th scope="col">Description</th></tr>
  <tr>
    <td valign="top"><code> void (*RIL_RequestFunc) (int request, void *data, size_t datalen, RIL_Token t);</code></td>
    <td valign="top">
	<p>This is the RIL entry point for solicited commands and must be able to handle the various RIL solicited request types defined in <code>ril.h</code> with the <code>RIL_REQUEST_</code> prefix.</p>
	<ul>
        <li><code>request</code> is one of <code>RIL_REQUEST_*</code></li>
        <li><code>data</code> is pointer to data defined for that <code>RIL_REQUEST_*</code></l>
        <li><code>t</code> should be used in subsequent call to <code>RIL_onResponse</code></li>
        <li><code>datalen</code> is owned by caller, and should not be modified or freed by callee</li>
      </ul>
	<p>Must be completed with a call to <code>RIL_onRequestComplete()</code>. &nbsp;<code>RIL_onRequestComplete()</code> may be called from any thread before or after this function returns. This will &nbsp;always be called from the same thread, so returning here implies that the radio is ready to process another command (whether or not the previous command has completed).</p></td>
  </tr>
  <tr>
    <td valign="top"><code> RIL_RadioState (*RIL_RadioStateRequest)();</code></td>
    <td valign="top">This function should return the current radio state synchronously.</td>
  </tr>
  <tr>
    <td valign="top"><code> int (*RIL_Supports)(int requestCode);</code></td>
    <td valign="top">This function returns "1" if the specified <code>RIL_REQUEST</code> code is supported and 0 if it is not.</td>
  </tr>
  <tr>
    <td valign="top"><code> void (*RIL_Cancel)(RIL_Token t);</code></td>
    <td valign="top"><p>This function is used to indicate that a pending request should be canceled. This function is called from a separate thread--not the thread that calls <code>RIL_RequestFunc</code>.</p>
      <p>On cancel, the callee should do its best to abandon the request and call <code>RIL_onRequestComplete</code> with <code>RIL_Errno CANCELLED</code> at some later point.</p>
      <p>Subsequent calls to <code>RIL_onRequestComplete</code> for this request with other results will be tolerated but ignored (that is, it is valid to ignore the cancellation request).</p>
    <p><code>RIL_Cancel</code> calls should return immediately and not wait for cancellation.</p></td>
  </tr>
  <tr>
    <td valign="top"><code> const char * (*RIL_GetVersion) (void);</code></td>
    <td valign="top">Return a version string for your Vendor RIL</td>
  </tr>
</table>


<p>The vendor RIL uses the following callback methods to communicate back to the Android RIL daemon.</p>
<p>
<table>
  <tr>
    <th scope="col">Name</th>
    <th scope="col">Description</th>
  </tr>
  <tr>
    <td><code>void RIL_onRequestComplete(RIL_Token t, RIL_Errno e, void *response, size_t responselen);</code></td>
    <td><ul>
      <li><code>t</code> is parameter passed in on previous call to <code>RIL_Notification</code> routine.</li>
      <li>If <code>e</code> != SUCCESS, then response can be null and is ignored</li>
      <li><code>response</code> is owned by caller, and should not be modified or freed by callee</li>
      <li><code>RIL_onRequestComplete</code> will return as soon as possible</li>
    </ul></td>
  </tr>
  <tr>
    <td><code>void RIL_requestTimedCallback (RIL_TimedCallback callback, void *param, const struct timeval *relativeTime);</code></td>
    <td>Call user-specified callback function on the same thread that <code>RIL_RequestFunc</code> is called. If <code>relativeTime</code> is specified, then it specifies a relative time value at which the callback is invoked. If <code>relativeTime</code> is NULL or points to a 0-filled structure, the callback will be invoked as soon as possible.</td>
  </tr>
</table></p>


<a name="androidRilFunctionsUnsolicited"></a><h3>RIL Unsolicited Commands</h3>

<p>The functions listed in the table below are call-back functions used by the Vendor RIL to invoke unsolicited commands on the Android platform. See <code>ril.h</code> for details. </p>
<p>
<table>
  <tr>
    <th scope="col">Name</th>
    <th scope="col">Description</th>
  </tr>
  <tr>
    <td><code>void RIL_onUnsolicitedResponse(int unsolResponse, const void *data, size_t datalen);</code></td>
    <td><ul>
      <li><code>unsolResponse</code> is one of <code>RIL_UNSOL_RESPONSE_*</code></li>
      <li><code>data</code> is pointer to data defined for that <code>RIL_UNSOL_RESPONSE_*</code></li>
      <li><code>data</code> is owned by caller, and should not be modified or freed by callee</li>
    </ul></td>
  </tr>
</table></p>


<p><span class="lh2"><a name="androidFooter"></a></span>

        </div>
      </div>
      <!-- end gc-pagecontent -->
    </div>
    <!-- end gooey wrapper -->
  </div>
  <!-- end codesearchresults -->
  <div id="gc-footer" dir="ltr">
    <div class="text"> &copy;2008 Google<!-- - <a href="/">Code Home</a> - <a href="http://www.google.com/accounts/TOS">Site Terms of Service</a> - <a href="http://www.google.com/privacy.html">Privacy Policy</a> - <a href="/more">Site Directory</a> --></div>
  </div>
  <!-- end gc-footer -->
</div>
<!-- end gc-containter -->
<script src="http://www.google-analytics.com/ga.js" type="text/javascript">
</script>
<script type="text/javascript">
  try {
    var pageTracker = _gat._getTracker("UA-18071-1");
    pageTracker._setAllowAnchor(true);
    pageTracker._initData();
    pageTracker._trackPageview(); 
  } catch(e) {}
</script>
<div id="jd-build-id"> v0.6 - 25 November 2008</div>
</div></div></div></body>
</html>