blob: 7acc5d29979278d5889ae9543279a34a624c602e (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head><meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
<title>libcontextsubscriber: </title>
<link href="tabs.css" rel="stylesheet" type="text/css">
<link href="doxygen.css" rel="stylesheet" type="text/css">
</head><body>
<!-- Generated by Doxygen 1.5.8 -->
<div class="navigation" id="top">
<div class="tabs">
<ul>
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="namespaces.html"><span>Namespaces</span></a></li>
<li><a href="annotated.html"><span>Classes</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
</div>
<div class="contents">
The Context Framework maintains a registry defining which context properties are currently provided and by whom. The introspection API of libcontextsubscriber allows you to inspect the current state of the registry and observe its changes.<h2><a class="anchor" name="Overview">
Overview</a></h2>
The introspection is provided via two classes: <a class="el" href="class_context_registry_info.html" title="A class to introspect the registry contents.">ContextRegistryInfo</a> and <a class="el" href="class_context_property_info.html" title="A class to introspect a context property details.">ContextPropertyInfo</a>.<p>
<a class="el" href="class_context_registry_info.html" title="A class to introspect the registry contents.">ContextRegistryInfo</a> provides a high-level view to the registry contents. You can use it to obtain info about the list of currently available keys or e.g. get a list of keys for one particular provider. <a class="el" href="class_context_registry_info.html" title="A class to introspect the registry contents.">ContextRegistryInfo</a> is a singleton instance which is created on the first access.<p>
<a class="el" href="class_context_property_info.html" title="A class to introspect a context property details.">ContextPropertyInfo</a> is used to obtain metadata about one particular key. Once created, it can be used to retrieve the type and provider information (DBus bus type and name) of the introspected key. It also provides a signal to listen for changes happening to a key.<h2><a class="anchor" name="Usage">
Usage</a></h2>
<div class="fragment"><pre class="fragment"> <span class="comment">// To get a list of all keys in the registry</span>
<a class="code" href="class_context_registry_info.html" title="A class to introspect the registry contents.">ContextRegistryInfo</a> *context = <a class="code" href="class_context_registry_info.html#93a34519ddb495338876ba0e1d1a4247" title="Returns the singleton instance of the ContextRegistryInfo.">ContextRegistryInfo::instance</a>();
QStringList currentKeys = context-><a class="code" href="class_context_registry_info.html#963309761292d39921da3fb06cb31060" title="Returns the list of all the keys currently availible in the registry.">listKeys</a>();
</pre></div><p>
Using the <a class="el" href="class_context_property_info.html" title="A class to introspect a context property details.">ContextPropertyInfo</a> is even more straight-forward.<p>
<div class="fragment"><pre class="fragment"> <span class="comment">// To check the type of a particular key</span>
<a class="code" href="class_context_property_info.html" title="A class to introspect a context property details.">ContextPropertyInfo</a> propInfo(<span class="stringliteral">"Battery.ChargeLevel"</span>);
QString propType = propInfo.type();
</pre></div><p>
The introspection API in general never asserts (never fails). It'll return empty strings on errors or if data is missing. For example:<p>
<div class="fragment"><pre class="fragment"> <a class="code" href="class_context_property_info.html" title="A class to introspect a context property details.">ContextPropertyInfo</a> propInfo(<span class="stringliteral">"Something.That.Doesnt.Exist"</span>);
propInfo.type(); <span class="comment">// ...returns empty string</span>
propInfo.doc(); <span class="comment">// ...returns empty string</span>
</pre></div><p>
You can use this functionality to wait for keys to become available in the registry. Just create a <a class="el" href="class_context_property_info.html" title="A class to introspect a context property details.">ContextPropertyInfo</a> for a key that you're expecting to become present and connect to the <code>changed</code> signal.<p>
<div class="fragment"><pre class="fragment"> <a class="code" href="class_context_property_info.html" title="A class to introspect a context property details.">ContextPropertyInfo</a> propInfo(<span class="stringliteral">"Something.That.Doesnt.Exist"</span>);
propInfo.declared(); <span class="comment">// false</span>
<span class="comment">// Connect something to the changed signal, keep checking it</span>
</pre></div><h2><a class="anchor" name="xmlvscdb">
XML vs.CDB</a></h2>
When the introspection API is first used, a backend choice is being made. <b>CDB</b> backend (reading data from <code>'cache</code>.cdb' ) is used if the tiny database cache file exists in the registry. The standard (slower) <b>XML</b> backend is used in other cases.<p>
It's possible to force a usage of a particular backend. This can be done by calling the <code>instance</code> method with a string name of the backend:<p>
<div class="fragment"><pre class="fragment"> <a class="code" href="class_context_registry_info.html#93a34519ddb495338876ba0e1d1a4247" title="Returns the singleton instance of the ContextRegistryInfo.">ContextRegistryInfo::instance</a>(<span class="stringliteral">"cdb"</span>); <span class="comment">// or "xml"</span>
</pre></div><p>
This needs to be done early enough before the introspection API is first used. For more information about the <b>xml</b> and backends read the <a class="el" href="updatingcontextproviders.html">UpdatingContextProviders</a> page. </div>
<hr size="1"><address style="text-align: right;"><small>Generated on Fri Oct 23 08:59:23 2009 for libcontextsubscriber by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.8 </small></address>
</body>
</html>
|
