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
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
|
<?xml version="1.0"?>
<node name="/" xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd">
<interface name="org.syncevolution.Server">
<doc:doc>
<doc:para>
Server is the entry object for SyncEvolution client API. It
can be used to query information and to start and monitor
sessions.
</doc:para>
<doc:para>
Sessions are required to modify the state of SyncEvolution and
to synchronize data. They are implemented by additional
objects, which exist as long as they are needed (= have
clients) or are executing (for example, running a sync
session).
</doc:para>
<doc:para>
A session must be active before it can be used. If there are
multiple conflicting session requests, they will be queued and
started one after the other. At the moment, SyncEvolution
will only run one session at a time, although the API would
allow concurrent sessions.
</doc:para>
<doc:para>
To be notified when a session is ready for use, subscribe to
the SessionChanged signal before asking for a session. It
may fire before the request to create a session returns. Either
handle that or use Session.GetStatus() to check whether the
session is still "queueing".
</doc:para>
<doc:para>
Method calls may fail with the following errors:
"org.syncevolution.Exception" - catch-all error condition.
"org.syncevolution.NoSuchConfig" - server configuration name is invalid
"org.syncevolution.NoSuchSource" - source name is invalid
"org.syncevolution.SourceUnusable" - CheckSource() may return this
if source is not usable (for various possible reasons).
"org.syncevolution.InvalidCall" - a call is (perhaps no longer) allowed
or suitable in the current situation, like Detach() when the client
is not attached.
</doc:para>
</doc:doc>
<method name="Attach">
<doc:doc>
<doc:description>
With no client attached, the server will shut down after a
certain period of inactivity. Attaching to the server
prevents that. Attaching is not necessary to invoke methods.
The main purpose is to keep the server running while clients
are around and listen for signals, in particular the
Presence signal.
Each attach has to be matched by one detach, so that one client has
the capability to attach to the server many times in different
modules. The behavior of calling Detach() more often than Attach()
is undefined.
</doc:description>
</doc:doc>
</method>
<method name="Detach">
<doc:doc>
<doc:description>
Detaches an attached client. A client which disconnects
from D-Bus is automatically detached from the server.
</doc:description>
</doc:doc>
</method>
<method name ="GetConfigs">
<doc:doc><doc:description>
Get an array of all configured servers (or templates)
In getting templates mode, the dbus server checks all paired devices
from bluez daemon and filters them by SyncML capability. Then it
looks through built-in templates and returns their matched templates.
Multiple templates might be created for each device, with different
matching scores(range: 1-5). Scores represent how well the device name
matches a template. The higher, the better.
A template might be used to help creation for multiple devices. Thus template
names must be reset in a naming rule. They are re-named with 'Bluetooth_<
mac address>_<sequence number>'. Here 'mac address' is the mac
address of the Bluetooth device and 'sequence number' enumerates all the
matched templates created for the device.
When retrieving the templates with GetConfig(), several additional
properties will be returned:
description - the description for the template (non-localized string)
score - the calculated score based on the device name and template (1-5, 5 is best)
deviceName - the device name that the template is for (copied verbatim from that device)
templateName - string identifying the class of devices the templates works for,
like "Nokia S40"; meant to be shown to users; optional, fall back
to first entry in fingerPrint if not set
fingerPrint - comma separated list of devices which work with this template,
typically in "vendor model" format; can be used by D-Bus
clients to re-match with user provided device information
Together with these changes, a property value is changed: 'syncURL' in the
configuration is replaced with the mac address of the device.
</doc:description></doc:doc>
<arg type="b" name="template" direction="in">
<doc:doc><doc:summary>
if TRUE, will return template names, otherwise will return
configured servers
</doc:summary></doc:doc>
</arg>
<arg type="as" name="servers" direction="out">
<doc:doc><doc:summary>
array of configured server (or template) names
</doc:summary></doc:doc>
</arg>
</method>
<method name="GetConfig">
<doc:doc><doc:description>
Get the configuration of a specific server (or template)
</doc:description></doc:doc>
<arg type="s" name="server" direction="in">
<doc:doc><doc:summary>server name</doc:summary></doc:doc>
</arg>
<arg type="b" name="template" direction="in">
<doc:doc><doc:summary>
if TRUE, will return a matching template configuration, otherwise
will return a matching server configuration
</doc:summary></doc:doc>
</arg>
<arg type="a{sa{ss}}" name="configuration" direction="out">
<doc:doc><doc:summary>
server (or template) configuration
</doc:summary></doc:doc>
<doc:doc><doc:description>
The dictionary keys are "source/<source name>" for
sources and the empty string for the main server
configuration. More keys might be added in the future. The
values are "configuration dictionaries" which contain keys
and values matching those in the SyncEvolution server
configuration files.
Properties which are not set are also not present in the
configuration dictionaries. The semantic difference between
"not set" and "empty" or "set to default" is that unset
values will always use the default value, even after that
changed during a software update. Properties that are set
always use the chosen value.
Note that property keys are case insensitive. The D-Bus
interface specification would allow to send two
properties whose keys only differ in case to the
server. The result is undefined.
</doc:description></doc:doc>
</arg>
</method>
<method name="CheckPresence">
<doc:doc><doc:description>
Checks whether a sync with a particular server can start.
</doc:description></doc:doc>
<arg type="s" name="server" direction="in">
<doc:doc><doc:summary>server name</doc:summary></doc:doc>
</arg>
<arg type="s" name="status" direction="out">
<doc:doc>
<doc:summary>
See Presence signal for details.
</doc:summary>
</doc:doc>
</arg>
<arg type="as" name="transports" direction="out">
<doc:doc>
<doc:summary>
All currently available transports. See Presence signal for details.
</doc:summary>
</doc:doc>
</arg>
</method>
<method name="GetReports">
<doc:doc><doc:description>
Get synchronization reports for a specific server
</doc:description></doc:doc>
<arg type="s" name="server" direction="in">
<doc:doc><doc:summary>server name</doc:summary></doc:doc>
</arg>
<arg type="u" name="start" direction="in">
<doc:doc><doc:summary>
index of the first (newest) report that will be returned;
reports are number starting with zero for the newest
</doc:summary></doc:doc>
</arg>
<arg type="u" name="count" direction="in">
<doc:doc><doc:summary>
maximum number of returned reports
</doc:summary></doc:doc>
</arg>
<arg type="aa{ss}" name="reports" direction="out">
<doc:doc><doc:summary>synchronization reports</doc:summary></doc:doc>
<doc:doc><doc:description>The array contains report dictionaries. The dictionary keys can be defined by below BNFs:
Key ::= 'dir' | 'peer' | 'start' | 'end' | 'status' | 'error' | SourceKey
SourceKey ::= SourcePrefix SourcePart
SourcePrefix ::= 'source' Sep SourceName
SourceName ::= character+
SourcePart ::= Sep ('mode' | 'first' | 'resume' | 'status' | 'backup-before'
| 'backup-after' | StatPart)
StatPart ::= 'stat' Sep LocName Sep StateName Sep ResultName
LocName ::= 'local' | 'remote'
StateName ::= 'added' | 'updated' | 'removed' | 'any'
ResultName ::= 'total' | 'reject' | 'match' | 'conflict_server_won' | 'conflict_client_won'
| 'conflict_duplicated' | 'sent' | 'received'
Sep ::= '-'
If SourceName has characters '_' and '-', they will be
escaped with '__' and '_+' respectively. This means
that a key can be split at '-' before replacing these
escape sequences in the source name.
For a key which contains StatPart, if its value is 0,
its pair-value won't be included in the dictionary.
</doc:description></doc:doc>
</arg>
</method>
<method name="GetDatabases">
<doc:doc>
<doc:description>
Get list of available databases that can be synchronized
by a source backend.
</doc:description>
</doc:doc>
<arg type="s" name="server" direction="in">
<doc:doc><doc:summary>server name</doc:summary></doc:doc>
</arg>
<arg type="s" name="source" direction="in">
<doc:doc>
<doc:summary>
name of the source configuration which defines
the backend ("type" property)
</doc:summary>
</doc:doc>
</arg>
<arg type="a(ssb)" name="databases" direction="out">
<doc:doc><doc:summary>information about all available databases</doc:summary></doc:doc>
<doc:doc>
<doc:description>
each entry contains in this order:
an optional name that can be shown to the user
(already localized or chosen by the user, empty if unavailable),
a unique value for the "evolutionSource" property,
a boolean which is true at most once for the default source
</doc:description>
</doc:doc>
</arg>
</method>
<method name="CheckSource">
<doc:doc>
<doc:description>Tests whether the source configuration
is correct. Raises the SourceUnusable exception if not.
</doc:description>
</doc:doc>
<arg type="s" name="server" direction="in">
<doc:doc><doc:summary>server name</doc:summary></doc:doc>
</arg>
<arg type="s" name="source" direction="in">
<doc:doc>
<doc:summary>
name of the source configuration which is to be tested
</doc:summary>
</doc:doc>
</arg>
</method>
<method name="StartSession">
<doc:doc><doc:description>
Start a session. The object is created instantly but will not be
ready for method calls until status changes from "queueing" to "idle".
The Detach() method can be called before that.
</doc:description></doc:doc>
<arg type="s" name="server" direction="in">
<doc:doc><doc:summary>server name</doc:summary></doc:doc>
</arg>
<arg type="o" name="session" direction="out">
<doc:doc><doc:summary>session D-Bus object path</doc:summary></doc:doc>
</arg>
</method>
<method name="Connect">
<doc:doc>
<doc:description>
<doc:para>
Establishes a connection between SyncEvolution and a peer
(SyncML client or server). That peer might contact
SyncEvolution via D-Bus directly (local sync) or via a
SyncEvolution server stub that acts as gateway between a
peer that is connected to the stub via some other
transport mechanism (remote sync). For SyncEvolution this
difference is almost completely transparent.
</doc:para>
<doc:para>
In contrast to connections established by SyncEvolution
itself, the peer has to send the first message and
SyncEvolution replies. If the first message is a normal
SyncML message, then SyncEvolution acts as SyncML server.
Alternatively, a Notification message can be sent to
request that SyncEvolution initiates a SyncML session as
client.
</doc:para>
<doc:para>
In the later case, SyncEvolution may or may not use the
connection established by Connect(), depending on the
content of that first message.
</doc:para>
<doc:para>
The result of Connect() is an object that implements the
org.syncevolution.Connection interface. It has to be used
for sending at least one message to start the sync. If
SyncEvolution needs to abort the connection, it will issue
the Close-signal and remove the object. A peer needs to
subscribe to that signal before starting to wait for a
reply. In addition, the client should also watch out for
SyncEvolution quitting unexpectedly.
</doc:para>
<doc:para>
SyncEvolution supports re-establishing a connection that was
interrupted. This only works when the peer is a SyncML
client, supports resending messages, and the non-D-Bus
message transport supports sending the session number as
part of the meta information.
</doc:para>
</doc:description>
</doc:doc>
<arg type="a{ss}" name="peer" direction="in">
<doc:doc>
<doc:summary>
Various information about the peer who initiated the
connection. All of it is optional unless explicitly
specified otherwise. Short, single line strings are
preferred.
"description" - a description of the peer in a format and
language that is understood by the user.
"id" - a unique ID for this particular peer, in a format
that is specific to the transport. The ID only has to be
unique among peers using that transport at the current
point in time.
"transport" - a string identifying the entity which talks
directly to SyncEvolution (peer or transport stub). If
available, this should be a D-Bus interface name, like
"org.openobex.obexd". The main purpose right now is for
informing the user and debugging. Later it might also be
used to call methods in that interface or for choosing a
local configuration for the peer based on its ID.
"transport_description" - could be used to describe the
version of the transport entity.
</doc:summary>
</doc:doc>
</arg>
<arg type="b" name="must_authenticate" direction="in">
<doc:doc>
<doc:summary>
<doc:para>
If false, then the peer is trusted and shall be given
access to SyncEvolution without further checks by
SyncEvolution itself. This is useful for peers which
already run as local user processes with same access
rights to the data as SyncEvolution or for transports that
authenticate and authorize access via their own
mechanisms.
</doc:para>
<doc:para>
If true, then a SyncML client peer must provide valid
credentials as part of the SyncML session. For a server,
a valid configuration must exist. SyncEvolution searches
for such a configuration by matching the sync URL in
the Notification with sync URLs in the configurations.
</doc:para>
</doc:summary>
</doc:doc>
</arg>
<arg type="s" name="session" direction="in">
<doc:doc>
<doc:summary>
If this is a reconnect for an older session,
then pass the session ID here. Otherwise
pass an empty string. New session IDs are created in
response to the initial message, see Reply signal.
</doc:summary>
</doc:doc>
</arg>
<arg type="o" name="connection" direction="out">
<doc:doc>
<doc:summary>
The connection object created by SyncEvolution in response
to this connection request. Implements the
org.syncevolution.Connection interface.
</doc:summary>
</doc:doc>
</arg>
</method>
<method name="GetSessions">
<doc:doc><doc:description>
Get currently existing sessions. This includes active and
queueing sessions.
</doc:description></doc:doc>
<arg type="ao" name="sessions" direction="out">
<doc:doc><doc:summary>array of session D-Bus object paths,
in the order in which they will run, running ones first</doc:summary></doc:doc>
</arg>
</method>
<signal name="SessionChanged">
<doc:doc><doc:description>Session start or end</doc:description></doc:doc>
<arg type="o" name="session">
<doc:doc><doc:summary>session D-Bus object path</doc:summary></doc:doc>
</arg>
<arg type="b" name="started">
<doc:doc><doc:summary>
TRUE if session was started and is active now (= ready for use),
FALSE if it ended
</doc:summary></doc:doc>
</arg>
</signal>
<signal name="TemplatesChanged">
<doc:doc>
<doc:description>
Template added or removed, for example because a Bluetooth
peer was paired resp. removed. To find out more, request
list of templates anew.
</doc:description>
</doc:doc>
</signal>
<signal name="Presence">
<doc:doc>
<doc:description>
Indicates whether a server can be reached right now. This
signal can be used by GUIs to prevent starting a sync when
it is known to fail, for example because the network is
currently down.
At the moment, the SyncEvolution server can only monitor
network connectivity, which is a cheap local operation and
thus done unconditionally while the server runs (see
Attach()). Detecting the presence of non-HTTP-based peers
might be more costly. Additional APIs might be added to turn
that on only when needed. The CheckPresence() method will
always force a check.
</doc:description>
</doc:doc>
<arg type="s" name="server">
<doc:doc><doc:summary>
name of the server configuration
</doc:summary></doc:doc>
</arg>
<arg type="s" name="status">
<doc:doc>
<doc:summary>
"no transport" - the transport necessary to reach the server is not working.
"not present" - the server is known to be down or unreachable.
"" - the server might be usable. Syncs can still fail.
Other non-empty strings might be added in the future. They always
indicate a condition which prevents syncing.
</doc:summary>
</doc:doc>
</arg>
<arg type="s" name="transport">
<doc:doc>
<doc:summary>
If the server can be reached via multiple transports, this
is the one which triggered the signal. Content of the
string to be decided...
</doc:summary>
</doc:doc>
</arg>
</signal>
<signal name="InfoRequest">
<doc:doc>
<doc:description>
<doc:para>
Emitted whenever the server needs information that only a
client can provide. Because the server does not know whether
clients are monitoring it (attaching to the server is
optional) and/or which of the attached clients are able to
handle the request, it broadcasts the request.
</doc:para>
<doc:para>
Clients react by calling InfoResponse. The flow is this:
information needed, InfoRequest("request"),
InfoResponse("working") + dialog is opened (if necessary),
InfoRequest("waiting"), information becomes available,
InfoResponse("response"), InfoRequest("done").
</doc:para>
<doc:para>
Clients should work on those requests that they support,
unless another client was faster (InfoRequest("waiting")).
Because there is a race condition, multiple dialogs might
be opened. The user only has to enter data in one of them.
A client can close his dialog upon InfoRequest("done")
and/or InfoRequest("waiting") with a 'handler' parameter
which is some other client. If the server does not get a
InfoResponse("working") soon enough (in the range of
minutes, not seconds), it has to assume that no client can
provide the information and fall back to some default or
abort.
</doc:para>
</doc:description>
</doc:doc>
<arg type="s" name="id">
<doc:doc><doc:summary>unique ID for the request</doc:summary></doc:doc>
</arg>
<arg type="o" name="session">
<doc:doc><doc:summary>the Session which is affected, may be empty</doc:summary></doc:doc>
</arg>
<arg type="s" name="state">
<doc:doc>
<doc:summary>
"request" for a new request,
"waiting" for one which is being serviced by some client,
"done" for a request which was resolved or timed out
</doc:summary>
</doc:doc>
</arg>
<arg type="s" name="handler">
<doc:doc>
<doc:summary>
for state="waiting": the client which first replied
with InfoResponse("working")
</doc:summary>
</doc:doc>
</arg>
<arg type="s" name="type">
<doc:doc>
<doc:summary>
Determines which information is needed. Currently only
"password" for interactive password requests is defined.
</doc:summary>
</doc:doc>
</arg>
<arg type="a{ss}" name="parameters">
<doc:doc>
<doc:summary>
Auxiliary parameters which depend on the type.
For "password" the following keys are used:
"name" - name of the password property in the config.
"description" - unique English description of the required password.
Content is determined by the individual password property, so this
may change. Currently used are "SyncML Server", "proxy",
"'source name' backend" (with 'source name' replaced by the same
names also used for the corresponding config entry).
"user", "server", "domain", "object", "protocol", "authtype", "port" -
optional keys as they would be used in the GNOME keyring.
</doc:summary>
</doc:doc>
</arg>
</signal>
<method name="InfoResponse">
<doc:doc><doc:description>reply for a specific InfoRequest</doc:description></doc:doc>
<arg type="s" name="id">
<doc:doc><doc:summary>unique ID sent by InfoRequest</doc:summary></doc:doc>
</arg>
<arg type="s" name="state">
<doc:doc>
<doc:summary>
"working" to indicate that a response will be sent later,
"response" for the actual reply
</doc:summary>
</doc:doc>
</arg>
<arg type="a{ss}" name="response">
<doc:doc>
<doc:summary>
Response values, valid in state="response", depend on type.
For "password" the following keys are used:
"password" - the password text, optional, do not set the key if the
user cancelled the request
</doc:summary>
</doc:doc>
</arg>
</method>
<signal name="LogOutput">
<doc:doc><doc:description></doc:description>Broadcast the console part of the output</doc:doc>
<arg type="o" name="path">
<doc:doc>
<doc:summary>
D-Bus object path. If the output belongs to a session, then path is set as session's
object path. Else, it's set as dbus server's object path.
</doc:summary>
</doc:doc>
</arg>
<arg type="s" name="level">
<doc:doc><doc:summary>the output level (DEBUG/INFO/SHOW/ERROR/WARNING/DEV)</doc:summary></doc:doc>
</arg>
<arg type="s" name="output">
<doc:doc><doc:summary>the output string to be broadcast</doc:summary></doc:doc>
</arg>
</signal>
</interface>
</node>
|