On Fri, 2009-07-31 at 12:44 +0100, Patrick Ohly wrote:
The bottom line line of the discussion is that the information
required
to re-establish an incoming connection is depending on the transport.
The same applies to connections originating from a server. My suggestion
is to keep this separate from the D-Bus API discussion and (as I said
earlier) not implement it immediately for OBEX.
Synthesis confirmed that they hadn't implemented this kind of reconnect
for OBEX either. Their experiments were done with switching between
different IP connections.
I'll write down a D-Bus API proposal now...
See below. As a proof-of-concept for this API I intend to write an
out-of-process HTTP transport stub. That'll allow us to verify our code
independently from the obexd plugin.
Forrest, does the API look okay? Do you need anything beyond the XML
file to call it? Now the difficult part: can we get a commitment from
the obexd team to get the obexd plugin implemented based on this API?
Any estimate how long that might take? This doesn't have to be set in
stone, but good enough to let us proceed with our own planning.
Bye, Patrick
<?xml version="1.0"?>
<node name="/"
xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd">
<doc:doc>
<doc:summary>SyncEvolution D-Bus Interface</doc:summary>
</doc:doc>
<interface name="org.Moblin.SyncEvolution">
[should be renamed to org.syncevolution]
<doc:doc>
<doc:para>
The SyncEvolution object can be used to get and set configurations,
to start synchronizations and to observe synchronization progress.
</doc:para>
</doc:doc>
[...]
<method name="Connect">
<doc:doc>
<doc:summary>
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.
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.
In the later case, SyncEvolution may or may not use the
connection established by Connect(), depending on the
content of that first message.
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 delete
that object. A peer needs to subscribe to the delete signal
to detect this situation. This also covers the situation
that SyncEvolution quits unexpectedly.
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:summary>
</doc:doc>
<arg type="s" name="peer_description"
direction="in">
<doc:doc>
<doc:summary>
A description of the peer in a format and language that is
understood by the user.
</doc:summary>
</doc:doc>
</arg>
<arg type="s" name="peer_id" direction="in">
<doc:doc>
<doc:summary>
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.
</doc:summary>
</doc:doc>
</arg>
<arg type="s" name="transport" direction="in">
<doc:doc>
<doc:summary>
A string identifying the entity which talks directly
to SyncEvolution (peer or transport stub). If available,
this should be a D-Bus interface name. 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.
</doc:summary>
</doc:doc>
</arg>
<arg type="b" name="must_authenticate"
direction="in">
<doc:doc>
<doc:summary>
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.
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:summary>
</doc:doc>
</arg>
<arg type="u" name="session" direction="in">
<doc:doc>
<doc:summary>
If this is a reconnect for an older session,
then pass the session number here. Otherwise
pass 0. New session numbers are created in
response to the initial message.
</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>
</interface>
<interface name="org.syncevolution.connection">
<doc:doc>
<doc:para>
The SyncEvolution connection object can be used to exchange
messages.
</doc:para>
</doc:doc>
<method name="Process">
<doc:doc>
<doc:summary>
Pass data to SyncEvolution and get the response.
</doc:summary>
</doc:doc>
<arg type="ay" name="message" direction="in">
<doc:doc>
<doc:summary>
The data to be processed. Empty messages are invalid
and will trigger an error.
</doc:summary>
</doc:doc>
</arg>
<arg type="s" name="message_type"
direction="in">
<doc:doc>
<doc:summary>
The MIME type of the
message. "application/vnd.syncml.ds.notification",
"application/vnd.syncml+xml" and
"application/vnd.syncml+wbxml" are currently supported.
</doc:summary>
</doc:doc>
</arg>
<arg type="ay" name="reply" direction="out">
<doc:doc>
<doc:summary>
The data to be returned to the peer. An empty reply is
possible as response to the last message; it must not be
delivered. Instead, final will be true and the connection
needs to be closed.
</doc:summary>
</doc:doc>
</arg>
<arg type="s" name="response_type"
direction="out">
<doc:doc>
<doc:summary>
The MIME type of the response. The same types as for the
message are supported.
</doc:summary>
</doc:doc>
</arg>
<arg type="s" name="response_url"
direction="out">
<doc:doc>
<doc:summary>
The content of the string depends on the transport, which
must be recognized by SyncEvolution if special information
is required. By default and if applicable, the URL for an
HTTP POST is passed here.
</doc:summary>
</doc:doc>
</arg>
<arg type="b" name="final" direction="out">
<doc:doc>
<doc:summary>
True if this is the last reply. No further messages are
expected and the session should be closed once the reply
was delivered successfully.
</doc:summary>
</doc:doc>
</arg>
<arg type="u" name="session" direction="out">
<doc:doc>
<doc:summary>
The first message in a new connection triggers the
creation of a new, random session number which is returned
together with the response. The caller is responsible for
ensuring that only messages belonging to this session are
passed to future process() calls.
In practice the session number does not change after the
first message, but this is not guaranteed and the caller
should always use the most recent value.
</doc:summary>
</doc:doc>
</arg>
</method>
<method name="Close">
<doc:doc>
<doc:summary>
Indicates that the connection object is no longer needed.
</doc:summary>
</doc:doc>
<arg type="b" name="normal" direction="in">
<doc:doc>
<doc:summary>
TRUE if the connection is being closed after successfully
delivering the final response. FALSE if an error is
encountered that cannot be handled by the peer or its
transport. SyncEvolution cannot rely on getting a close(FALSE)
call in all cases. If its caller disappears from the bus
it must assume that there was a fatal error and close the
connection.
</doc:summary>
</doc:doc>
</arg>
<arg type="s" name="error" direction="in">
<doc:doc>
<doc:summary>
A description which explains the error, may be empty.
Used for debugging.
</doc:summary>
</doc:doc>
</arg>
</method>
</interface>