/usr/share/gtk-doc/html/geoclue/ch01.html is in libgeoclue-dev 0.12.0-1ubuntu12.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Using Geoclue in applications</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
<link rel="home" href="index.html" title="Geoclue Reference Manual">
<link rel="up" href="index.html" title="Geoclue Reference Manual">
<link rel="prev" href="index.html" title="Geoclue Reference Manual">
<link rel="next" href="simple-example.html" title="Using basic Geoclue providers: simple example in C">
<meta name="generator" content="GTK-Doc V1.13 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
<link rel="chapter" href="ch01.html" title="Using Geoclue in applications">
<link rel="reference" href="rn01.html" title="C API">
<link rel="reference" href="rn02.html" title="D-Bus API">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
<td><a accesskey="p" href="index.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
<td> </td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
<th width="100%" align="center">Geoclue Reference Manual</th>
<td><a accesskey="n" href="simple-example.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
</tr></table>
<div class="chapter" title="Using Geoclue in applications">
<div class="titlepage"><div><div><h2 class="title">
<a name="id2766027"></a>Using Geoclue in applications</h2></div></div></div>
<div class="toc"><dl>
<dt><span class="section"><a href="ch01.html#overview">Overview</a></span></dt>
<dt><span class="section"><a href="simple-example.html">Using basic Geoclue providers: simple example in C</a></span></dt>
<dt><span class="section"><a href="simple-master-example.html">Master provider: simple example in C</a></span></dt>
</dl></div>
<div class="section" title="Overview">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="overview"></a>Overview</h2></div></div></div>
<div class="sect2">
<div class="titlepage"><div><div><h4 class="subtitle">Why use Geoclue</h4></div></div></div>
<p>
Building context-sensitive applications is difficult. Location-sensitivy is no
exception, but Geoclue tries to help there. With Geoclue it is possible to build
location-aware applications with less work and less knowledge about the actual
geoinformation sources.
</p>
<p> Main features of Geoclue are:
</p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">Standardized D-Bus (and GObject) interfaces to various geographical data sources</li>
<li class="listitem">Easy and fast to implement: Need to get data from provider XYZ?
Chances are, Geoclue is the easiest way to do that...</li>
<li class="listitem">Geoclue Master provider (experimental at the moment) makes things eaven easier:
you don't even have to choose a data provider, just let Geoclue choose the
best possible provider for you.</li>
<li class="listitem">Adding new providers (data sources) is straight-forward: Even when the geoinformation
source you want is not already in Geoclue, Implementing a Geoclue provider may
well turn out to be the easiest way forward.</li>
</ul></div>
<p>
</p>
</div>
<div class="sect2">
<div class="titlepage"><div><div><h4 class="subtitle">Requirements</h4></div></div></div>
<p>
Geoclue is a collection of D-Bus APIs. Internally it's implemented with GLib and GObject (as is the C wrapper library).
Several included providers also use Libxml2, and the master provider uses GConf.
</p>
<p>
There is a GObject-based C API, but using Geoclue is possible from any programming language
with D-Bus support.
</p>
</div>
<div class="sect2">
<div class="titlepage"><div><div><h4 class="subtitle">Using basic Geoclue providers</h4></div></div></div>
<p>
D-Bus can automatically start services as they're needed so basic method calls
can be made without any preparation. However, geoclue providers may shut down when
they're not used. This means that clients using signals and clients that set any options
should always use AddReference() and RemoveReference() methods to ensure server
persistence. In C the wrapper takes care of this.
</p>
<p>
Clients should not assume that method calls will return instantly or that the
response will contain valid data. Examples of possible problems
</p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">Many geoclue providers use web services so method calls may take seconds or even time out.</li>
<li class="listitem">GPS providers usually respond instantly, but will not have a valid data until after getting a fix (which may take anything from a few seconds to minutes)</li>
</ul></div>
<p>
Using signals should be the first option whenever the used provider supports them.
When signals are not available, asynchronous method calls can be used in
applications where UI responsiveness is important.
</p>
</div>
<div class="sect2">
<div class="titlepage"><div><div><h4 class="subtitle">Using Geoclue Master</h4></div></div></div>
<p>Master provider was designed to solve the following problems:
</p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">A single provider cannot be the best solution to all problems</li>
<li class="listitem">The "best" providers will be different depending on the user</li>
<li class="listitem">Supporting a single geodata source can be a big job for an application developer, supporting several would be a nightmare</li>
</ul></div>
<p>
</p>
<p>
Master provider implements the same interfaces as regular providers, but internally
it uses whichever regular provider happens to be the best one (with "best" defined as
a provider that fulfills the accuracy requirements and does not surpass resource restrictions).
The internally used provider may change over time -- this does not interrupt clients use in any way,
but the changes can be observed using the MasterClient API.
</p>
<p>
A typical Master provider use includes:
</p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">Getting a client-specific GeoclueMasterClient from GeoclueMaster</li>
<li class="listitem">Setting GeoclueMasterClient requirements (such as accuracy)</li>
<li class="listitem">Starting the wanted interfaces (such as Position) </li>
<li class="listitem">Using the client just like a regular provider</li>
</ul></div>
<p>
</p>
<p>
Master provider is fairly new and may not be as stable as the rest of Geoclue.
</p>
</div>
<div class="sect2">
<div class="titlepage"><div><div><h4 class="subtitle">Current providers</h4></div></div></div>
TODO: list the providers shipped with geoclue, shortly explain their features.
</div>
</div>
</div>
<div class="footer">
<hr>
Generated by GTK-Doc V1.13</div>
</body>
</html>
|