1:40 p.m.
Hello Forrest!
I've just had a chat with Marcel about OBEX/SyncML integration. I'd like
to continue the discussion by email. Note that the public SyncEvolution
list is on CC, please group reply, I'll approve posts.
What we (= SyncEvolution) have to implement is the SyncML OBEX binding:
http://www.openmobilealliance.org/Technical/release_program/docs/copyrigh...
As explained in the design document for the future SyncML server, we
want to establish a central D-Bus service as the single component in the
system which runs SyncML sessions:
http://moblin.org/documentation/syncevolution/direct-synchronization-aka-...
This service has to interact with peers over OBEX in two ways:
1. actively contact them (SyncML server = OBEX client)
2. wait for connection requests (SyncML client = OBEX server)
These are the common use cases. The spec allows a SyncML client (phone)
to contact the server (desktop), but typically the UI of a phone only
allows triggering a sync via HTTP, not via OBEX. Instead, the software
on the desktop is expected to contact the phone.
The first point could be implemented via libopenobex. libsyncml could be
used as example for this. We might even copy the code, the license is
compatible. However, we don't have SyncML server support yet. Whether
that is really simpler than using obexd remains to be seen, which is why
I'd like to look at the second point first.
The second point is best solved via an obexd plugin. This is were help
would be very welcome. Forrest, do you think you could point us in the
right direction? My hope that this is trivial for someone who knows the
obexd source code. We could use help:
1. addding a new SyncML plugin to obexd
2. adding the SyncML service description (OBEX binding document,
5.2.1)
3. writing stubs for Connect/Disconnect/Put/Get/Abort operations:
* CONNECT: use a dummy connection ID
* PUT: discard incoming data
* GET: send dummy data
4. how the data could be exchanged with a D-Bus service as part of
the obexd event loop
These stubs then need to be extended so that they actually talk to the
sync D-Bus service via its (still to be defined) API.
The OBEXD binding allows splitting of one SyncML message into smaller
PUT/GET chunks. I'm undecided whether the D-Bus API should also support
this, because the maximum size of a SyncML message could already be
chosen so that we don't overload the system.
Speaking of D-Bus communication: Marcel pointed out that this additional
traffic and the amount of data can be problematic and mentioned that
D-Bus 0.4 will support fd exchange to hook up two peers directly. We
should keep that in mind, but start with data exchange via plain D-Bus
before tuning it.
We are not the only ones who transmit the data over D-Bus anyway, EDS
also does it. So our use of D-Bus is not a qualitative difference
(completely different way of using it), only a quantitative one (twice
the traffic).
To complete the OBEX support and server-initiated syncs, we (= the
SyncEvolution team and/or Synthesis) also needs to add encoding and
decoding of the SyncML Notification message (OMA DS 1.2.2, chapter 12).
This is non-trivial because the URIs of the device must be known in
advance. To get started we should make this configurable and later
decide how to simplify that for users (global device database?).
--
Best Regards, Patrick Ohly
The content of this message is my personal opinion only and although
I am an employee of Intel, the statements I make here in no way
represent Intel's position on the issue, nor am I authorized to speak
on behalf of Intel on this matter.
9:44 a.m.
What we (= SyncEvolution) have to implement is the SyncML OBEX
binding:
http://www.openmobilealliance.org/Technical/release_program/docs/copyrigh...
Thank you for sharing the document. For SyncML client/OBEX server binding we need
to support "Connect", "Disconnect", "Put", "Get"
and "Abort" operation in obexd.
As explained in the design document for the future SyncML server, we
want to establish a central D-Bus service as the single component in
the system which runs SyncML sessions:
http://moblin.org/documentation/syncevolution/direct-synchronization-aka-...
This service has to interact with peers over OBEX in two ways:
1. actively contact them (SyncML server = OBEX client)
2. wait for connection requests (SyncML client = OBEX server)
These are the common use cases. The spec allows a SyncML client
(phone) to contact the server (desktop), but typically the UI of a
phone only allows triggering a sync via HTTP, not via OBEX. Instead,
the software on the desktop is expected to contact the phone.
The first point could be implemented via libopenobex. libsyncml could
be used as example for this. We might even copy the code, the license
is compatible. However, we don't have SyncML server support yet.
Whether that is really simpler than using obexd remains to be seen,
which is why I'd like to look at the second point first.
OK. Let's have more detailed discussion about SyncML server/OBEX client
binding when SyncML server support is ready.
The second point is best solved via an obexd plugin. This is were
help
would be very welcome. Forrest, do you think you could point us in the
right direction? My hope that this is trivial for someone who knows
the obexd source code. We could use help:
1. addding a new SyncML plugin to obexd
2. adding the SyncML service description (OBEX binding document,
5.2.1)
3. writing stubs for Connect/Disconnect/Put/Get/Abort operations:
* CONNECT: use a dummy connection ID
* PUT: discard incoming data
* GET: send dummy data
4. how the data could be exchanged with a D-Bus service as part
of the obexd event loop
These stubs then need to be extended so that they actually talk to the
sync D-Bus service via its (still to be defined) API.
Your described code logic is
almost right to support SyncML client/OBEX server. But I think we could start this work
after sync D-Bus API is stable.
The OBEXD binding allows splitting of one SyncML message into smaller
PUT/GET chunks. I'm undecided whether the D-Bus API should also
support this, because the maximum size of a SyncML message could
already be chosen so that we don't overload the system.
Speaking of D-Bus communication: Marcel pointed out that this
additional traffic and the amount of data can be problematic and
mentioned that D-Bus 0.4 will support fd exchange to hook up two
peers directly. We should keep that in mind, but start with data
exchange via plain D-Bus before tuning it.
Good to know that D-Bus 0.4 will support
fd exchange.
Thanks,
Forrest
3:40 p.m.
On Mon, 2009-07-27 at 08:44 +0100, Zhao, Forrest wrote:
> The second point is best solved via an obexd plugin. This is
were help
> would be very welcome. Forrest, do you think you could point us in the
> right direction? My hope that this is trivial for someone who knows
> the obexd source code. We could use help:
> 1. addding a new SyncML plugin to obexd
> 2. adding the SyncML service description (OBEX binding document,
> 5.2.1)
> 3. writing stubs for Connect/Disconnect/Put/Get/Abort operations:
> * CONNECT: use a dummy connection ID
> * PUT: discard incoming data
> * GET: send dummy data
> 4. how the data could be exchanged with a D-Bus service as part
> of the obexd event loop
>
> These stubs then need to be extended so that they actually talk to the
> sync D-Bus service via its (still to be defined) API.
Your described code logic is almost right to support SyncML
client/OBEX server. But I think we could start this work after sync
D-Bus API is stable.
The requirements of the obexd plugin drive the design D-Bus API, so we
need to work on this in parallel. Here's my take on obexd + synx D-Bus
server interaction for a server initiated sync via OBEX, with
SyncEvolution acting as SyncML client:
1. obexd: publish SyncML as Bluetooth service
2. third-party SyncML server (could use libsyncml command line tool
for testing): pair with Bluetooth stack, create connection to
obexd
3. obexd: instantiate org.syncevolution.sync service,
*asynchronously* call connect(config="", session=0,
transporthandle=org.syncevolution.transport instance)
4. syncevo-dbus-server: look up default configuration (config="")
and accept the connection, returning a org.syncevolution.session
instance and the corresponding session number
5. obexd: accept the OBEX connection, setting the session number as
connection ID
6. SyncML server: PUT SyncML Notification message
7. obexd: gather complete data of all PUTs, call
transporthandle.process(data=byte array, mime type=string)
8. syncevo-dbus-server:
* check type to distinguish between server initiated sync
("application/vnd.syncml.ds.notification", supported)
and SyncML client ("application/vnd.syncml+(wb)xml", not
supported yet)
* instantiate EvolutionSyncClient based on parameters in
the notification message, with transporthandle as
transport agent
* run the sync, let it produce the first SyncML message
* return that message as result of
transporthandle.process(), then go idle
9. obexd: reply (?) to GET with that data
10. obexd+syncevo-dbus-server: process more PUT/GET exchanges in the
same way until transporthandle.process() returns an empty
message, indicating the end of the session, but with
transporthandle still valid
11. obexd: close connection, call
transporthandle.close(success=true/false) indicating whether the
connection was shut down properly
12. syncevo-dbus-server: treat the last message as sent, close down
sync session, free transporthandle
The session number was chosen as integer value because not all transport
stubs might support a string, whereas an integer can always be turned
into a string. What is the type of an OBEX Connection ID?
All calls must be made asynchronously. There is no guaranteed response
time for any of them.
I'm not sure how the OBEX server initiates or replies to the GET that
the binding document describes. I hope the experts know better how to
implement that ;-)
Error handling: if syncevo-dbus-server dies unexpectedly, all
communication with transporthandle fails. There's no way to recover from
this. The OBEX client must be told that there was a unrecoverable error.
I'm less sure about the situation when the connection or obexd go down.
In HTTP, clients can resend their PUT with the old URL (which often
includes a session ID). If the server is smart, it will keep that
session alive long enough to continue despite intermittent loss of IP
connectivity and the resulting transport error. Is the same possible
with OBEX, in other words, can an OBEX client reconnect with the same
connection ID?
It doesn't seem like this is possible. Just in case (and for HTTP), the
connect() call above takes a session identifier. If non-null, it can
check whether that session is still alive and reconnect to it.
If OBEX really doesn't support resuming an interrupted connection, then
syncevo-dbus-server would have to check whether the first message in a
new connection is something which matches an active session. That
changes steps 3-7, because the connect cannot be processed without the
message data. A unique ID for the peer would be useful, but only if it
remains constant after a loss of connection. In HTTP that's not the
case, because the same client might have a different IP after
reconnecting.
I hope the description above makes sense. If not, then let's clarify the
questions that I raised and I'll follow up with a detailed D-Bus API
description.
--
Best Regards, Patrick Ohly
The content of this message is my personal opinion only and although
I am an employee of Intel, the statements I make here in no way
represent Intel's position on the issue, nor am I authorized to speak
on behalf of Intel on this matter.
6:11 a.m.
>> These stubs then need to be extended so that they actually
talk to
>> the sync D-Bus service via its (still to be defined) API.
> Your described code logic is almost right to support SyncML
> client/OBEX server. But I think we could start this work after sync
> D-Bus API is stable.
The requirements of the obexd plugin drive the design D-Bus API, so we
need to work on this in parallel. Here's my take on obexd + synx D-Bus
server interaction for a server initiated sync via OBEX, with
SyncEvolution acting as SyncML client:
1. obexd: publish SyncML as Bluetooth service
2. third-party SyncML server (could use libsyncml command line
tool for testing): pair with Bluetooth stack, create
connection to obexd
3. obexd: instantiate org.syncevolution.sync service,
*asynchronously* call connect(config="", session=0,
transporthandle=org.syncevolution.transport instance)
4. syncevo-dbus-server: look up default configuration (config="")
and accept the connection, returning a
org.syncevolution.session instance and the corresponding
session number
5. obexd: accept the OBEX connection, setting the session number
as connection ID
session number is not necessary the same as OBEX connection ID. We
need an internal data structure to map between them.
6. SyncML server: PUT SyncML Notification message
7. obexd: gather complete data of all PUTs, call
transporthandle.process(data=byte array, mime type=string)
8. syncevo-dbus-server:
* check type to distinguish between server initiated
sync ("application/vnd.syncml.ds.notification",
supported) and SyncML client
("application/vnd.syncml+(wb)xml", not supported yet)
* instantiate EvolutionSyncClient based on parameters in
the notification message, with transporthandle as
transport agent
* run the sync, let it produce the first SyncML message
* return that message as result of
transporthandle.process(), then go idle
9. obexd: reply (?) to GET with that data
10. obexd+syncevo-dbus-server: process more PUT/GET exchanges in
the same way until transporthandle.process() returns an empty
message, indicating the end of the session, but with
transporthandle still valid
11. obexd: close connection, call
transporthandle.close(success=true/false) indicating whether
the connection was shut down properly
Another case is SyncML client initiated disconnection. Is there a way for
syncevo-dbus-server to notify obexd of disconnect the current coonection
with remote OBEX client?
12. syncevo-dbus-server: treat the last message as sent, close
down sync session, free transporthandle
The session number was chosen as integer value because not all
transport stubs might support a string, whereas an integer can always
be turned into a string. What is the type of an OBEX Connection ID?
OBEX Connection ID is type of uint32, however we'll not use session number
as OBEX Connection ID in obexd because obexd has its own OBEX
Connection ID naming rule. We just need an internal data structure to
map between session number and OBEX Connection ID.
All calls must be made asynchronously. There is no guaranteed response
time for any of them.
Sure. The PBAP server that I implemented in obexd has the similar logic as
SyncML client/OBEX server. It's implemented in async way.
I'm not sure how the OBEX server initiates or replies to the GET
that
the binding document describes. I hope the experts know better how to
implement that ;-)
Error handling: if syncevo-dbus-server dies unexpectedly, all
communication with transporthandle fails. There's no way to recover
from this. The OBEX client must be told that there was a
unrecoverable error.
I'm less sure about the situation when the connection or obexd go
down. In HTTP, clients can resend their PUT with the old URL (which
often includes a session ID). If the server is smart, it will keep
that session alive long enough to continue despite intermittent loss
of IP connectivity and the resulting transport error. Is the same
possible with OBEX, in other words, can an OBEX client reconnect with
the same connection ID?
It doesn't seem like this is possible. Just in case (and for HTTP),
the connect() call above takes a session identifier. If non-null, it
can check whether that session is still alive and reconnect to it.
OBEX does not have such mechanism like HTTP. So we might need to
do the resend in SyncML server level.
If OBEX really doesn't support resuming an interrupted
connection,
then syncevo-dbus-server would have to check whether the first
message in a new connection is something which matches an active
session. That changes steps 3-7, because the connect cannot be
processed without the message data. A unique ID for the peer would be
useful, but only if it remains constant after a loss of connection.
In HTTP that's not the case, because the same client might have a
different IP after reconnecting.
This is not the case for OBEX, either. After the
connection is dropped, the
OBEX server may reassign the connection ID to another OBEX session.
Thanks,
Forrest
11:15 a.m.
On Tue, 2009-07-28 at 05:11 +0100, Zhao, Forrest wrote:
>>> These stubs then need to be extended so that they
actually talk to
>>> the sync D-Bus service via its (still to be defined) API.
>> Your described code logic is almost right to support SyncML
>> client/OBEX server. But I think we could start this work after sync
>> D-Bus API is stable.
>
> The requirements of the obexd plugin drive the design D-Bus API, so we
> need to work on this in parallel. Here's my take on obexd + synx D-Bus
> server interaction for a server initiated sync via OBEX, with
> SyncEvolution acting as SyncML client:
>
> 1. obexd: publish SyncML as Bluetooth service
> 2. third-party SyncML server (could use libsyncml command line
> tool for testing): pair with Bluetooth stack, create
> connection to obexd
> 3. obexd: instantiate org.syncevolution.sync service,
> *asynchronously* call connect(config="", session=0,
> transporthandle=org.syncevolution.transport instance)
> 4. syncevo-dbus-server: look up default configuration (config="")
> and accept the connection, returning a
> org.syncevolution.session instance and the corresponding
> session number
> 5. obexd: accept the OBEX connection, setting the session number
> as connection ID
session number is not necessary the same as OBEX connection ID. We
need an internal data structure to map between them.
Okay. Using the session number as connection ID was meant to simplify
the implementation, it's not a requirement.
> 6. SyncML server: PUT SyncML Notification message
> 7. obexd: gather complete data of all PUTs, call
> transporthandle.process(data=byte array, mime type=string)
> 8. syncevo-dbus-server:
> * check type to distinguish between server initiated
> sync ("application/vnd.syncml.ds.notification",
> supported) and SyncML client
> ("application/vnd.syncml+(wb)xml", not supported yet)
> * instantiate EvolutionSyncClient based on parameters in
> the notification message, with transporthandle as
> transport agent
> * run the sync, let it produce the first SyncML message
> * return that message as result of
> transporthandle.process(), then go idle
> 9. obexd: reply (?) to GET with that data
> 10. obexd+syncevo-dbus-server: process more PUT/GET exchanges in
> the same way until transporthandle.process() returns an empty
> message, indicating the end of the session, but with
> transporthandle still valid
> 11. obexd: close connection, call
> transporthandle.close(success=true/false) indicating whether
> the connection was shut down properly
Another case is SyncML client initiated disconnection. Is there a way for
syncevo-dbus-server to notify obexd of disconnect the current coonection
with remote OBEX client?
obexd could listen for transporthandle going away. I think D-Bus has the
mechanisms for that. This covers both the case that syncevo-dbus-server
dies as well as an unforseen termination of the sync session.
I think that is good enough, because if we get to that point where a
disconnect is necessary, there isn't much that can. obexd should simply
clean up and ignore all ensuing errors for that connection, without
reporting back to syncevo-dbus-server.
[re-establish connection via OBEX]
> It doesn't seem like this is possible. Just in case (and for
HTTP),
> the connect() call above takes a session identifier. If non-null, it
> can check whether that session is still alive and reconnect to it.
OBEX does not have such mechanism like HTTP. So we might need to
do the resend in SyncML server level.
I see. After thinking about it some more, I'm coming to the conclusion
that for server-initiated syncs the "message resend by SyncML client" is
not going to work: the client might detect that his message to the
server (GET) didn't get through, but the server would have to establish
the connection and resend his PUT. "message resent by SyncML server" may
or may not work with non-SyncEvolution clients - need to check with
Synthesis.
If we could reverse the roles and continue the sync session with a
SyncML client initiated OBEX connection, then perhaps it would work.
This assumes that the SyncML server accepts connections via OBEX. I
suggest that we defer the discussion of this particular aspect until I
had a chance to discuss if with Synthesis and we are ready to discuss
the SyncEvolution initiated OBEX connections (SyncML server).
> If OBEX really doesn't support resuming an interrupted
connection,
> then syncevo-dbus-server would have to check whether the first
> message in a new connection is something which matches an active
> session. That changes steps 3-7, because the connect cannot be
> processed without the message data. A unique ID for the peer would be
> useful, but only if it remains constant after a loss of connection.
> In HTTP that's not the case, because the same client might have a
> different IP after reconnecting.
This is not the case for OBEX, either. After the connection is dropped, the
OBEX server may reassign the connection ID to another OBEX session.
But the peer itself has a unique ID that could be used to address it in
a new connection request, right? Is it the same for USB and Bluetooth?
--
Best Regards, Patrick Ohly
The content of this message is my personal opinion only and although
I am an employee of Intel, the statements I make here in no way
represent Intel's position on the issue, nor am I authorized to speak
on behalf of Intel on this matter.
11:31 a.m.
>> If OBEX really doesn't support resuming an interrupted connection,
>> then syncevo-dbus-server would have to check whether the first
>> message in a new connection is something which matches an active
>> session. That changes steps 3-7, because the connect cannot be
>> processed without the message data. A unique ID for the peer would
>> be useful, but only if it remains constant after a loss of
>> connection. In HTTP that's not the case, because the same client
>> might have a different IP after reconnecting.
> This is not the case for OBEX, either. After the connection is
> dropped, the OBEX server may reassign the connection ID to another
> OBEX session.
But the peer itself has a unique ID that could be used to address it
in a new connection request, right? Is it the same for USB and
Bluetooth?
hmm, please read the definition of cmd_connect() at
http://git.kernel.org/?p=bluetooth/obexd.git;a=blob;f=src/obex.c;h=53ec9b...
You may find that connection ID(i.e. cid) is defined as a global variable and
assigned by OBEX server. Please let me if this answers your question.
Thanks,
Forrest
12:46 p.m.
On Tue, 2009-07-28 at 10:31 +0100, Zhao, Forrest wrote:
>
>>> If OBEX really doesn't support resuming an interrupted connection,
>>> then syncevo-dbus-server would have to check whether the first
>>> message in a new connection is something which matches an active
>>> session. That changes steps 3-7, because the connect cannot be
>>> processed without the message data. A unique ID for the peer would
>>> be useful, but only if it remains constant after a loss of
>>> connection. In HTTP that's not the case, because the same client
>>> might have a different IP after reconnecting.
>> This is not the case for OBEX, either. After the connection is
>> dropped, the OBEX server may reassign the connection ID to another
>> OBEX session.
>
> But the peer itself has a unique ID that could be used to address it
> in a new connection request, right? Is it the same for USB and
> Bluetooth?
hmm, please read the definition of cmd_connect() at
http://git.kernel.org/?p=bluetooth/obexd.git;a=blob;f=src/obex.c;h=53ec9b...
You may find that connection ID(i.e. cid) is defined as a global variable and
assigned by OBEX server. Please let me if this answers your question.
No, not quite. I'm looking for whatever corresponds to the IP address in
a TCP connect(), or at a lower level the MAC. In case that it makes a
difference, this is from a user space perspective, not inside the
kernel.
So for initiating an OBEX connection, how do I find the available
devices and choose one of them?
If I was contacted via obexd and Bluetooth, can I find that device again
when it reconnects via USB, without establishing a connection and
exchanging some data?
--
Best Regards
Patrick Ohly
Senior Software Engineer
Intel GmbH
Open Source Technology Center
Hermuelheimer Strasse 8a Phone: +49-2232-2090-30
50321 Bruehl Fax: +49-2232-2090-29
Germany
3:08 a.m.
Ohly, Patrick wrote:
On Tue, 2009-07-28 at 10:31 +0100, Zhao, Forrest wrote:
>>
>>>> If OBEX really doesn't support resuming an interrupted connection,
>>>> then syncevo-dbus-server would have to check whether the first
>>>> message in a new connection is something which matches an active
>>>> session. That changes steps 3-7, because the connect cannot be
>>>> processed without the message data. A unique ID for the peer would
>>>> be useful, but only if it remains constant after a loss of
>>>> connection. In HTTP that's not the case, because the same client
>>>> might have a different IP after reconnecting.
>>> This is not the case for OBEX, either. After the connection is
>>> dropped, the OBEX server may reassign the connection ID to another
>>> OBEX session.
>>
>> But the peer itself has a unique ID that could be used to address it
>> in a new connection request, right? Is it the same for USB and
>> Bluetooth?
>
> hmm, please read the definition of cmd_connect() at
>
http://git.kernel.org/?p=bluetooth/obexd.git;a=blob;f=src/obex.c;h=53ec9b...
>
> You may find that connection ID(i.e. cid) is defined as a global
> variable and assigned by OBEX server. Please let me if this answers
> your question.
No, not quite. I'm looking for whatever corresponds to the IP address
in a TCP connect(), or at a lower level the MAC. In case that it
makes a difference, this is from a user space perspective, not inside
the kernel.
This is done by rfcomm_connect() in obexd. The declaration is
static int rfcomm_connect(const bdaddr_t *src, const bdaddr_t *dst, uint8_t channel,
GIOFunc function, gpointer user_data);
src is source BT MAC address; dst is destination BT MAC address, channel is the service
channel (e.g. PBAP server channel is 15).
So for initiating an OBEX connection, how do I find the available
devices and choose one of them?
To find the available BT devices, please use command 'hcitool scan'; to find the
services supported by a BT device, please use command 'sdptool browse
BT-MAC-address'.
If I was contacted via obexd and Bluetooth, can I find that device
again when it reconnects via USB, without establishing a connection
and exchanging some data?
Sorry, I have not experienced such case.
Marcel,
Could you help to answer this question?
Thanks,
Forrest
1:44 p.m.
On Wed, 2009-07-29 at 02:08 +0100, Zhao, Forrest wrote:
Ohly, Patrick wrote:
> On Tue, 2009-07-28 at 10:31 +0100, Zhao, Forrest wrote:
> No, not quite. I'm looking for whatever corresponds to the IP address
> in a TCP connect(), or at a lower level the MAC. In case that it
> makes a difference, this is from a user space perspective, not inside
> the kernel.
This is done by rfcomm_connect() in obexd. The declaration is
static int rfcomm_connect(const bdaddr_t *src, const bdaddr_t *dst, uint8_t channel,
GIOFunc function, gpointer user_data);
src is source BT MAC address; dst is destination BT MAC address, channel is the service
channel (e.g. PBAP server channel is 15).
>
> So for initiating an OBEX connection, how do I find the available
> devices and choose one of them?
To find the available BT devices, please use command 'hcitool scan';
to find the services supported by a BT device, please use command
'sdptool browse BT-MAC-address'.
>
> If I was contacted via obexd and Bluetooth, can I find that device
> again when it reconnects via USB, without establishing a connection
> and exchanging some data?
Sorry, I have not experienced such case.
Marcel,
Could you help to answer this question?
What you described above looks very much Bluetooth specific. I fear that
the other transports will likely also have their own addressing scheme,
like USB bus number or device node.
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.
I'll write down a D-Bus API proposal now...
--
Best Regards, Patrick Ohly
The content of this message is my personal opinion only and although
I am an employee of Intel, the statements I make here in no way
represent Intel's position on the issue, nor am I authorized to speak
on behalf of Intel on this matter.
12:15 p.m.
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>
6:13 a.m.
> 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.
Let's first come out a clear design and API, then we could give a good
workload estimation for both sides.
<?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.
From obexd plugin's point of view I think that method
"Connect" should
establish a connection between OBEX server and
SyncEvlolution instead
of establishing a connection between SyncEvolution and a peer. In the
other words the transport layer (e.g. OBEX, HTTP) does not need to
parse the SyncML packets and initiate the SyncML-level connection.
Otherwise we duplicate the code in OBEX and HTTP server stub. My
understanding is that the transport layer (e.g. OBEX, HTTP) is
resposible for transmitting the packets requested by upper level (e.g.
syncML) and does not need to parse the SyncML packets. This would
impact the SyncEvolution API design significantly. So let's first achieve
agreement on the basic point.
Thanks,
Forrest
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>
8:43 a.m.
On Wed, 2009-08-05 at 05:13 +0100, Zhao, Forrest wrote:
>> 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.
Let's first come out a clear design and API, then we could give a good
workload estimation for both sides.
Okay, so what's missing? ;-)
> <?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.
From obexd plugin's point of view I think that method "Connect" should
establish a connection between OBEX server and SyncEvlolution
That's covered by the API: obexd is the "server stub" mentioned above,
in which case the connection is between obexd and SyncEvolution. Let me
rephrase the description, perhaps then it is more clear:
Establishes a connection between SyncEvolution and a transport
agent. That transport agent might be part of a SyncML client or
server which is connected directly to D-Bus (local sync) or it
might be connected to the SyncML peer via some other transport
mechanism (remote sync via OBEX, HTTP, ...). The task of the
transport agent is to pass messages back and forth, with no need
to parse the content of them.
This replaces the complete paragraph quoted above.
instead
of establishing a connection between SyncEvolution and a peer. In the
other words the transport layer (e.g. OBEX, HTTP) does not need to
parse the SyncML packets and initiate the SyncML-level connection.
Otherwise we duplicate the code in OBEX and HTTP server stub.
Exactly.
My
understanding is that the transport layer (e.g. OBEX, HTTP) is
resposible for transmitting the packets requested by upper level (e.g.
syncML) and does not need to parse the SyncML packets. This would
impact the SyncEvolution API design significantly. So let's first achieve
agreement on the basic point.
I think we are in agreement :-)
--
Best Regards
Patrick Ohly
Senior Software Engineer
Intel GmbH
Open Source Technology Center
Hermuelheimer Strasse 8a Phone: +49-2232-2090-30
50321 Bruehl Fax: +49-2232-2090-29
Germany
8:47 a.m.
>
> From obexd plugin's point of view I think that method "Connect"
> should establish a connection between OBEX server and SyncEvlolution
That's covered by the API: obexd is the "server stub" mentioned above,
in which case the connection is between obexd and SyncEvolution. Let
me rephrase the description, perhaps then it is more clear:
Establishes a connection between SyncEvolution and a transport
agent. That transport agent might be part of a SyncML client
or server which is connected directly to D-Bus (local sync)
or it might be connected to the SyncML peer via some other
transport mechanism (remote sync via OBEX, HTTP, ...). The
task of the transport agent is to pass messages back and
forth, with no need to parse the content of them.
This replaces the complete paragraph quoted above.
> instead
> of establishing a connection between SyncEvolution and a peer. In the
> other words the transport layer (e.g. OBEX, HTTP) does not need to
> parse the SyncML packets and initiate the SyncML-level connection.
> Otherwise we duplicate the code in OBEX and HTTP server stub.
Exactly.
> My
> understanding is that the transport layer (e.g. OBEX, HTTP) is
> resposible for transmitting the packets requested by upper level
> (e.g. syncML) and does not need to parse the SyncML packets. This
> would
> impact the SyncEvolution API design significantly. So let's first
> achieve agreement on the basic point.
I think we are in agreement :-)
OK. Thanks for clarification. I'll continue the discussion with previous email.
10:20 a.m.
<?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>
Take OBEX server/SyncML client binding for example, what name is
appropriate for "peer_description"?
<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>
Is it appropriate to set "transport" to "OBEX" in obexd plugin?
<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>
How should obexd plugin know if the SyncML-level authentication is needed?
<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>
For OBEX session is always 0 since OBEX has no mechanism to support reconnection.
<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>
If the message is too long, OBEX would split the message into muliple
packets and send them seperately. It would be nice for SyncEvolution
to provide a API to transmit multiple packets belonging to one message.
<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>
I'm afraid this way of returning data does not work. Please read section 6.2
of
http://www.openmobilealliance.org/Technical/release_program/docs/copyrigh....
OBEX client first send SyncML request to OBEX server by PUT command; then OBEX server
can't return data to OBEX client actively. OBEX client has to send GET command to pull
results.
<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>
10:50 a.m.
On Wed, 2009-08-05 at 09:20 +0100, Zhao, Forrest wrote:
> <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>
Take OBEX server/SyncML client binding for example, what name is
appropriate for "peer_description"?
Do you have access to device information in obexd? Using the device name
would be suitable, or the brand + model.
> <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>
Is it appropriate to set "transport" to "OBEX" in obexd plugin?
I think org.openobex would be better (there might be different OBEX
transports).
> <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>
How should obexd plugin know if the SyncML-level authentication is needed?
The peer must have paired before it is allowed to ask for an OBEX
connection. As a first approximation I'd say that this is enough to
ensure that the peer is authenticated already, so use
must_authenticate=false in all cases.
This is rather crude because it does not take into account why the user
has allowed pairing, but as far as I know, this "all or nothing"
approach is what is commonly used with Bluetooth, isn't it?
As a different example, it should be true for a HTTP server, unless the
server requires HTTP AUTH.
> <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>
For OBEX session is always 0 since OBEX has no mechanism to support reconnection.
Correct.
> <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>
>
If the message is too long, OBEX would split the message into muliple
packets and send them seperately. It would be nice for SyncEvolution
to provide a API to transmit multiple packets belonging to one message.
I was arguing with myself about that. I agree that it would be nice, but
is it really worth making the API more complex? How long is "too long"
in the context of OBEX?
I think that with a small enough maximum message size (64KB? more?
less?) we can safely buffer a complete message inside obexd before
sending it over D-Bus and then wouldn't have to change the API.
> <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>
>
I'm afraid this way of returning data does not work. Please read section 6.2
of
http://www.openmobilealliance.org/Technical/release_program/docs/copyrigh....
OBEX client first send SyncML request to OBEX server by PUT command; then OBEX server
can't return data to OBEX client actively. OBEX client has to send GET command to pull
results.
I had a question mark behind GET in one of my earlier emails because I
wasn't sure how the GET works.
The D-Bus API would still work as-is:
- OBEX client sends PUT, triggering an asynchronous process() call
- OBEX client sends GET, gets blocked because no data is available yet
- process() returns the response
- response is delivered to client via the pending GET
If the OBEX client does not send a GET at all, then it is buggy. This
needs to be detected by a timeout inside SyncEvolution, just like any
other "unresponsive peer" situation. obexd can keep the response around
until either it is delivered or the connection is aborted.
OBEX is somewhat special in that it doesn't allow the transport to push
the response. Exposing this in the API would make it unnecessarily
complex for other cases where the response can be pushed, so if
possible, I'd like to hide this PUT/GET semantic inside obexd.
--
Best Regards, Patrick Ohly
The content of this message is my personal opinion only and although
I am an employee of Intel, the statements I make here in no way
represent Intel's position on the issue, nor am I authorized to speak
on behalf of Intel on this matter.
11:11 a.m.
Ohly, Patrick wrote:
On Wed, 2009-08-05 at 09:20 +0100, Zhao, Forrest wrote:
>> <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>
>
> Take OBEX server/SyncML client binding for example, what name is
> appropriate for "peer_description"?
Do you have access to device information in obexd? Using the device
name would be suitable, or the brand + model.
Local device information or remote device information? Do you mean the bluetooth adapter
device information?
>> <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>
>
> Is it appropriate to set "transport" to "OBEX" in obexd plugin?
I think org.openobex would be better (there might be different OBEX
transports).
>> <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>
>
> How should obexd plugin know if the SyncML-level authentication is
> needed?
The peer must have paired before it is allowed to ask for an OBEX
connection. As a first approximation I'd say that this is enough to
ensure that the peer is authenticated already, so use
must_authenticate=false in all cases.
This is rather crude because it does not take into account why the
user has allowed pairing, but as far as I know, this "all or nothing"
approach is what is commonly used with Bluetooth, isn't it?
No, besides the pairing process there's an authentication mechanism for each bluetooth
profile (e.g PBAP, FTP, OPP).
But here I think we are talking about the SynML-level authentication, right? Does SyncML
spec
define the authentication mechanism?
As a different example, it should be true for a HTTP server, unless
the server requires HTTP AUTH.
>> <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>
>
> For OBEX session is always 0 since OBEX has no mechanism to support
> reconnection.
Correct.
>> <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>
>>
>
> If the message is too long, OBEX would split the message into muliple
> packets and send them seperately. It would be nice for SyncEvolution
> to provide a API to transmit multiple packets belonging to one
> message.
I was arguing with myself about that. I agree that it would be nice,
but is it really worth making the API more complex? How long is "too
long" in the context of OBEX?
Library openobex send message in unit of 1500 bytes.
I think that with a small enough maximum message size (64KB? more?
less?) we can safely buffer a complete message inside obexd before
sending it over D-Bus and then wouldn't have to change the API.
OK, anyway I don't think it a good idea to cache packets, but obexd could buffer a
complete message and call process().
>> <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>
>>
> I'm afraid this way of returning data does not work. Please read
> section 6.2
> of
>
http://www.openmobilealliance.org/Technical/release_program/docs/copyrigh....
> OBEX client first send SyncML request to OBEX server by PUT command;
> then OBEX server can't return data to OBEX client actively. OBEX
> client has to send GET command to pull results.
I had a question mark behind GET in one of my earlier emails because I
wasn't sure how the GET works.
The D-Bus API would still work as-is:
- OBEX client sends PUT, triggering an asynchronous process() call
- OBEX client sends GET, gets blocked because no data is available yet
- process() returns the response
- response is delivered to client via the pending GET
Then I have another question: after async D-Bus process() call, can SyncEvolution return
multiple results? I ask this because there's a "final" out parameter for
process().
If the OBEX client does not send a GET at all, then it is buggy. This
needs to be detected by a timeout inside SyncEvolution, just like any
other "unresponsive peer" situation. obexd can keep the response
around until either it is delivered or the connection is aborted.
OBEX is somewhat special in that it doesn't allow the transport to
push the response. Exposing this in the API would make it
unnecessarily complex for other cases where the response can be
pushed, so if possible, I'd like to hide this PUT/GET semantic inside
obexd.
11:25 a.m.
On Wed, 2009-08-05 at 10:11 +0100, Zhao, Forrest wrote:
Ohly, Patrick wrote:
> On Wed, 2009-08-05 at 09:20 +0100, Zhao, Forrest wrote:
>>> <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>
>>
>> Take OBEX server/SyncML client binding for example, what name is
>> appropriate for "peer_description"?
>
> Do you have access to device information in obexd? Using the device
> name would be suitable, or the brand + model.
Local device information or remote device information? Do you mean the bluetooth adapter
device information?
Remote. The local Bluetooth adapter information are of not much use for
the user. They might be useful for debugging, though. Should we add a
"transport_description" argument for that purpose?
>>> <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>
>>
>> How should obexd plugin know if the SyncML-level authentication is
>> needed?
>
> The peer must have paired before it is allowed to ask for an OBEX
> connection. As a first approximation I'd say that this is enough to
> ensure that the peer is authenticated already, so use
> must_authenticate=false in all cases.
>
> This is rather crude because it does not take into account why the
> user has allowed pairing, but as far as I know, this "all or nothing"
> approach is what is commonly used with Bluetooth, isn't it?
No, besides the pairing process there's an authentication mechanism
for each bluetooth profile (e.g PBAP, FTP, OPP).
Ah, I see. Then we should require that the pairing process has
authorized access to SyncML before calling connect(). must_authorize
would still be false.
Do we have a GUI for this pairing process in Moblin or in Linux desktops
in general?
But here I think we are talking about the SynML-level authentication,
right? Does SyncML spec
define the authentication mechanism?
Yes, there is a username/password mechanism. Using it in the context of
Bluetooth would not be very user-friendly though or might not work at
all (no credentials to check against on a phone).
>> If the message is too long, OBEX would split the message
into muliple
>> packets and send them seperately. It would be nice for SyncEvolution
>> to provide a API to transmit multiple packets belonging to one
>> message.
>
> I was arguing with myself about that. I agree that it would be nice,
> but is it really worth making the API more complex? How long is "too
> long" in the context of OBEX?
Library openobex send message in unit of 1500 bytes.
My guess is that sending data in such small chunks over D-Bus would lead
to too many messages and performance problems (untested).
> I think that with a small enough maximum message size (64KB?
more?
> less?) we can safely buffer a complete message inside obexd before
> sending it over D-Bus and then wouldn't have to change the API.
OK, anyway I don't think it a good idea to cache packets, but obexd
could buffer a complete message and call process().
Yes, let's do that. We can tweak the size of messages that have to
buffered and send over D-Bus once we have something working.
>>> <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>
>>>
>> I'm afraid this way of returning data does not work. Please read
>> section 6.2
>> of
>>
http://www.openmobilealliance.org/Technical/release_program/docs/copyrigh....
>> OBEX client first send SyncML request to OBEX server by PUT command;
>> then OBEX server can't return data to OBEX client actively. OBEX
>> client has to send GET command to pull results.
>
> I had a question mark behind GET in one of my earlier emails because I
> wasn't sure how the GET works.
>
> The D-Bus API would still work as-is:
> - OBEX client sends PUT, triggering an asynchronous process() call
> - OBEX client sends GET, gets blocked because no data is available yet
> - process() returns the response
> - response is delivered to client via the pending GET
Then I have another question: after async D-Bus process() call, can
SyncEvolution return multiple results?
No. There's exactly one response for each incoming message.
I ask this because there's a "final" out parameter for
process().
That signals end-of-connection, not "final response for this message".
Should I rename the parameter?
--
Best Regards, Patrick Ohly
The content of this message is my personal opinion only and although
I am an employee of Intel, the statements I make here in no way
represent Intel's position on the issue, nor am I authorized to speak
on behalf of Intel on this matter.
4:47 a.m.
Ohly, Patrick wrote:
On Wed, 2009-08-05 at 10:11 +0100, Zhao, Forrest wrote:
> Ohly, Patrick wrote:
>> On Wed, 2009-08-05 at 09:20 +0100, Zhao, Forrest wrote:
>>>> <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>
>>>
>>> Take OBEX server/SyncML client binding for example, what name is
>>> appropriate for "peer_description"?
>>
>> Do you have access to device information in obexd? Using the device
>> name would be suitable, or the brand + model.
>
> Local device information or remote device information? Do you mean
> the bluetooth adapter device information?
Remote. The local Bluetooth adapter information are of not much use
for the user. They might be useful for debugging, though. Should we
add a "transport_description" argument for that purpose?
Now I understand the meaning of "peer_description". Let's add
"transport_description" argument if necessary in the future.
>>>> <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>
>>>
>>> How should obexd plugin know if the SyncML-level authentication is
>>> needed?
>>
>> The peer must have paired before it is allowed to ask for an OBEX
>> connection. As a first approximation I'd say that this is enough to
>> ensure that the peer is authenticated already, so use
>> must_authenticate=false in all cases.
>>
>> This is rather crude because it does not take into account why the
>> user has allowed pairing, but as far as I know, this "all or
>> nothing" approach is what is commonly used with Bluetooth, isn't it?
>
> No, besides the pairing process there's an authentication mechanism
> for each bluetooth profile (e.g PBAP, FTP, OPP).
Ah, I see. Then we should require that the pairing process has
authorized access to SyncML before calling connect(). must_authorize
would still be false.
Do we have a GUI for this pairing process in Moblin or in Linux
desktops in general?
Gnome-bluez, which is maintained by Marcel, is GUI for BlueZ. We could
use it for development purpose. The bluetooth GUI in Moblin is owned by
Guru team. I don't know much about the current status.
> But here I think we are talking about the SynML-level
> authentication, right? Does SyncML spec
> define the authentication mechanism?
Yes, there is a username/password mechanism. Using it in the context
of Bluetooth would not be very user-friendly though or might not work
at all (no credentials to check against on a phone).
>>> If the message is too long, OBEX would split the message into
>>> muliple packets and send them seperately. It would be nice for
>>> SyncEvolution to provide a API to transmit multiple packets
>>> belonging to one message.
>>
>> I was arguing with myself about that. I agree that it would be nice,
>> but is it really worth making the API more complex? How long is "too
>> long" in the context of OBEX?
>
> Library openobex send message in unit of 1500 bytes.
My guess is that sending data in such small chunks over D-Bus would
lead to too many messages and performance problems (untested).
>> I think that with a small enough maximum message size (64KB? more?
>> less?) we can safely buffer a complete message inside obexd before
>> sending it over D-Bus and then wouldn't have to change the API.
>
> OK, anyway I don't think it a good idea to cache packets, but obexd
> could buffer a complete message and call process().
Yes, let's do that. We can tweak the size of messages that have to
buffered and send over D-Bus once we have something working.
>>>> <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>
>>>>
>>> I'm afraid this way of returning data does not work. Please read
>>> section 6.2 of
>>>
http://www.openmobilealliance.org/Technical/release_program/docs/copyrigh....
>>> OBEX client first send SyncML request to OBEX server by PUT
>>> command; then OBEX server can't return data to OBEX client
>>> actively. OBEX client has to send GET command to pull results.
>>
>> I had a question mark behind GET in one of my earlier emails
>> because I wasn't sure how the GET works.
>>
>> The D-Bus API would still work as-is:
>> - OBEX client sends PUT, triggering an asynchronous process() call
>> - OBEX client sends GET, gets blocked because no data is available
>> yet
>> - process() returns the response
>> - response is delivered to client via the pending GET
>
> Then I have another question: after async D-Bus process() call, can
> SyncEvolution return multiple results?
No. There's exactly one response for each incoming message.
> I ask this because there's a "final" out parameter for process().
That signals end-of-connection, not "final response for this message".
Should I rename the parameter?
OK, I understand the meaning of this parameter. No need to rename it.
Now I think I understand the requriement for OBEX server/SyncEvolution client binding.
Then I have 2 questions:
1 when can I expect to have the SyncEvolution client, which implement the proposed
D-Bus API?
2 where can I find a peer (i.e. OBEX client/SyncML server) to debug to-be-developed
obexd plugin for SyncEvolution client?
Thanks,
Forrest
6:12 a.m.
On Thu, 2009-08-06 at 03:47 +0100, Zhao, Forrest wrote:
Ohly, Patrick wrote:
> On Wed, 2009-08-05 at 10:11 +0100, Zhao, Forrest wrote:
>> Ohly, Patrick wrote:
>>> On Wed, 2009-08-05 at 09:20 +0100, Zhao, Forrest wrote:
>>>>> <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>
>>>>
>>>> Take OBEX server/SyncML client binding for example, what name is
>>>> appropriate for "peer_description"?
>>>
>>> Do you have access to device information in obexd? Using the device
>>> name would be suitable, or the brand + model.
>>
>> Local device information or remote device information? Do you mean
>> the bluetooth adapter device information?
>
> Remote. The local Bluetooth adapter information are of not much use
> for the user. They might be useful for debugging, though. Should we
> add a "transport_description" argument for that purpose?
Now I understand the meaning of "peer_description". Let's add
"transport_description" argument if necessary in the future.
Is it possible to add parameters to a D-Bus interface without breaking
compatibility? Doesn't seem like this is possible, so I'd rather add the
parameter now.
Now I think I understand the requriement for OBEX
server/SyncEvolution client binding.
Then I have 2 questions:
1 when can I expect to have the SyncEvolution client, which implement the proposed
D-Bus API?
Just the interface, without real functionality behind it: end of next week
Fully implemented: two weeks from now
This is an aggressive schedule, with a certain risk of delays. If you
don't need it that early (for example, if you cannot start working on it
now anyway), then we should go for a less risky schedule.
What do you think is a realistic schedule for adding the obexd plugin?
Can we count on you to do it? I assume we can, but I wanted to give you
a chance to say "no" ;-)
2 where can I find a peer (i.e. OBEX client/SyncML server) to debug
to-be-developed
obexd plugin for SyncEvolution client?
libsyncml:
https://libsyncml.opensync.org/
https://libsyncml.opensync.org/wiki/obex-guide
It comes with a rudimentary syncml-ds-tool which does SyncML via OBEX,
without implementing any of the advanced SyncML logic. This should be
good enough to verify that connections can be established and (once that
works in obexd) to test SyncEvolution as OBEX server/SyncML client.
--
Best Regards, Patrick Ohly
The content of this message is my personal opinion only and although
I am an employee of Intel, the statements I make here in no way
represent Intel's position on the issue, nor am I authorized to speak
on behalf of Intel on this matter.
12:49 p.m.
Hello!
I'd like to revise the D-Bus API a bit. See below.
On Wed, 2009-08-05 at 11:25 +0200, Patrick Ohly wrote:
On Wed, 2009-08-05 at 10:11 +0100, Zhao, Forrest wrote:
> Ohly, Patrick wrote:
> > On Wed, 2009-08-05 at 09:20 +0100, Zhao, Forrest wrote:
> >>> <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>
> >>
> >> Take OBEX server/SyncML client binding for example, what name is
> >> appropriate for "peer_description"?
> >
> > Do you have access to device information in obexd? Using the device
> > name would be suitable, or the brand + model.
>
> Local device information or remote device information? Do you mean the bluetooth
adapter device information?
Remote. The local Bluetooth adapter information are of not much use for
the user. They might be useful for debugging, though. Should we add a
"transport_description" argument for that purpose?
I think we should, and there may be more types of optional information
that we might have to add in the future. Therefore I suggest to replace
Connect(peer_description, peer_id, transport, ...) with
Connect(peer, ...) where peer is string->string dictionary with the
following predefined keys: "description", "id",
"transport",
"transport_description".
All of these are optional in the context of OBEX, but providing some of
the information for debugging purposes would be useful.
The advantage of the dictionary is that we can add other auxiliary
information later on without breaking the API. The disadvantage is more
complex method argument encoding in obexd.
dbus_message_append_args() does not support dict entries, one has to use
an iterator. Here's an example:
const char *key = "transport";
const char *value = "org.openobex.obexd";
DBusMessageIter sub;
dbus_message_iter_open_container(&iter, DBUS_TYPE_ARRAY, "{ss}", &sub);
DBusMessageIter entry;
dbus_message_iter_open_container(&sub, DBUS_TYPE_DICT_ENTRY, NULL, &entry);
dbus_message_iter_append_basic(&entry, DBUS_TYPE_STRING, &key);
dbus_message_iter_append_basic(&entry, DBUS_TYPE_STRING, &value);
dbus_message_iter_close_container(&sub, &entry);
dbus_message_iter_close_container(&iter, &sub);
The arguments before and after this dictionary can be appended normally.
For similar reasons, I suggest to move the connection.response()
response_url retval into a dictionary. This dictionary can be skipped
when parsing the reply.
--
Best Regards, Patrick Ohly
The content of this message is my personal opinion only and although
I am an employee of Intel, the statements I make here in no way
represent Intel's position on the issue, nor am I authorized to speak
on behalf of Intel on this matter.
2:12 a.m.
Hi Patrick,
When will your defined API for OBEX server/SyncML client be ready? I'll work on this
fulltime and need the SyncML client code to do the debug/test.
Thanks,
Forrest
-----Original Message-----
From: Ohly, Patrick
Sent: 2009年8月21日 18:50
To: Zhao, Forrest
Cc: SyncEvolution; Holtmann, Marcel
Subject: RE: [SyncEvolution] SyncML + OBEX
Hello!
I'd like to revise the D-Bus API a bit. See below.
On Wed, 2009-08-05 at 11:25 +0200, Patrick Ohly wrote:
On Wed, 2009-08-05 at 10:11 +0100, Zhao, Forrest wrote:
> Ohly, Patrick wrote:
> > On Wed, 2009-08-05 at 09:20 +0100, Zhao, Forrest wrote:
> >>> <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>
> >>
> >> Take OBEX server/SyncML client binding for example, what name is
> >> appropriate for "peer_description"?
> >
> > Do you have access to device information in obexd? Using the device
> > name would be suitable, or the brand + model.
>
> Local device information or remote device information? Do you mean the bluetooth
adapter device information?
Remote. The local Bluetooth adapter information are of not much use for
the user. They might be useful for debugging, though. Should we add a
"transport_description" argument for that purpose?
I think we should, and there may be more types of optional information
that we might have to add in the future. Therefore I suggest to replace
Connect(peer_description, peer_id, transport, ...) with
Connect(peer, ...) where peer is string->string dictionary with the
following predefined keys: "description", "id",
"transport",
"transport_description".
All of these are optional in the context of OBEX, but providing some of
the information for debugging purposes would be useful.
The advantage of the dictionary is that we can add other auxiliary
information later on without breaking the API. The disadvantage is more
complex method argument encoding in obexd.
dbus_message_append_args() does not support dict entries, one has to use
an iterator. Here's an example:
const char *key = "transport";
const char *value = "org.openobex.obexd";
DBusMessageIter sub;
dbus_message_iter_open_container(&iter, DBUS_TYPE_ARRAY, "{ss}",
&sub);
DBusMessageIter entry;
dbus_message_iter_open_container(&sub, DBUS_TYPE_DICT_ENTRY, NULL, &entry);
dbus_message_iter_append_basic(&entry, DBUS_TYPE_STRING, &key);
dbus_message_iter_append_basic(&entry, DBUS_TYPE_STRING, &value);
dbus_message_iter_close_container(&sub, &entry);
dbus_message_iter_close_container(&iter, &sub);
The arguments before and after this dictionary can be appended normally.
For similar reasons, I suggest to move the connection.response()
response_url retval into a dictionary. This dictionary can be skipped
when parsing the reply.
--
Best Regards, Patrick Ohly
The content of this message is my personal opinion only and although
I am an employee of Intel, the statements I make here in no way
represent Intel's position on the issue, nor am I authorized to speak
on behalf of Intel on this matter.
12:25 p.m.
On Fri, 2009-09-11 at 01:12 +0100, Zhao, Forrest wrote:
When will your defined API for OBEX server/SyncML client be ready?
I'll work on this fulltime and need the SyncML client code to do the debug/test.
You can check out the "dbus-api" branch of syncevolution and the
"master" branch of libsynthesis on git.moblin.org. Configure
SyncEvolution with "--enable-dbus-service --with-synthesis-src=<path to
your libsynthesis repo>". Compile and then run
"src/syncevo-dbus-server". It provides the D-Bus APIs described in
src/dbus/interfaces.
There's also test/dbus-server-connect.py which establishes a connection
and does a dummy message exchange with the server. Real SyncML traffic
is not supported yet. I hope to get to this next week.
--
Best Regards, Patrick Ohly
The content of this message is my personal opinion only and although
I am an employee of Intel, the statements I make here in no way
represent Intel's position on the issue, nor am I authorized to speak
on behalf of Intel on this matter.
6:02 p.m.
I have a question maybe out of scope.
The "Connect" seems only covers Server Transport logic (can be
SyncML server or client), i.e. it's the peer contacting SyncEvolution.
What about Client Transport logic? GUI needs it to init EvolutionSyncClient
(can be both SyncML server or client). Will there be another method?
<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>
_______________________________________________
SyncEvolution mailing list
SyncEvolution(a)syncevolution.org
http://lists.syncevolution.org/listinfo/syncevolution
7:52 p.m.
On Wed, 2009-08-05 at 17:02 +0100, Chen, Congwu wrote:
I have a question maybe out of scope.
The "Connect" seems only covers Server Transport logic (can be
SyncML server or client), i.e. it's the peer contacting SyncEvolution.
What about Client Transport logic? GUI needs it to init EvolutionSyncClient
(can be both SyncML server or client). Will there be another method?
There are two solutions:
1. do it in-process, like we do at the moment for HTTP via
libsoup/libcurl (libopenobex?)
2. define a D-Bus interface for outgoing connections
Solution 1 might give better performance, but also creates additional
dependencies (and code) in our binary. The second solution might be
easier overall, but requires further discussion (how do we address the
peer which is to be contacted?) and changes in obexd.
We deferred that at the moment. Any ideas about the addressing issue?
The org.syncevolution.connection interface might be the same.
--
Best Regards, Patrick Ohly
The content of this message is my personal opinion only and although
I am an employee of Intel, the statements I make here in no way
represent Intel's position on the issue, nor am I authorized to speak
on behalf of Intel on this matter.
4063
days inactive
4112
days old
syncevolution@synevolution.org
23 comments
3 participants
participants (3)
-
Chen, Congwu -
Patrick Ohly -
Zhao, Forrest