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
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
|
<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<refentry id="GypsyControl">
<refmeta>
<refentrytitle role="top_of_page" id="GypsyControl.top_of_page">GypsyControl</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GYPSY Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>GypsyControl</refname>
<refpurpose>Control object for gypsy-daemon</refpurpose>
</refnamediv>
<refsynopsisdiv id="GypsyControl.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>
<synopsis>
<link linkend="GypsyControl-struct">GypsyControl</link>;
#define <link linkend="GYPSY-CONTROL-DBUS-SERVICE--CAPS">GYPSY_CONTROL_DBUS_SERVICE</link>
#define <link linkend="GYPSY-CONTROL-DBUS-PATH--CAPS">GYPSY_CONTROL_DBUS_PATH</link>
#define <link linkend="GYPSY-CONTROL-DBUS-INTERFACE--CAPS">GYPSY_CONTROL_DBUS_INTERFACE</link>
<link linkend="GypsyControl">GypsyControl</link> * <link linkend="gypsy-control-get-default">gypsy_control_get_default</link> (void);
<link linkend="char">char</link> * <link linkend="gypsy-control-create">gypsy_control_create</link> (<link linkend="GypsyControl">GypsyControl</link> *control,
const <link linkend="char">char</link> *device_name,
<link linkend="GError">GError</link> **error);
</synopsis>
</refsynopsisdiv>
<refsect1 id="GypsyControl.object-hierarchy" role="object_hierarchy">
<title role="object_hierarchy.title">Object Hierarchy</title>
<synopsis>
<link linkend="GObject">GObject</link>
+----GypsyControl
</synopsis>
</refsect1>
<refsect1 id="GypsyControl.description" role="desc">
<title role="desc.title">Description</title>
<para>
<link linkend="GypsyControl"><type>GypsyControl</type></link> is the object that controls the gypsy-daemon process.
It is a singleton object, meaning that there will only be one instance of it
per application. Once the object has been created (or referenced if it
had already been created for the application) with
<link linkend="gypsy-control-get-default"><function>gypsy_control_get_default()</function></link>, it can be used to tell gypsy-daemon what GPS
device to connect to with <link linkend="gypsy-control-create"><function>gypsy_control_create()</function></link>. This call returns the
D-Bus object path to the GPS object in gypsy-daemon. This object path is then used to
create other objects, such as <link linkend="GypsyPosition"><type>GypsyPosition</type></link>, or <link linkend="GypsyCourse"><type>GypsyCourse</type></link>.
</para>
<para>
As gypsy-daemon is able to connect to multiple GPS devices, the one
<link linkend="GypsyControl"><type>GypsyControl</type></link> can be used to create them, returning a different path for each
GPS device. Gypsy-daemon can connect to both serial port devices which have
an entry in <filename>/dev</filename> and Bluetooth devices natively without
the need to use rfcomm to set up a <filename>/dev</filename> entry. To do
this you pass either the device path or the Bluetooth address of the device
to <link linkend="gypsy-control-create"><function>gypsy_control_create()</function></link>.
</para>
<para>
Once the program has finished with the GPS, the <link linkend="GypsyControl"><type>GypsyControl</type></link> object should
by unreferenced with <link linkend="g-object-unref"><function>g_object_unref()</function></link>.
</para>
<para>
<informalexample>
<programlisting>
. . .
<link linkend="GypsyControl">GypsyControl</link> *control;
char *path_bt, *path_dev;
GError *error = NULL;
. . .
control = gypsy_control_get_default ();
/ * Use a Bluetooth device * /
path_bt = gypsy_control_create (control, "aa:bb:cc:dd:ee", &error);
if (path_bt == NULL) {
g_warning ("There was an error creating aa:bb:cc:dd:ee - %s", error->message);
g_error_free (error);
error = NULL;
}
/ * Use a serial port device * /
path_dev = gypsy_control_create (control, "/dev/gps", &error);
if (path_dev == NULL) {
g_warning ("There was an error creating /dev/gps - %s", error->message);
g_error_free (error);
error = NULL;
}
. . .
/ * Use the paths here to create listener objects * /
. . .
g_free (path_bt);
g_free (path_dev);
. . .
/ * The program has finished with Gypsy now, unref the object. * /
g_object_unref (G_OBJECT (control));
</programlisting>
</informalexample></para>
<para>
</para>
</refsect1>
<refsect1 id="GypsyControl.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="GypsyControl-struct" role="struct">
<title>GypsyControl</title>
<indexterm zone="GypsyControl-struct"><primary sortas="GypsyControl">GypsyControl</primary></indexterm><programlisting>typedef struct _GypsyControl GypsyControl;</programlisting>
<para>
There are no public fields in <link linkend="GypsyControl"><type>GypsyControl</type></link>.</para>
<para>
</para></refsect2>
<refsect2 id="GYPSY-CONTROL-DBUS-SERVICE--CAPS" role="macro">
<title>GYPSY_CONTROL_DBUS_SERVICE</title>
<indexterm zone="GYPSY-CONTROL-DBUS-SERVICE--CAPS"><primary sortas="GYPSY_CONTROL_DBUS_SERVICE">GYPSY_CONTROL_DBUS_SERVICE</primary></indexterm><programlisting>#define GYPSY_CONTROL_DBUS_SERVICE "org.freedesktop.Gypsy"
</programlisting>
<para>
A define containing the service name of the control service</para>
<para>
</para></refsect2>
<refsect2 id="GYPSY-CONTROL-DBUS-PATH--CAPS" role="macro">
<title>GYPSY_CONTROL_DBUS_PATH</title>
<indexterm zone="GYPSY-CONTROL-DBUS-PATH--CAPS"><primary sortas="GYPSY_CONTROL_DBUS_PATH">GYPSY_CONTROL_DBUS_PATH</primary></indexterm><programlisting>#define GYPSY_CONTROL_DBUS_PATH "/org/freedesktop/Gypsy"
</programlisting>
<para>
A define containing the object path of the Gypsy object</para>
<para>
</para></refsect2>
<refsect2 id="GYPSY-CONTROL-DBUS-INTERFACE--CAPS" role="macro">
<title>GYPSY_CONTROL_DBUS_INTERFACE</title>
<indexterm zone="GYPSY-CONTROL-DBUS-INTERFACE--CAPS"><primary sortas="GYPSY_CONTROL_DBUS_INTERFACE">GYPSY_CONTROL_DBUS_INTERFACE</primary></indexterm><programlisting>#define GYPSY_CONTROL_DBUS_INTERFACE "org.freedesktop.Gypsy.Server"
</programlisting>
<para>
A define containing the name of the Control interface</para>
<para>
</para></refsect2>
<refsect2 id="gypsy-control-get-default" role="function">
<title>gypsy_control_get_default ()</title>
<indexterm zone="gypsy-control-get-default"><primary sortas="gypsy_control_get_default">gypsy_control_get_default</primary></indexterm><programlisting><link linkend="GypsyControl">GypsyControl</link> * gypsy_control_get_default (void);</programlisting>
<para>
Retrieves the default <link linkend="GypsyControl"><type>GypsyControl</type></link> object.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> A singleton <link linkend="GypsyControl"><type>GypsyControl</type></link>. Once the program has finished using
the <link linkend="GypsyControl"><type>GypsyControl</type></link>, it should be unreferenced with <link linkend="g-object-unref"><function>g_object_unref()</function></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="gypsy-control-create" role="function">
<title>gypsy_control_create ()</title>
<indexterm zone="gypsy-control-create"><primary sortas="gypsy_control_create">gypsy_control_create</primary></indexterm><programlisting><link linkend="char">char</link> * gypsy_control_create (<link linkend="GypsyControl">GypsyControl</link> *control,
const <link linkend="char">char</link> *device_name,
<link linkend="GError">GError</link> **error);</programlisting>
<para>
Creates a object on the server that refers to the GPS device at <parameter>device_name</parameter>.
When this object is finalized, the remote object on the server will be
shutdown after which any calls to the object at the returned path
are not guaranteed to work.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>control</parameter> :</term>
<listitem><simpara> The <link linkend="GypsyControl"><type>GypsyControl</type></link> device
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>device_name</parameter> :</term>
<listitem><simpara> The path to the device file, or Bluetooth address
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter> :</term>
<listitem><simpara> A <link linkend="GError"><type>GError</type></link> to return errors in, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The path to the created object.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
</refsect1>
</refentry>
|
