[maemo-commits] [maemo-commits] r17296 - in projects/haf/doc/mvo: . context

Tue Jan 27 16:35:34 EET 2009

Author: marivoll
Date: 2009-01-27 16:35:21 +0200 (Tue, 27 Jan 2009)
New Revision: 17296

Added:
   projects/haf/doc/mvo/context/
   projects/haf/doc/mvo/context/subsys-context-framework.html
Log:
New.


Added: projects/haf/doc/mvo/context/subsys-context-framework.html
===================================================================

--- projects/haf/doc/mvo/context/subsys-context-framework.html	2009-01-27 14:19:42 UTC (rev 17295)
+++ projects/haf/doc/mvo/context/subsys-context-framework.html	2009-01-27 14:35:21 UTC (rev 17296)
@@ -0,0 +1,551 @@
+<!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.2.7" />
+<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,
+div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
+div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
+div.admonitionblock {
+  margin-right: 10%;
+  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 {
+  margin-right: 0%;
+}
+div.listingblock > div.content {
+  border: 1px solid silver;
+  background: #f4f4f4;
+  padding: 0.5em;
+}
+
+div.quoteblock {
+  padding-left: 2.0em;
+}
+div.quoteblock > div.attribution {
+  padding-top: 0.5em;
+  text-align: right;
+}
+
+div.verseblock {
+  padding-left: 2.0em;
+}
+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;
+}
+dd > *:first-child {
+  margin-top: 0.1em;
+}
+
+ul, ol {
+    list-style-position: outside;
+}
+div.olist > ol {
+  list-style-type: decimal;
+}
+div.olist2 > ol {
+  list-style-type: lower-alpha;
+}
+
+div.tableblock > table {
+  border: 3px solid #527bbd;
+}
+thead {
+  font-family: sans-serif;
+  font-weight: bold;
+}
+tfoot {
+  font-weight: bold;
+}
+
+div.hlist {
+  margin-top: 0.8em;
+  margin-bottom: 0.8em;
+}
+div.hlist td {
+  padding-bottom: 15px;
+}
+td.hlist1 {
+  vertical-align: top;
+  font-style: normal;
+  padding-right: 0.8em;
+}
+td.hlist2 {
+  vertical-align: top;
+}
+
+ at 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; }
+
+/* Because IE6 child selector is broken. */
+div.olist2 ol {
+  list-style-type: lower-alpha;
+}
+div.olist2 div.olist ol {
+  list-style-type: decimal;
+}
+</style>
+<title>Context Framework</title>
+</head>
+<body>
+<div id="header">
+<h1>Context Framework</h1>
+</div>
+<h2 id="_introduction">Introduction</h2>
+<div class="sectionbody">
+<div class="para"><p>The Context Framework 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="para"><p>Applications access context properties via <tt>DuiValueSpaceItems</tt> in the
+<a href="../libduivaluespace/index.html"><tt>DuiValueSpace</tt></a>.</p></div>
+<div class="para"><p>The context framework is modular: context properties from multiple
+independent components are directly combined in the <tt>DuiValueSpace</tt> API
+and applications can access them without needing to know who is
+ultimately providing them.</p></div>
+<div class="para"><p>The <a href="../libduivaluespace/index.html"><tt>DuiValueSpace</tt></a> API is intended to be
+general; other subsystems that communicate in terms of key/value pairs
+can use it as well.  The Settings framework is an obvious candidate.</p></div>
+<div class="para"><p>A component that wants to directly provide context properties needs to
+implement the relevant interfaces defined by the context framework.
+Specifically, such a component must put a object on the session or
+system D-Bus that implements the
+<a href="../org.freedesktop.ContextKit.Manager/index.html"><tt>org.freedesktop.ContextKit.Manager</tt></a> interface and register that
+object with the context framework.</p></div>
+<div class="para"><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 new context properties and for absorbing properties from
+existing subsystems that have aqcuired them by accident and would
+rather get rid of them.</p></div>
+<div class="para"><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="para"><p>To summarize, the context framework contributes value to the Maemo
+platform in the following ways:</p></div>
+<div class="ilist"><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.
+</p>
+</li>
+<li>
+<p>
+It implements context properties that do not naturally belong to
+  other subsystems.
+</p>
+</li>
+</ul></div>
+<div class="para"><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.  However, 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="_interfaces">Interfaces</h2>
+<div class="sectionbody">
+<div class="para"><div class="title"><tt>libduivaluespace</tt></div><p>The DuiValueSpace class and friends.  Applications and other clients
+of context properties written in C++ should use this.  This API needs
+bindings for other platform languages, maybe including C.</p></div>
+<div class="para"><p><a href="../libduivaluespace/index.html">Documentation</a></p></div>
+<div class="listingblock">
+<div class="title">Example: Listening to the spatial orientation</div>
+<div class="content"><!-- Generator: GNU source-highlight 2.4
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #000080">#include</span></span> <span style="color: #FF0000">&lt;blah.h&gt;</span>
+
+<span style="font-style: italic"><span style="color: #9A1900">// David</span></span>
+
+</tt></pre></div></div>
+<div class="para"><div class="title"><tt>contextkit-providers</tt></div><p>The interface to register providers of context properties.  A provider
+must implement the <tt>org.freedesktop.ContextKit.Manager</tt> D-Bus
+interface.</p></div>
+<div class="listingblock">
+<div class="title">Example: Registering the <tt>do-you-feel-lucky.punk</tt> property</div>
+<div class="content"><!-- Generator: GNU source-highlight 2.4
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">&lt;context&gt;</span></span>
+  ... Rob, David
+<span style="font-weight: bold"><span style="color: #0000FF">&lt;/context&gt;</span></span>
+</tt></pre></div></div>
+<div class="para"><p><a href="../contextkit-providers/index.html">Documentation</a></p></div>
+<div class="para"><div class="title"><tt>org.freedesktop.ContextKit.Manager</tt></div><p>The D-Bus interface that every context provider needs to implement.</p></div>
+<div class="para"><p><a href="../org.freedesktop.ContextKit.Manager/index.html">Documentation</a></p></div>
+<div class="para"><div class="title"><tt>libcontextprovider</tt></div><p>A convenience library for implementing the
+api:org.freedesktop.ContextKit.Manager D-Bus interface.</p></div>
+<div class="listingblock">
+<div class="title">Example: Providing the <tt>do-you-feel-lucky.punk</tt> property</div>
+<div class="content"><!-- Generator: GNU source-highlight 2.4
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #000080">#include</span></span> <span style="color: #FF0000">&lt;blah.h&gt;</span>
+
+<span style="font-style: italic"><span style="color: #9A1900">// Rob</span></span>
+</tt></pre></div></div>
+<div class="para"><p><a href="../libcontextprovider/index.html">Documentation</a></p></div>
+<div class="para"><div class="title"><tt>dui-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="para"><p><a href="../dui-context-properties/index.html">Documentation</a></p></div>
+</div>
+<h2 id="_architecture">Architecture</h2>
+<div class="sectionbody">
+<div class="para"><p>Context properties are collected from all providers that have
+registered themselves with the api:libduivaluespace-context-providers
+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="para"><p>This registration information is read by the <tt>libduivaluespace</tt>
+library and used by its <tt>DuiValueSpace</tt> class to connect a requested
+<tt>DuiValueSpaceItem</tt> to the right bus name.</p></div>
+<div class="para"><p>The registration information is compiled into a <em>registry</em> that is
+optimized for use by <tt>DuiValueSpace</tt>.  When the set of registered
+properties changes, the registry is recompiled by a command line
+utility provided by the context framework.  This will then trigger all
+<tt>DuiValueSpace</tt> instances to reload the registry information, and
+existing <tt>DuiValueSpaceItems</tt> to be updated.</p></div>
+<div class="para"><p>When providers are installed from packages, recompilation of the
+registry 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="para"><p><tt>DuiValueSpace</tt> gracefully handles start, stop and restart of the
+providers. During system startup some applications may start to use
+the Context Framework before all providers are available. Properties
+become dynamically available in <tt>DuiValueSpace</tt> as providers become
+available, and removed when providers are no longer available.</p></div>
+<div class="para"><p>Communication between a <tt>DuiValueSpaceItem</tt> and the provider happens
+with the api:org.freedesktop.ContextKit.Manager interface.  This
+interface allows for bulk retrieval of property values, bulk
+subscriptions, and bulk change notification.</p></div>
+<div class="para"><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.</p></div>
+<div class="para"><p>In the api:org.freedesktop.ContextKit.Manager interface, property
+values are represented as D-Bus values, which map nicely to
+<tt>QVariant</tt>s (except for the <em>null</em> value which is handled
+specially).</p></div>
+<div class="para"><p>Context providers need to implement the
+api:orf.freedesktop.ContextKit.Manager interface.  They can do it
+directly, or with the help of the api:libcontextprovider
+convenience library.  This library is used by the context daemon
+itself, which can serve as an extended example.</p></div>
+<div class="para"><p>Initially, at least the
+<a href="../subsys-connectivity/index.html">Connectivity Framework</a> and the
+<a href="../subsys-location/index.html">Location Framework</a> are expected to
+be context providers as described above.  Additional context
+properties are implemented by the <em>context daemon</em> contained in the
+Context Framework.</p></div>
+<div class="svg">
+<object type="image/svg+xml" data="fig1.svg" width=800></object>
+</div>
+</div>
+<h2 id="_development_support">Development support</h2>
+<div class="sectionbody">
+<div class="para"><p>The Context Framework provides a simple test application to watch all
+available context properties.  This can be used to test context
+providers during development.</p></div>
+<div class="para"><p>In addition, the test application can be used to force context
+properties to arbitrary values.  This can be used to test the reaction
+of applications to context changes.</p></div>
+<div class="para"><p>The test application is intended to run on the device and either show
+its UI on the device itself or export it to an external X11 server.
+This way, the testing can be done without disturbing the display of
+the device itself.</p></div>
+</div>
+<h2 id="_security_considerations">Security considerations</h2>
+<div class="sectionbody">
+<div class="para"><p>Context properties might need to have different access restrictions.
+The Security Framework can control access per D-Bus bus connection and
+a Context Provider should therefore use the features of the Security
+Framework to restrict access to itself.</p></div>
+</div>
+<h2 id="_source">Source</h2>
+<div class="sectionbody">
+<div class="para"><div class="title"><tt>libduivaluespace</tt></div><p>Languages: C++</p></div>
+<div class="para"><p>Licenses: LGPL2.1</p></div>
+<div class="para"><p>Provided interfaces: libduivaluespace, contextkit-providers</p></div>
+<div class="para"><div class="title"><tt>contextkit</tt></div><p>Languages: C, Vala</p></div>
+<div class="para"><p>License: LGPL 2.1</p></div>
+<div class="para"><p>Provided interfaces: org.freedesktop.ContextKit, libcontextprovider, dui-context-properties</p></div>
+</div>
+<div id="footer">
+<div id="footer-text">
+Last updated 2009-01-26 11:31:23 EEST
+</div>
+</div>
+</body>
+</html>


