diff options
Diffstat (limited to 'doc/context-arch.html')
| -rw-r--r-- | doc/context-arch.html | 1249 |
1 files changed, 1249 insertions, 0 deletions
diff --git a/doc/context-arch.html b/doc/context-arch.html new file mode 100644 index 00000000..73d2d7be --- /dev/null +++ b/doc/context-arch.html @@ -0,0 +1,1249 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
+ "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+<meta name="generator" content="AsciiDoc 8.4.4" />
+<title>Context Framework Subsystem Architecture Description</title>
+<style type="text/css">
+/* Debug borders */
+p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
+/*
+ border: 1px solid red;
+*/
+}
+
+body {
+ margin: 1em 5% 1em 5%;
+}
+
+a {
+ color: blue;
+ text-decoration: underline;
+}
+a:visited {
+ color: fuchsia;
+}
+
+em {
+ font-style: italic;
+ color: navy;
+}
+
+strong {
+ font-weight: bold;
+ color: #083194;
+}
+
+tt {
+ color: navy;
+}
+
+h1, h2, h3, h4, h5, h6 {
+ color: #527bbd;
+ font-family: sans-serif;
+ margin-top: 1.2em;
+ margin-bottom: 0.5em;
+ line-height: 1.3;
+}
+
+h1, h2, h3 {
+ border-bottom: 2px solid silver;
+}
+h2 {
+ padding-top: 0.5em;
+}
+h3 {
+ float: left;
+}
+h3 + * {
+ clear: left;
+}
+
+div.sectionbody {
+ font-family: serif;
+ margin-left: 0;
+}
+
+hr {
+ border: 1px solid silver;
+}
+
+p {
+ margin-top: 0.5em;
+ margin-bottom: 0.5em;
+}
+
+ul, ol, li > p {
+ margin-top: 0;
+}
+
+pre {
+ padding: 0;
+ margin: 0;
+}
+
+span#author {
+ color: #527bbd;
+ font-family: sans-serif;
+ font-weight: bold;
+ font-size: 1.1em;
+}
+span#email {
+}
+span#revision {
+ font-family: sans-serif;
+}
+
+div#footer {
+ font-family: sans-serif;
+ font-size: small;
+ border-top: 2px solid silver;
+ padding-top: 0.5em;
+ margin-top: 4.0em;
+}
+div#footer-text {
+ float: left;
+ padding-bottom: 0.5em;
+}
+div#footer-badges {
+ float: right;
+ padding-bottom: 0.5em;
+}
+
+div#preamble {
+ margin-top: 1.5em;
+ margin-bottom: 1.5em;
+}
+div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
+div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
+div.admonitionblock {
+ margin-top: 1.5em;
+ margin-bottom: 1.5em;
+}
+div.admonitionblock {
+ margin-top: 2.5em;
+ margin-bottom: 2.5em;
+}
+
+div.content { /* Block element content. */
+ padding: 0;
+}
+
+/* Block element titles. */
+div.title, caption.title {
+ color: #527bbd;
+ font-family: sans-serif;
+ font-weight: bold;
+ text-align: left;
+ margin-top: 1.0em;
+ margin-bottom: 0.5em;
+}
+div.title + * {
+ margin-top: 0;
+}
+
+td div.title:first-child {
+ margin-top: 0.0em;
+}
+div.content div.title:first-child {
+ margin-top: 0.0em;
+}
+div.content + div.title {
+ margin-top: 0.0em;
+}
+
+div.sidebarblock > div.content {
+ background: #ffffee;
+ border: 1px solid silver;
+ padding: 0.5em;
+}
+
+div.listingblock > div.content {
+ border: 1px solid silver;
+ background: #f4f4f4;
+ padding: 0.5em;
+}
+
+div.quoteblock {
+ padding-left: 2.0em;
+ margin-right: 10%;
+}
+div.quoteblock > div.attribution {
+ padding-top: 0.5em;
+ text-align: right;
+}
+
+div.verseblock {
+ padding-left: 2.0em;
+ margin-right: 10%;
+}
+div.verseblock > div.content {
+ white-space: pre;
+}
+div.verseblock > div.attribution {
+ padding-top: 0.75em;
+ text-align: left;
+}
+/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
+div.verseblock + div.attribution {
+ text-align: left;
+}
+
+div.admonitionblock .icon {
+ vertical-align: top;
+ font-size: 1.1em;
+ font-weight: bold;
+ text-decoration: underline;
+ color: #527bbd;
+ padding-right: 0.5em;
+}
+div.admonitionblock td.content {
+ padding-left: 0.5em;
+ border-left: 2px solid silver;
+}
+
+div.exampleblock > div.content {
+ border-left: 2px solid silver;
+ padding: 0.5em;
+}
+
+div.imageblock div.content { padding-left: 0; }
+div.imageblock img { border: 1px solid silver; }
+span.image img { border-style: none; }
+
+dl {
+ margin-top: 0.8em;
+ margin-bottom: 0.8em;
+}
+dt {
+ margin-top: 0.5em;
+ margin-bottom: 0;
+ font-style: normal;
+ color: navy;
+}
+dd > *:first-child {
+ margin-top: 0.1em;
+}
+
+ul, ol {
+ list-style-position: outside;
+}
+ol.arabic {
+ list-style-type: decimal;
+}
+ol.loweralpha {
+ list-style-type: lower-alpha;
+}
+ol.upperalpha {
+ list-style-type: upper-alpha;
+}
+ol.lowerroman {
+ list-style-type: lower-roman;
+}
+ol.upperroman {
+ list-style-type: upper-roman;
+}
+
+div.compact ul, div.compact ol,
+div.compact p, div.compact p,
+div.compact div, div.compact div {
+ margin-top: 0.1em;
+ margin-bottom: 0.1em;
+}
+
+div.tableblock > table {
+ border: 3px solid #527bbd;
+}
+thead {
+ font-family: sans-serif;
+ font-weight: bold;
+}
+tfoot {
+ font-weight: bold;
+}
+td > div.verse {
+ white-space: pre;
+}
+p.table {
+ margin-top: 0;
+}
+/* Because the table frame attribute is overriden by CSS in most browsers. */
+div.tableblock > table[frame="void"] {
+ border-style: none;
+}
+div.tableblock > table[frame="hsides"] {
+ border-left-style: none;
+ border-right-style: none;
+}
+div.tableblock > table[frame="vsides"] {
+ border-top-style: none;
+ border-bottom-style: none;
+}
+
+
+div.hdlist {
+ margin-top: 0.8em;
+ margin-bottom: 0.8em;
+}
+div.hdlist tr {
+ padding-bottom: 15px;
+}
+dt.hdlist1.strong, td.hdlist1.strong {
+ font-weight: bold;
+}
+td.hdlist1 {
+ vertical-align: top;
+ font-style: normal;
+ padding-right: 0.8em;
+ color: navy;
+}
+td.hdlist2 {
+ vertical-align: top;
+}
+div.hdlist.compact tr {
+ margin: 0;
+ padding-bottom: 0;
+}
+
+.comment {
+ background: yellow;
+}
+
+@media print {
+ div#footer-badges { display: none; }
+}
+
+div#toctitle {
+ color: #527bbd;
+ font-family: sans-serif;
+ font-size: 1.1em;
+ font-weight: bold;
+ margin-top: 1.0em;
+ margin-bottom: 0.1em;
+}
+
+div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
+ margin-top: 0;
+ margin-bottom: 0;
+}
+div.toclevel2 {
+ margin-left: 2em;
+ font-size: 0.9em;
+}
+div.toclevel3 {
+ margin-left: 4em;
+ font-size: 0.9em;
+}
+div.toclevel4 {
+ margin-left: 6em;
+ font-size: 0.9em;
+}
+/* Workarounds for IE6's broken and incomplete CSS2. */
+
+div.sidebar-content {
+ background: #ffffee;
+ border: 1px solid silver;
+ padding: 0.5em;
+}
+div.sidebar-title, div.image-title {
+ color: #527bbd;
+ font-family: sans-serif;
+ font-weight: bold;
+ margin-top: 0.0em;
+ margin-bottom: 0.5em;
+}
+
+div.listingblock div.content {
+ border: 1px solid silver;
+ background: #f4f4f4;
+ padding: 0.5em;
+}
+
+div.quoteblock-attribution {
+ padding-top: 0.5em;
+ text-align: right;
+}
+
+div.verseblock-content {
+ white-space: pre;
+}
+div.verseblock-attribution {
+ padding-top: 0.75em;
+ text-align: left;
+}
+
+div.exampleblock-content {
+ border-left: 2px solid silver;
+ padding-left: 0.5em;
+}
+
+/* IE6 sets dynamically generated links as visited. */
+div#toc a:visited { color: blue; }
+</style>
+<script type="text/javascript">
+/*<+'])');
+ // Function that scans the DOM tree for header elements (the DOM2
+ // nodeIterator API would be a better technique but not supported by all
+ // browsers).
+ var iterate = function (el) {
+ for (var i = el.firstChild; i != null; i = i.nextSibling) {
+ if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
+ var mo = re.exec(i.tagName)
+ if (mo)
+ result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
+ iterate(i);
+ }
+ }
+ }
+ iterate(el);
+ return result;
+}
+
+// This function does the work. toclevels = 1..4.
+function generateToc(toclevels) {
+ var toc = document.getElementById("toc");
+ var entries = tocEntries(document.getElementsByTagName("body")[0], toclevels);
+ for (var i = 0; i < entries.length; ++i) {
+ var entry = entries[i];
+ if (entry.element.id == "")
+ entry.element.id = "toc" + i;
+ var a = document.createElement("a");
+ a.href = "#" + entry.element.id;
+ a.appendChild(document.createTextNode(entry.text));
+ var div = document.createElement("div");
+ div.appendChild(a);
+ div.className = "toclevel" + entry.toclevel;
+ toc.appendChild(div);
+ }
+ if (entries.length == 0)
+ document.getElementById("header").removeChild(toc);
+}
+/*]]>*/
+</script>
+</head>
+<body>
+<div id="header">
+<h1>Context Framework Subsystem Architecture Description</h1>
+<div id="toc">
+ <div id="toctitle">Table of Contents</div>
+ <noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
+</div>
+</div>
+<div id="preamble">
+<div class="sectionbody">
+<div class="tableblock">
+<table rules="all"
+width="30%"
+frame="border"
+cellspacing="0" cellpadding="4">
+<col width="50%" />
+<col width="50%" />
+<tbody>
+<tr>
+<td align="left" valign="top"><p class="table">Author</p></td>
+<td align="left" valign="top"><p class="table">Marius Vollmer</p></td>
+</tr>
+<tr>
+<td align="left" valign="top"><p class="table">Status</p></td>
+<td align="left" valign="top"><p class="table">Draft</p></td>
+</tr>
+<tr>
+<td align="left" valign="top"><p class="table">Version</p></td>
+<td align="left" valign="top"><p class="table">2009-12-10</p></td>
+</tr>
+<tr>
+<td align="left" valign="top"><p class="table">Approver</p></td>
+<td align="left" valign="top"><p class="table">Olli Finni</p></td>
+</tr>
+</tbody>
+</table>
+</div>
+<div class="paragraph"><p>Copyright © Nokia. All rights reserved.</p></div>
+<div class="paragraph"><p>This material, including documentation and any related computer
+programs, is protected by copyright controlled by Nokia. All rights
+are reserved. Copying, including reproducing, storing, adapting or
+translating, any or all of this material requires the prior written
+consent of Nokia. This material also contains confidential
+information, which may not be disclosed to others without the prior
+written consent of Nokia.</p></div>
+<div class="paragraph"><p>Nokia is a registered trademark of Nokia. Other company and product
+names mentioned herein may be trademarks or tradenames of their
+respective owners.</p></div>
+</div>
+</div>
+<h2 id="_introduction">Introduction</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>The Context Framework, part of the Data Domain, provides a uniform,
+high level API to numerous context properties of the device. While
+many of these context properties are available without the context
+framework, each of them has its own specific way of accessing it. The
+context framework collects them all behind a uniform API, and
+applications thus have easy access to all of the context properties.</p></div>
+<div class="paragraph"><p>The following lists some typical context properties:</p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+Connectivity status of the device; whether it is connected to the
+ Internet and by what means.
+</p>
+</li>
+<li>
+<p>
+Location; the name of the current city.
+</p>
+</li>
+<li>
+<p>
+Builtin sensors; orientation in space.
+</p>
+</li>
+<li>
+<p>
+Current use; idle, plays media, web browsing.
+</p>
+</li>
+<li>
+<p>
+Combined properties; current weather based on location and online
+ weather database.
+</p>
+</li>
+</ul></div>
+<div class="paragraph"><p>More concretely, the information in the status bar of a device is
+provided exclusively by the Context Framework.</p></div>
+<div class="paragraph"><p>Applications access context properties by using the <tt>ContextProperty</tt>
+class that is implemented in api:libcontextsubscriber.</p></div>
+<div class="paragraph"><p>The context framework is modular: context properties from multiple
+independent components are directly combined in the
+<tt>libcontextsubscriber</tt> API and applications can access them without
+needing to know who is ultimately providing them.</p></div>
+<div class="paragraph"><p>A component that wants to directly provide context properties needs to
+implement the relevant interfaces defined by the context framework.
+Currently, the only supported way to do that is to use the
+api:libcontextprovider library.</p></div>
+<div class="paragraph"><p>In addition to information from multiple sources, the context
+framework is a provider of context properties itself: there is a
+<em>context daemon</em> that collects information from low-level and legacy
+interfaces. This context daemon is a good default location for
+implementing context properties and for absorbing properties from
+existing subsystems that have aqcuired them for historical reasons and
+would rather get rid of them.</p></div>
+<div class="paragraph"><p>The concrete list of properties is ultimately defined by their
+providers, but the context framework is the central authority: the
+‘official’ list of context properties of the Maemo platform is defined
+and documented by the context framework.</p></div>
+<div class="paragraph"><p>To summarize, the context framework contributes value to the Maemo
+platform in the following ways:</p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+It implements and documents a high-level, uniform API to a set of
+ context properties that are provided by multiple components.
+</p>
+</li>
+<li>
+<p>
+It defines and documents the concrete list of properties of the
+ Maemo platform. This includes harmonizing the context ontology with
+ other industry efforts.
+</p>
+</li>
+<li>
+<p>
+It implements context properties that do not naturally belong to
+ other subsystems and coordinates the implementation of context
+ properties that do belong in specific subsystems.
+</p>
+</li>
+<li>
+<p>
+It provides a debugging and exploration tool for inspecting and
+ controlling context properties.
+</p>
+</li>
+</ul></div>
+<div class="paragraph"><p>Thus, the Context Framework does not drive the behavior of the system,
+it only provides the information that is needed for other components
+to decide for themselves. To makes this reasonably easy, the context
+properties are at a high level of abstraction and express the coarse
+grained states of the device. For example, the properties tell you
+whether it is completely idle, in passive use playing some media, or
+in active use. They don’t give a real-time view of CPU load.</p></div>
+</div>
+<h2 id="_architecture">Architecture</h2>
+<div class="sectionbody">
+<h3 id="_concepts">Concepts</h3><div style="clear:left"></div>
+<div class="paragraph"><p>Context properties are collected from all providers that have
+registered themselves with the
+<a href="context-providers.html"><tt>context-providers</tt></a> interface. For each
+provider, this registration information includes the list of its
+properties with type information and a short description for each, and
+the D-Bus bus name where the provider can be reached. Providers can
+be both on the session and on the system bus, and the registration
+information indicates which bus it is.</p></div>
+<div class="paragraph"><p>This registration information is read by the <tt>libcontextsubscriber</tt>
+library and used by its <tt>ContextProperty</tt> class to connect a requested
+property name to the right bus name.</p></div>
+<div class="paragraph"><p>The registration information is compiled into a <em>cache</em> that is
+optimized for use by <tt>libcontextsubscriber</tt>. When the set of
+registered properties changes, the cache is recompiled by a command
+line utility provided by the context framework. This will then
+trigger all libcontextsubscriber clients to reload the registry
+information, and existing <tt>ContextProperty</tt> instances to be updated.</p></div>
+<div class="paragraph"><p>(Note that the cache only caches property declarations, it does not
+ever contain the values of context properties.)</p></div>
+<div class="paragraph"><p>When providers are installed from packages, recompilation of the cache
+happens automatically. <em>Triggers</em> in the Context Framework packages
+are used to run the command line utility at the right times.</p></div>
+<div class="paragraph"><p>The <tt>libcontextsubscriber</tt> library gracefully handles start, stop and
+restart of providers. During system startup some applications may
+start to use the Context Framework before all providers are
+available. Properties become dynamically available as providers become
+available, and removed when providers are no longer available.</p></div>
+<div class="paragraph"><p>Communication between a <tt>ContextProperty</tt> and the provider happens
+using a private D-Bus interface. This interface allows for bulk
+retrieval of property values, bulk subscriptions, and bulk change
+notification.</p></div>
+<div class="paragraph"><p>The values of properties are represented to clients as a <tt>QVariant</tt>
+value. Properties can have a special <em>null</em> value when they are not
+available, either because they are not provided by any provider, or
+because the provider is not able to deliver a value. In other words,
+the types of all context properties are "maybe types": subscribers
+might get a value or not. In general, the <em>null</em> value means that the
+real value of the property is unknown.</p></div>
+<div class="paragraph"><p>The <em>null</em> value is different from the empty string or the empty list.
+For example, the "Location.City" property, which denotes the name of
+the current city as a string, will be <em>null</em> when the name of the city
+is unknown (either because the current location of the device is
+unknown or because the database that maps from locations to city names
+is not reachable), but it will be the empty string when the current
+location is known to be outside of any city.</p></div>
+<div class="paragraph"><p>The absence of a value can have many reasons: no provider is available
+for this property, the provider has not yet delivered a value, or the
+provider is deliberately not delivering a value, which it can in turn
+have many reasons. For example, necessary hardware might not be
+present or its use might be disallowed by the current power management
+policy, or a needed online database might not reachable.</p></div>
+<div class="paragraph"><p>The Context Framework makes no attempt to distinguish these different
+reasons. Subscribers should make good use of a value when they get
+it, but they must not fail catastrophically when no value is
+available, or when it takes longer than expected for it to become
+available.</p></div>
+<div class="paragraph"><p>It is expected that eventually the statusbar plugins, such as the
+battery charge monitor and the connectivity indicators, exclusively
+use the context properties to retrieve the information they display.</p></div>
+<div class="paragraph"><p>Context providers need to implement the private D-Bus interface. This
+is done with the api:libcontextprovider library. This library is used
+by the context daemon itself, which can serve as an extended example.</p></div>
+<div class="paragraph"><p>The Connectivity Framework and the Sensor Framework are expected to be
+context providers as described above. Additional context properties,
+such as those related to the Location Framework, are implemented by
+the <em>context daemon</em> contained in the Context Framework.</p></div>
+<div class="paragraph"><p>The <tt>contextd</tt> Context Daemon will implement all context properties
+that don’t have a native provider. It will at least implement
+properties for the information contained in HAL and for location
+related information. It is expected that <tt>contextd</tt> runs the
+necessary reverse geocoding operations at a reasonable frequency. It
+will also perform Content Framework queries to retrieve the values of
+certain properties.</p></div>
+<div class="paragraph"><p>If necessary for security reasons, the <tt>contextd</tt> might need to be
+split into multiple instances.</p></div>
+<h3 id="_system_context">System context</h3><div style="clear:left"></div>
+<div class="paragraph"><p>The context framework decouples context subscribers from context
+providers.</p></div>
+<div class="svg">
+<object type="image/png" data="fig3.png"/>
+</div>digraph G {
+
+ graph [size="7,100"];
+ node [shape=box, style=filled, fontsize=11];
+ edge [fontsize=11];
+
+
+ "Direct UI Framework" -> "Context Framework"
+ "Policy Engine" -> "Context Framework"
+ "Sensor" -> "Context Framework"
+ "Content Framework" -> "Context Framework" [dir="both"]
+
+ "Context Framework" -> "Internet Connectivity" [dir="back"]
+ "Context Framework" -> "Location Framework"
+ "Context Framework" -> "Freedesktop Essentials"
+
+}
+<h3 id="_structural_view">Structural view</h3><div style="clear:left"></div>
+<div class="paragraph"><p>The following figure summarizes the components of the Context
+Framework.</p></div>
+<div class="svg">
+<object type="image/png" data="fig4.png"/>
+</div>digraph G {
+
+ graph [size="7,100"];
+ node [shape=box, style=filled, fontsize=11];
+ edge [fontsize=11];
+
+ { rank=source
+ app [label="<<process>>\n\napplication"];
+ }
+
+ subgraph cluster0 {
+ label="Context Framework"
+
+ registry [label="<<XML documents>>\n\n/usr/share/context-providers/"];
+ cache [label="<<CDB file>>\n\ncache.cdb"];
+ libsub [label="<<library>>\n\nlibcontextsubscriber"];
+ update [label="<<utility>>\n\nupdate-context-providers"];
+ libprov [label="<<library>>\n\nlibcontextprovider"];
+ contextd [label="<<process>>\n\ncontextd"];
+
+ commander [label="<<utility>>\n\ncontext-commander"];
+ corepros [label="<<XML document>>\n\ncore context\nproperty declarations", shape=note];
+
+ // update -> registry [label="<<read>>"]
+ // update -> cache [label="<<write>>"]
+ registry -> update [label="<<read>>", dir="back"]
+ cache -> update [label="<<write>>", dir="back"]
+
+ libsub -> libprov [label="<<D-Bus>>"]
+ libsub -> registry [label="<<read>>"]
+ libsub -> cache [label="<<read>>"]
+ libprov -> contextd [label="<<link>>", dir="back"]
+ }
+
+ {
+ rank=sink
+ props [label="<<XML document>>\n\nicd2-props.xml", shape=note];
+ icd2 [label="<<process>>\n\nicd2"];
+ libgeo [label="<<library>>\n\nlibgeo"];
+ libhal [label="<<library>>\n\nlibhal"];
+ }
+
+ app -> libsub [label="<<link>>"]
+
+ registry -> props [dir="back"]
+ contextd -> libgeo [label="<<link>>"]
+ contextd -> libhal [label="<<link>>"]
+ libprov -> icd2 [label="<<link>>", dir="back"]
+}
+<div class="paragraph"><p>There are two fundamental options for exporting information via the
+context framework:</p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+The context daemon can use existing platform interfaces, such as
+ HAL, to collect this information, process it, and export it as a
+ context property.
+ <br />
+ This applies to: HAL, Location subsystem, Kernel.
+</p>
+</li>
+<li>
+<p>
+The principal producer of the information, such as the <tt>icd2</tt> daemon
+ in the Connectivity subsystem, can use the libcontextprovider API
+ and export the information directly to applications without using
+ the context daemon as a middle man.
+ <br />
+ This applies to: Sensor Framework, possibly Connectivity subsystem
+ (needs agreeement), possibly Telephony subsystem (needs agreement)
+</p>
+</li>
+</ul></div>
+<h3 id="_provided_interfaces">Provided Interfaces</h3><div style="clear:left"></div>
+<div class="paragraph"><div class="title"><tt>libcontextsubscriber</tt></div><p>A C++ API for listening to context properties.</p></div>
+<div class="paragraph"><p><a href="libcontextsubscriber">Documentation</a></p></div>
+<div class="paragraph"><div class="title"><tt>libcontextprovider</tt></div><p>A C++ and C API for providing values of context properties.</p></div>
+<div class="paragraph"><p><a href="libcontextprovider">Documentation</a></p></div>
+<div class="paragraph"><div class="title"><tt>context-properties</tt></div><p>The canonical list of context properties in the Maemo platform. When
+a context property from the list is available, it must conform to its
+description there.</p></div>
+<div class="paragraph"><p><a href="context-properties.html">Documentation</a></p></div>
+<div class="paragraph"><div class="title"><tt>context-providers</tt></div><p>The interface to register providers of context properties. A provider
+must use the api:libcontextprovider API.</p></div>
+<div class="paragraph"><p><a href="context-providers.html">Documentation</a></p></div>
+<h3 id="_development_support">Development support</h3><div style="clear:left"></div>
+<div class="paragraph"><p>No special features are needed in the Context Framework components to
+make them work in a Scratchbox environment. Availability of
+individual properties depends on the ability of their providers to run
+in Scratchbox. The <tt>contextd</tt> Context Daemon runs but might not be
+able to provide all properties.</p></div>
+<div class="paragraph"><p>The Context Framework provides a graphical tool called the Context
+Commander to watch all available context properties. This can be used
+to test context providers during development.</p></div>
+<div class="paragraph"><p>In addition, the Context Commander can be used to force context
+properties of selected applications to arbitrary values. This can be
+used to test the reaction of applications to context changes.</p></div>
+<div class="paragraph"><p>The Context Commander runs on the device and either show its UI on the
+device itself or exports it to an external X11 server. This way, the
+testing can be done without disturbing the display of the device
+itself.</p></div>
+<div class="paragraph"><p>When started, the Context Commander takes control of all subscribers
+with their cooperation: when the
+"org.freedesktop.ContextKit.Commander" name appears on the session
+D-Bus, all ContextProperty instances redirect their subcription
+requests to it.</p></div>
+<div class="paragraph"><p>There are vague ideas about integrating the Context Commander into
+Eclipse.</p></div>
+<h3 id="_licenses">Licenses</h3><div style="clear:left"></div>
+<div class="paragraph"><p>The components of the Context Framework will be developed publically,
+under the umbrella of the freedesktop.org organization. All source
+code is licensed with LGPL 2.1, including the daemon and context
+commander.</p></div>
+<div class="paragraph"><p>Non-free source code can safely interact with the Context Framework
+components.</p></div>
+<h3 id="_user_data_settings_and_configurability">User Data, Settings, and Configurability</h3><div style="clear:left"></div>
+<div class="paragraph"><p>The Context Framework does not store user data and is not
+configurable.</p></div>
+<h3 id="_configurability">Configurability</h3><div style="clear:left"></div>
+<div class="paragraph"><p>See above.</p></div>
+<h3 id="_packages">Packages</h3><div style="clear:left"></div>
+<div class="dlist"><div class="title"><tt>contextkit</tt></div><dl>
+<dt class="hdlist1">
+Languages
+</dt>
+<dd>
+<p>
+C, C++
+</p>
+</dd>
+<dt class="hdlist1">
+License
+</dt>
+<dd>
+<p>
+LGPL 2.1
+</p>
+</dd>
+<dt class="hdlist1">
+Provided interfaces
+</dt>
+<dd>
+<p>
+libcontextsubscriber, libcontextprovider, context-providers, context-properties,
+</p>
+</dd>
+<dt class="hdlist1">
+Used interfaces
+</dt>
+<dd>
+<p>
+libdbus, libgee, libglib, libcdb, libqt4-dbus, libqt4-xml, libqtcore4
+</p>
+</dd>
+<dt class="hdlist1">
+Binary packages
+</dt>
+<dd>
+<p>
+ libcontextsubscriber0, libcontextsubscriber0-dbg, libcontextsubscriber-dev, libcontextsubscriber-doc,
+ libcontextprovider0, libcontextprovider0-dbg, libcontextprovider-dev, libcontextprovider-doc,
+ contextkit, contextkit-doc, context-dbg
+</p>
+</dd>
+<dt class="hdlist1">
+Sources
+</dt>
+<dd>
+<p>
+<a href="https://dvcs.projects.maemo.org/git/?p=ContextKit">https://dvcs.projects.maemo.org/git/?p=ContextKit</a>
+</p>
+</dd>
+</dl></div>
+<div class="dlist"><div class="title"><tt>context-commander</tt></div><dl>
+<dt class="hdlist1">
+Languages
+</dt>
+<dd>
+<p>
+C++
+</p>
+</dd>
+<dt class="hdlist1">
+License
+</dt>
+<dd>
+<p>
+LGPL 2.1
+</p>
+</dd>
+<dt class="hdlist1">
+Provided interfaces
+</dt>
+<dd>
+<p>
+none
+</p>
+</dd>
+<dt class="hdlist1">
+Used interfaces
+</dt>
+<dd>
+<p>
+libcontextsubscriber, libqt4-dbus, libqt4-gui, libqt4-core
+</p>
+</dd>
+<dt class="hdlist1">
+Binary packages
+</dt>
+<dd>
+<p>
+context-commander
+</p>
+</dd>
+<dt class="hdlist1">
+Sources
+</dt>
+<dd>
+<p>
+<a href="https://dvcs.projects.maemo.org/git/?p=ContextCommander">https://dvcs.projects.maemo.org/git/?p=ContextCommander</a>
+</p>
+</dd>
+</dl></div>
+<div class="dlist"><div class="title"><tt>context-provider-example</tt></div><dl>
+<dt class="hdlist1">
+Languages
+</dt>
+<dd>
+<p>
+C
+</p>
+</dd>
+<dt class="hdlist1">
+License
+</dt>
+<dd>
+<p>
+LGPL 2.1
+</p>
+</dd>
+<dt class="hdlist1">
+Provided interfaces
+</dt>
+<dd>
+<p>
+Context.Example.* properties.
+</p>
+</dd>
+<dt class="hdlist1">
+Used interfaces
+</dt>
+<dd>
+<p>
+libcontextprovider, sysfs files for accelerometer and ambient light sensor
+</p>
+</dd>
+<dt class="hdlist1">
+Binary packages
+</dt>
+<dd>
+<p>
+context-provider-example
+</p>
+</dd>
+<dt class="hdlist1">
+Sources
+</dt>
+<dd>
+<p>
+<a href="https://dvcs.projects.maemo.org/git/?p=ContextProviderExample">https://dvcs.projects.maemo.org/git/?p=ContextProviderExample</a>
+</p>
+</dd>
+</dl></div>
+<div class="dlist"><div class="title"><tt>context-subscriber-example</tt></div><dl>
+<dt class="hdlist1">
+Languages
+</dt>
+<dd>
+<p>
+C++
+</p>
+</dd>
+<dt class="hdlist1">
+License
+</dt>
+<dd>
+<p>
+LGPL 2.1
+</p>
+</dd>
+<dt class="hdlist1">
+Provided interfaces
+</dt>
+<dd>
+<p>
+none.
+</p>
+</dd>
+<dt class="hdlist1">
+Used interfaces
+</dt>
+<dd>
+<p>
+Context.Example.* properties, libcontextsubscriber, libqt4-gui, libqt4-core
+</p>
+</dd>
+<dt class="hdlist1">
+Binary packages
+</dt>
+<dd>
+<p>
+context-subscriber-example
+</p>
+</dd>
+<dt class="hdlist1">
+Sources
+</dt>
+<dd>
+<p>
+<a href="https://dvcs.projects.maemo.org/git/?p=ContextSubscriberExample">https://dvcs.projects.maemo.org/git/?p=ContextSubscriberExample</a>
+</p>
+</dd>
+</dl></div>
+</div>
+<h2 id="_performance">Performance</h2>
+<div class="sectionbody">
+<h3 id="_general">General</h3><div style="clear:left"></div>
+<div class="paragraph"><p>The Context Framework makes no real-time guarantees and does not rely
+on any.</p></div>
+<div class="paragraph"><p>It is careful not to cause significant additional communication that
+wouldn’t be needed anyway to communicate contextual information to the
+interested parties.</p></div>
+<div class="paragraph"><p>We expect 5 to 10 providers, about 20 subscribers, each subscribed to
+an average of 5 properties. Property values can become arbitrarily
+big, but are expected to be mostly small, in the order of 10 bytes.
+The occasional big property value is expected to change
+correspondingly infrequently.</p></div>
+<h3 id="_memory">Memory</h3><div style="clear:left"></div>
+<div class="tableblock">
+<table rules="all"
+width="100%"
+frame="border"
+cellspacing="0" cellpadding="4">
+<col width="33%" />
+<col width="33%" />
+<col width="33%" />
+<tbody>
+<tr>
+<td align="left" valign="top"><p class="table">OneNAND</p></td>
+<td align="left" valign="top"><p class="table">All files are stored on the OneNAND, in their FHS mandated places</p></td>
+<td align="left" valign="top"><p class="table">200 KiB</p></td>
+</tr>
+<tr>
+<td align="left" valign="top"><p class="table">eMMC</p></td>
+<td align="left" valign="top"><p class="table">Not used</p></td>
+<td align="left" valign="top"><p class="table">0</p></td>
+</tr>
+<tr>
+<td align="left" valign="top"><p class="table">RAM/Idle</p></td>
+<td align="left" valign="top"><p class="table">A couple of bytes per subscription plus a couple more per provided property</p></td>
+<td align="left" valign="top"><p class="table">200 KiB</p></td>
+</tr>
+<tr>
+<td align="left" valign="top"><p class="table">RAM/Peak</p></td>
+<td align="left" valign="top"><p class="table">The biggest property values might reach a KiB</p></td>
+<td align="left" valign="top"><p class="table">500 KiB</p></td>
+</tr>
+</tbody>
+</table>
+</div>
+<h3 id="_runtime">Runtime</h3><div style="clear:left"></div>
+<div class="paragraph"><p>The Context Framework allows subscribers and providers to directly
+connect to each other (incurring only the usual D-Bus daemon
+overhead). Context properties are expected to change only
+infrequently and providers are urged to throttle the rate of change.</p></div>
+<div class="paragraph"><p>The contextd daemon is started on the first subscription to one of its
+properties. This is expected to happen on every boot since it
+provides properties that are used by other daemons, such as the
+context engine.</p></div>
+<h3 id="_power_consumption">Power consumption</h3><div style="clear:left"></div>
+<div class="paragraph"><p>Providers of context properties know at any time whether someone in
+the system is subscribed to them. This allows them to avoid expensive
+operations for producing values that are not needed.</p></div>
+<div class="paragraph"><p>The documentation for subscribers urges them to take the cost of
+producing property values into consideration. The subscriber API
+offers an easy way to temporarily suspend a subscription.</p></div>
+<div class="paragraph"><p>Sometimes, increased granularity of control over a property is needed:
+instead of just switching it on and off, the subscriber might want to
+request different levels of quality. For example, some subscribers
+might need a higher update frequency than others and are willing to
+pay the associated price in power consumption.</p></div>
+<div class="paragraph"><p>The recommended way to implement this increased control is to offer
+multiple properties that deliver the same value but with different
+qualities-of-service. For example, there could be both
+"Location.HighResCoordinates" and "Location.LowResCoordinates"
+properties that both deliver the current geographical coordinates.
+Subscribing to "Location.HighResCoordinates", however, would cause the
+location to be updated more frequently and maybe even activate a GPS
+device, if available.</p></div>
+</div>
+<h2 id="_security_impact">Security Impact</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Different context properties might need to have different access
+restrictions. A context provider can implement these access
+restriction in whatever way works, but should preferrably use the
+existing features of the Security Framework.</p></div>
+<div class="paragraph"><p>The Security Framework can control access per D-Bus bus connection.
+Thus, a given context provider should only implement properties with
+the same access rights and leave it to the Security Framework to allow
+or disallow connections to the provider as a whole.</p></div>
+<div class="paragraph"><p>The Context Daemon needs to follow the same rules, of course.</p></div>
+<div class="paragraph"><p>The libcontextsubscriber library listens for a special D-Bus bus name
+to appear and then allows the service behind that name to override all
+values of context properties. The library protects this special name
+with a security token so that only specially certified software can
+own this name. The context commander might or might not be certified
+in this way; instead of certifying it, it might be preferrable to
+require developers to explicitly disable the name protection (via a
+developer certificate or a general device unlocking ceremony) before
+they can use the context commander.</p></div>
+</div>
+<h2 id="_open_items">Open Items</h2>
+<div class="sectionbody">
+<div class="ulist"><ul>
+<li>
+<p>
+The D-Bus interface needs to be reviewed and maybe redesigned. It
+ might make sense to use one object path per property instead of one
+ object path per subscriber like we do now.
+</p>
+</li>
+<li>
+<p>
+Integration with Content Framework needs to be addressed. Snapshots
+ of the current context need to be imported into the content database
+ (as document tags, say) and content queries might be run
+ periodically to provide contextual information (such as the ten most
+ recently accessed documents).
+</p>
+</li>
+<li>
+<p>
+The current plan for localization of context properties requires
+ context providers to do it. They thusly need access to the current
+ device language and rumour has it that everything about l10n is
+ different in Harmattan.
+</p>
+</li>
+</ul></div>
+</div>
+<h2 id="_appendices">Appendices</h2>
+<div class="sectionbody">
+<h3 id="_the_context_framework_for_context_providers">The Context Framework for Context Providers</h3><div style="clear:left"></div>
+<div class="paragraph"><p>The advantages of the Context Framework for application writers should
+be clear: they can access a rich set of useful contextual information
+with a simple API.</p></div>
+<div class="paragraph"><p>The ultimate providers of this information, however, might feel that
+the context framework itself does not add significant value: after
+all, they already implement APIs to access all that information
+anyway. Hooking into the Context Framework means a duplication of
+effort and the requirement to express everything as a value (instead
+of a general query/response API) might be unwelcome.</p></div>
+<div class="paragraph"><p>However, the unified API and central maintenance of the list of core
+properties carries a lot of value:</p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+It makes using more contextual information trivial once you have
+ used your first property.
+</p>
+</li>
+<li>
+<p>
+It makes it possible to expose present and future context
+ information in all kinds of places with a single effort. Once the
+ context framework has been integrated into the Web runtime, into
+ Python, or into any language that people care about, no additional
+ effort is needed by anyone to track future developments of the
+ context properties.
+</p>
+</li>
+<li>
+<p>
+It decouples context providers from consumers. The context
+ framework makes it possible to move the implementation of a property
+ from one component to another without having to restart the
+ consumers.
+</p>
+</li>
+<li>
+<p>
+It makes it worthwhile to develop sophisticated tools such as the
+ context commander and support for easy automated testing of context
+ subscribers and providers.
+</p>
+</li>
+<li>
+<p>
+It might allow some context providers to exit the "API business"
+ altogether.
+</p>
+<div class="paragraph"><p>If a piece of information is available in a corner of the system but
+needed somewhere else, it is only human to see this as a nuisance
+and cobble together a few D-Bus methods to access that information.</p></div>
+<div class="paragraph"><p>The context framework provides a good alternative in those cases.</p></div>
+</li>
+</ul></div>
+<div class="paragraph"><p>It is thus our opinion that the context framework provides enough
+value to justify pushing it into other peoples subsystems, even if
+that means duplicated efforts.</p></div>
+<div class="paragraph"><p>Moreover, the effort needed to integrate with the context framework is
+low.</p></div>
+<h3 id="_relation_to_policy_engine">Relation to Policy Engine</h3><div style="clear:left"></div>
+<div class="paragraph"><p>The policy engine has the role in the Maemo platform to decide system
+global behavior and controls the various distributed enforcement
+points accordingly. This job will likely be done by OHMng.</p></div>
+<div class="paragraph"><p>The policy engine can be both a subscriber to and provider of context
+properties. The policy engine will base its decisions (partly) on the
+current values of context properties and will publish (part of) its
+decisions as context properties.</p></div>
+<div class="paragraph"><p>Most facts that need to be gathered as input for the policy engine can
+be communicted to it via the context framework. If necessary,
+non-public context properties can be defined that (while visible to
+everyone who knows where to look) are not maintained as part of the
+list of core properties.</p></div>
+<div class="paragraph"><p>Decisions of the policy engine can be communicated to cooperating
+applications and potentially even to enforcement points. The set of
+values representable as context properties is quite rich so that
+hopefully all facts and decisions can be represented with them.</p></div>
+</div>
+<div id="footer">
+<div id="footer-text">
+Last updated 2009-12-08 18:28:04 EEST
+</div>
+</div>
+</body>
+</html>
|