This file is indexed.

/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>