From: Mikel Astiz <[email protected]>
The client D-Bus documentation should mention that all transfer paths
contain a prefix consisting of the path of the session they belong to.
This can be conveniently used by clients to install D-Bus signal matches
that concentrate on the relevant signals.
---
doc/client-api.txt | 2 +-
1 files changed, 1 insertions(+), 1 deletions(-)
diff --git a/doc/client-api.txt b/doc/client-api.txt
index 839a78c..7ca65cc 100644
--- a/doc/client-api.txt
+++ b/doc/client-api.txt
@@ -466,7 +466,7 @@ Transfer hierarchy
Service org.bluez.obex.client
Interface org.bluez.obex.Transfer
-Object path [variable prefix]/{transfer0,transfer1,...}
+Object path [variable prefix]/{session0,session1,...}/{transfer0,...}
Methods dict GetProperties()
--
1.7.7.6
Hi Mikel,
On Tue, Aug 21, 2012 at 10:23 AM, Mikel Astiz <[email protected]> wrote:
> From: Mikel Astiz <[email protected]>
>
> The client D-Bus documentation should mention that all transfer paths
> contain a prefix consisting of the path of the session they belong to.
>
> This can be conveniently used by clients to install D-Bus signal matches
> that concentrate on the relevant signals.
> ---
> doc/client-api.txt | 2 +-
> 1 files changed, 1 insertions(+), 1 deletions(-)
>
> diff --git a/doc/client-api.txt b/doc/client-api.txt
> index 839a78c..7ca65cc 100644
> --- a/doc/client-api.txt
> +++ b/doc/client-api.txt
> @@ -466,7 +466,7 @@ Transfer hierarchy
>
> Service org.bluez.obex.client
> Interface org.bluez.obex.Transfer
> -Object path [variable prefix]/{transfer0,transfer1,...}
> +Object path [variable prefix]/{session0,session1,...}/{transfer0,...}
>
> Methods dict GetProperties()
>
> --
> 1.7.7.6
I went ahead and applied this patch.
--
Luiz Augusto von Dentz
On Wed, 2012-08-22 at 15:52 +0300, Luiz Augusto von Dentz wrote:
> Hi Patrick,
>
> On Wed, Aug 22, 2012 at 3:04 PM, Patrick Ohly <[email protected]> wrote:
> > On Wed, 2012-08-22 at 14:39 +0300, Luiz Augusto von Dentz wrote:
> >> Hi Patrick,
> >>
> >> On Tue, Aug 21, 2012 at 11:31 AM, Patrick Ohly <[email protected]> wrote:
> >> > It would be even better to explicitly mention that the "[variable
> >> > prefix]" here is the same as the "[variable prefix]" in the Session.
> >> >
> >> > Or perhaps change it like this?
> >> >
> >> > -Object path [variable prefix]/{transfer0,transfer1,...}
> >> > +Object path [session prefix]/{transfer0,...}
> >>
> >> Hmm, I prefer the original proposal since that imo looks more clear
> >> how the path is formatted, anyway the point here is that the transfers
> >> are tied to sessions.
> >
> > But as Marcel said, "variable prefix" means "no guarantee made about its
> > content, none whatsoever". Without knowing Bluez conventions, that was
> > also my understand when reading the API description. Assigning some
> > other meaning to "variable prefix" would break with developer
> > expectations.
>
> But we are not changing that, that why we return the object path to
> you, you will never have to guess it.
Knowing the path in advance is relevant for the client so that it can
set up an efficient signal watch before starting the transfer. That in
turn is needed to avoid race conditions. At the time that the client is
told the final path, it may already be too late to do anything with the
path.
> > Unless the meaning of "variable prefix" gets redefined, "[variable
> > prefix]/{session0,session1,...}" still doesn't allow the developer to do
> > path_namespace filtering.
>
> Im not sure why this is important? Prefix or variable prefix it does
> not matter, you will not be able to hardcode nor you should be
> constructing a path based on the session prefix, so if you are
> planning to do prefix matching I would strongly advise not to.
The prefix would not be hard-coded. The steps would be:
- create a session
- register for Transfer signals with a path prefix filter for the
session path as returned by obexd
- start a transfer
- process the signals
Currently this is not correct behavior, because the API makes no
guarantee about the "[variable prefix]" of Transfer objects. Therefore
clients have to receive and process *all* Transfer signals to avoid the
race condition described in the "obexd client API" mail.
I thought the purpose of the patch was to add that guarantee to the API
description.
> > I can imagine three ways to address race conditions:
> > 1. Clients subscribe to signals in advance, before any are sent.
>
> Can be done already, but it means you have to listen to every transfer
> which can cause you application to wakeup a little too much.
Exactly.
> > 2. Clients subscribe to signals later *and* check the current state.
> > 3. Clients provide a callback object with methods which get invoked by
> > obexd.
> >
> > The second option increases traffic and depends on being able to check
> > the current state. Currently this approach is not possible for Transfer
> > objects because they can get removed before the client checked their
> > state.
>
> I don't thing this is true, we do return the properties of the
> transfer so you don't need to check the current state just listen for
> changes,
Listen for changes *in advance* (given the current API). The returned
properties might already be out-dated. The path information is useful,
the completion state not so much. If it says "not complete yet", the
client needs a way to check for completion or failure reliably.
> btw if you mean a method call for checking the current state
> it does happen to have the same race conditions.
Right. To make it work, the life cycle of Transfer objects would have to
be changed.
> > The third option has the drawback that there's no standard way of
> > letting the client declare which of these methods it wants to have
> > called (in contrast to D-Bus signals). The advantage is that it becomes
> > possible to clean up temp files after completion of the transfer: add an
> > explicit "here's your result" callback method and when that fails,
> > delete the temporary file.
>
> We normally used the term agent for this type of object that is
> registered to act as callback mechanism, in fact this was used before
> and was just replaced with the current design recently as it was
> considered more complicated to the client application to implement and
> did not allow any other application like a download manager to listen
> for transfer progress.
Valid points. I included the option primarily for the sake of
completeness.
--
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.
Hi Patrick,
On Wed, Aug 22, 2012 at 3:04 PM, Patrick Ohly <[email protected]> wrote:
> On Wed, 2012-08-22 at 14:39 +0300, Luiz Augusto von Dentz wrote:
>> Hi Patrick,
>>
>> On Tue, Aug 21, 2012 at 11:31 AM, Patrick Ohly <[email protected]> wrote:
>> >> diff --git a/doc/client-api.txt b/doc/client-api.txt
>> >> index 839a78c..7ca65cc 100644
>> >> --- a/doc/client-api.txt
>> >> +++ b/doc/client-api.txt
>> >> @@ -466,7 +466,7 @@ Transfer hierarchy
>> >>
>> >> Service org.bluez.obex.client
>> >> Interface org.bluez.obex.Transfer
>> >> -Object path [variable prefix]/{transfer0,transfer1,...}
>> >> +Object path [variable prefix]/{session0,session1,...}/{transfer0,...}
>> >>
>> >> Methods dict GetProperties()
>> >
>> > It would be even better to explicitly mention that the "[variable
>> > prefix]" here is the same as the "[variable prefix]" in the Session.
>> >
>> > Or perhaps change it like this?
>> >
>> > -Object path [variable prefix]/{transfer0,transfer1,...}
>> > +Object path [session prefix]/{transfer0,...}
>>
>> Hmm, I prefer the original proposal since that imo looks more clear
>> how the path is formatted, anyway the point here is that the transfers
>> are tied to sessions.
>
> But as Marcel said, "variable prefix" means "no guarantee made about its
> content, none whatsoever". Without knowing Bluez conventions, that was
> also my understand when reading the API description. Assigning some
> other meaning to "variable prefix" would break with developer
> expectations.
But we are not changing that, that why we return the object path to
you, you will never have to guess it.
> Unless the meaning of "variable prefix" gets redefined, "[variable
> prefix]/{session0,session1,...}" still doesn't allow the developer to do
> path_namespace filtering.
Im not sure why this is important? Prefix or variable prefix it does
not matter, you will not be able to hardcode nor you should be
constructing a path based on the session prefix, so if you are
planning to do prefix matching I would strongly advise not to.
> How about this:
>
> -Object path [variable prefix]/{transfer0,transfer1,...}
> +Object path [prefix]/{session0,session1,...}/{transfer0,...}"
> + with "prefix" as in the corresponding session
>
>> > Using this knowledge efficiently is not always possible, however. D-Bus
>> > itself has a "path_namespace" filter [1], but many D-Bus bindings don't
>> > expose it (Python [2], GIO D-Bus [3]). Therefore a client using those
>> > bindings still has to receive all Transfer signals and do its own
>> > filtering.
>> >
>> > [1] http://dbus.freedesktop.org/doc/dbus-specification.html#message-bus-routing-match-rules
>> > [2] http://dbus.freedesktop.org/doc/dbus-python/api/dbus.connection.Connection-class.html#add_signal_receiver
>> > [3] http://developer.gnome.org/gio/stable/GDBusConnection.html#g-dbus-connection-signal-subscribe
>>
>> Apparently people are not doing a good job with bindings then, arg
>> matching is quite essential to things like NameOwnerChanged, anyway
>> for what is worth even properties have this race condition with values
>> changing in meantime while GetAll/Get/GetProperties is returning, so
>> it seems we need to solve this problem by making the transfer
>> properties unlikely to change so the application have enough time to
>> subscribe to signals.
>
> "unlikely" doesn't sit well with me. An unlikely failure is still a
> failure. Tell me if I'm too pedantic here ;-)
I said unlikely because we cannot guarantee that we dont get some
unexpected event e.g. remote device crash/disconnects.
> I can imagine three ways to address race conditions:
> 1. Clients subscribe to signals in advance, before any are sent.
Can be done already, but it means you have to listen to every transfer
which can cause you application to wakeup a little too much.
> 2. Clients subscribe to signals later *and* check the current state.
> 3. Clients provide a callback object with methods which get invoked by
> obexd.
>
> The second option increases traffic and depends on being able to check
> the current state. Currently this approach is not possible for Transfer
> objects because they can get removed before the client checked their
> state.
I don't thing this is true, we do return the properties of the
transfer so you don't need to check the current state just listen for
changes, btw if you mean a method call for checking the current state
it does happen to have the same race conditions.
> The third option has the drawback that there's no standard way of
> letting the client declare which of these methods it wants to have
> called (in contrast to D-Bus signals). The advantage is that it becomes
> possible to clean up temp files after completion of the transfer: add an
> explicit "here's your result" callback method and when that fails,
> delete the temporary file.
We normally used the term agent for this type of object that is
registered to act as callback mechanism, in fact this was used before
and was just replaced with the current design recently as it was
considered more complicated to the client application to implement and
did not allow any other application like a download manager to listen
for transfer progress.
--
Luiz Augusto von Dentz
Hi Patrick,
On Wed, Aug 22, 2012 at 2:04 PM, Patrick Ohly <[email protected]> wrote:
> On Wed, 2012-08-22 at 14:39 +0300, Luiz Augusto von Dentz wrote:
>> Hi Patrick,
>>
>> On Tue, Aug 21, 2012 at 11:31 AM, Patrick Ohly <[email protected]> wrote:
>> >> diff --git a/doc/client-api.txt b/doc/client-api.txt
>> >> index 839a78c..7ca65cc 100644
>> >> --- a/doc/client-api.txt
>> >> +++ b/doc/client-api.txt
>> >> @@ -466,7 +466,7 @@ Transfer hierarchy
>> >>
>> >> Service org.bluez.obex.client
>> >> Interface org.bluez.obex.Transfer
>> >> -Object path [variable prefix]/{transfer0,transfer1,...}
>> >> +Object path [variable prefix]/{session0,session1,...}/{transfer0,...}
>> >>
>> >> Methods dict GetProperties()
>> >
>> > It would be even better to explicitly mention that the "[variable
>> > prefix]" here is the same as the "[variable prefix]" in the Session.
>> >
>> > Or perhaps change it like this?
>> >
>> > -Object path [variable prefix]/{transfer0,transfer1,...}
>> > +Object path [session prefix]/{transfer0,...}
>>
>> Hmm, I prefer the original proposal since that imo looks more clear
>> how the path is formatted, anyway the point here is that the transfers
>> are tied to sessions.
>
> But as Marcel said, "variable prefix" means "no guarantee made about its
> content, none whatsoever". Without knowing Bluez conventions, that was
> also my understand when reading the API description. Assigning some
> other meaning to "variable prefix" would break with developer
> expectations.
>
> Unless the meaning of "variable prefix" gets redefined, "[variable
> prefix]/{session0,session1,...}" still doesn't allow the developer to do
> path_namespace filtering.
>
> How about this:
>
> -Object path [variable prefix]/{transfer0,transfer1,...}
> +Object path [prefix]/{session0,session1,...}/{transfer0,...}"
> + with "prefix" as in the corresponding session
>From my point of view, this is beyond the scope of this patch. The
modification proposed here is in general consistent with the existing
documentation in the mentioned projects, and in particular with the
file being modified (see org.bluez.obex.Message).
I agree that the exact interpretation of "variable prefix" is
undocumented, but fixing that has a broad scope affecting several
projects. See for example org.bluez.Device or org.ofono.VoiceCall.
Personally, I find it relatively obvious that both variable prefixes
match. Otherwise there would be no reference to the session (or
BlueZ-adapter, oFono-modem, etc., depending on the case).
Regarding the lack of support in some bindings, I would say it's not
critical. After all, we're doing an optimization here (reduce number
of context-switches). If someone is using a limited binding, then
there's a performance penalty.
Cheers,
Mikel
On Wed, 2012-08-22 at 14:39 +0300, Luiz Augusto von Dentz wrote:
> Hi Patrick,
>
> On Tue, Aug 21, 2012 at 11:31 AM, Patrick Ohly <[email protected]> wrote:
> >> diff --git a/doc/client-api.txt b/doc/client-api.txt
> >> index 839a78c..7ca65cc 100644
> >> --- a/doc/client-api.txt
> >> +++ b/doc/client-api.txt
> >> @@ -466,7 +466,7 @@ Transfer hierarchy
> >>
> >> Service org.bluez.obex.client
> >> Interface org.bluez.obex.Transfer
> >> -Object path [variable prefix]/{transfer0,transfer1,...}
> >> +Object path [variable prefix]/{session0,session1,...}/{transfer0,...}
> >>
> >> Methods dict GetProperties()
> >
> > It would be even better to explicitly mention that the "[variable
> > prefix]" here is the same as the "[variable prefix]" in the Session.
> >
> > Or perhaps change it like this?
> >
> > -Object path [variable prefix]/{transfer0,transfer1,...}
> > +Object path [session prefix]/{transfer0,...}
>
> Hmm, I prefer the original proposal since that imo looks more clear
> how the path is formatted, anyway the point here is that the transfers
> are tied to sessions.
But as Marcel said, "variable prefix" means "no guarantee made about its
content, none whatsoever". Without knowing Bluez conventions, that was
also my understand when reading the API description. Assigning some
other meaning to "variable prefix" would break with developer
expectations.
Unless the meaning of "variable prefix" gets redefined, "[variable
prefix]/{session0,session1,...}" still doesn't allow the developer to do
path_namespace filtering.
How about this:
-Object path [variable prefix]/{transfer0,transfer1,...}
+Object path [prefix]/{session0,session1,...}/{transfer0,...}"
+ with "prefix" as in the corresponding session
> > Using this knowledge efficiently is not always possible, however. D-Bus
> > itself has a "path_namespace" filter [1], but many D-Bus bindings don't
> > expose it (Python [2], GIO D-Bus [3]). Therefore a client using those
> > bindings still has to receive all Transfer signals and do its own
> > filtering.
> >
> > [1] http://dbus.freedesktop.org/doc/dbus-specification.html#message-bus-routing-match-rules
> > [2] http://dbus.freedesktop.org/doc/dbus-python/api/dbus.connection.Connection-class.html#add_signal_receiver
> > [3] http://developer.gnome.org/gio/stable/GDBusConnection.html#g-dbus-connection-signal-subscribe
>
> Apparently people are not doing a good job with bindings then, arg
> matching is quite essential to things like NameOwnerChanged, anyway
> for what is worth even properties have this race condition with values
> changing in meantime while GetAll/Get/GetProperties is returning, so
> it seems we need to solve this problem by making the transfer
> properties unlikely to change so the application have enough time to
> subscribe to signals.
"unlikely" doesn't sit well with me. An unlikely failure is still a
failure. Tell me if I'm too pedantic here ;-)
I can imagine three ways to address race conditions:
1. Clients subscribe to signals in advance, before any are sent.
2. Clients subscribe to signals later *and* check the current state.
3. Clients provide a callback object with methods which get invoked by
obexd.
The second option increases traffic and depends on being able to check
the current state. Currently this approach is not possible for Transfer
objects because they can get removed before the client checked their
state.
The third option has the drawback that there's no standard way of
letting the client declare which of these methods it wants to have
called (in contrast to D-Bus signals). The advantage is that it becomes
possible to clean up temp files after completion of the transfer: add an
explicit "here's your result" callback method and when that fails,
delete the temporary file.
--
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.
Hi Patrick,
On Tue, Aug 21, 2012 at 11:31 AM, Patrick Ohly <[email protected]> wrote:
>> diff --git a/doc/client-api.txt b/doc/client-api.txt
>> index 839a78c..7ca65cc 100644
>> --- a/doc/client-api.txt
>> +++ b/doc/client-api.txt
>> @@ -466,7 +466,7 @@ Transfer hierarchy
>>
>> Service org.bluez.obex.client
>> Interface org.bluez.obex.Transfer
>> -Object path [variable prefix]/{transfer0,transfer1,...}
>> +Object path [variable prefix]/{session0,session1,...}/{transfer0,...}
>>
>> Methods dict GetProperties()
>
> It would be even better to explicitly mention that the "[variable
> prefix]" here is the same as the "[variable prefix]" in the Session.
>
> Or perhaps change it like this?
>
> -Object path [variable prefix]/{transfer0,transfer1,...}
> +Object path [session prefix]/{transfer0,...}
Hmm, I prefer the original proposal since that imo looks more clear
how the path is formatted, anyway the point here is that the transfers
are tied to sessions.
> Using this knowledge efficiently is not always possible, however. D-Bus
> itself has a "path_namespace" filter [1], but many D-Bus bindings don't
> expose it (Python [2], GIO D-Bus [3]). Therefore a client using those
> bindings still has to receive all Transfer signals and do its own
> filtering.
>
> [1] http://dbus.freedesktop.org/doc/dbus-specification.html#message-bus-routing-match-rules
> [2] http://dbus.freedesktop.org/doc/dbus-python/api/dbus.connection.Connection-class.html#add_signal_receiver
> [3] http://developer.gnome.org/gio/stable/GDBusConnection.html#g-dbus-connection-signal-subscribe
Apparently people are not doing a good job with bindings then, arg
matching is quite essential to things like NameOwnerChanged, anyway
for what is worth even properties have this race condition with values
changing in meantime while GetAll/Get/GetProperties is returning, so
it seems we need to solve this problem by making the transfer
properties unlikely to change so the application have enough time to
subscribe to signals.
--
Luiz Augusto von Dentz
Hi Marcel,
On Tue, Aug 21, 2012 at 2:08 PM, Marcel Holtmann <[email protected]> wrote:
> Hi Mikel,
>
>> >> The client D-Bus documentation should mention that all transfer paths
>> >> contain a prefix consisting of the path of the session they belong to.
>> >>
>> >> This can be conveniently used by clients to install D-Bus signal matches
>> >> that concentrate on the relevant signals.
>> >> ---
>> >> doc/client-api.txt | 2 +-
>> >> 1 files changed, 1 insertions(+), 1 deletions(-)
>> >>
>> >> diff --git a/doc/client-api.txt b/doc/client-api.txt
>> >> index 839a78c..7ca65cc 100644
>> >> --- a/doc/client-api.txt
>> >> +++ b/doc/client-api.txt
>> >> @@ -466,7 +466,7 @@ Transfer hierarchy
>> >>
>> >> Service org.bluez.obex.client
>> >> Interface org.bluez.obex.Transfer
>> >> -Object path [variable prefix]/{transfer0,transfer1,...}
>> >> +Object path [variable prefix]/{session0,session1,...}/{transfer0,...}
>> >>
>> >> Methods dict GetProperties()
>> >
>> > It would be even better to explicitly mention that the "[variable
>> > prefix]" here is the same as the "[variable prefix]" in the Session.
>>
>> This documentation pattern can be widely found in Obexd and Bluez, as
>> well as oFono. It's implicit that the variable prefix matches in both
>> cases.
>
> it actually means that you can not count on this prefix. It might change
> and it is perfect legal that it changes from one run of the daemon to
> another. The variable prefix is discovered via some defined initial
> method.
Indeed, you cannot rely on a stable prefix across different runs and
clients should not try to parse these strings, but you do have
relationships between objects that are guaranteed in the object path.
In this case you do know that, as long as the session is active (and
obviously the daemon is running), the session path will be an exact
prefix of the transfer path.
> Remember that I intermixed the PID in the object path of BlueZ. Simple
> because people started hardcoding object paths.
Yes, we need to be careful to avoid clients making false assumptions
about these paths.
Cheers,
Mikel
Hi Mikel,
> >> The client D-Bus documentation should mention that all transfer paths
> >> contain a prefix consisting of the path of the session they belong to.
> >>
> >> This can be conveniently used by clients to install D-Bus signal matches
> >> that concentrate on the relevant signals.
> >> ---
> >> doc/client-api.txt | 2 +-
> >> 1 files changed, 1 insertions(+), 1 deletions(-)
> >>
> >> diff --git a/doc/client-api.txt b/doc/client-api.txt
> >> index 839a78c..7ca65cc 100644
> >> --- a/doc/client-api.txt
> >> +++ b/doc/client-api.txt
> >> @@ -466,7 +466,7 @@ Transfer hierarchy
> >>
> >> Service org.bluez.obex.client
> >> Interface org.bluez.obex.Transfer
> >> -Object path [variable prefix]/{transfer0,transfer1,...}
> >> +Object path [variable prefix]/{session0,session1,...}/{transfer0,...}
> >>
> >> Methods dict GetProperties()
> >
> > It would be even better to explicitly mention that the "[variable
> > prefix]" here is the same as the "[variable prefix]" in the Session.
>
> This documentation pattern can be widely found in Obexd and Bluez, as
> well as oFono. It's implicit that the variable prefix matches in both
> cases.
it actually means that you can not count on this prefix. It might change
and it is perfect legal that it changes from one run of the daemon to
another. The variable prefix is discovered via some defined initial
method.
Remember that I intermixed the PID in the object path of BlueZ. Simple
because people started hardcoding object paths.
Regards
Marcel
Hi Patrick,
On Tue, Aug 21, 2012 at 10:31 AM, Patrick Ohly <[email protected]> wrote:
> On Tue, 2012-08-21 at 09:23 +0200, Mikel Astiz wrote:
>> From: Mikel Astiz <[email protected]>
>>
>> The client D-Bus documentation should mention that all transfer paths
>> contain a prefix consisting of the path of the session they belong to.
>>
>> This can be conveniently used by clients to install D-Bus signal matches
>> that concentrate on the relevant signals.
>> ---
>> doc/client-api.txt | 2 +-
>> 1 files changed, 1 insertions(+), 1 deletions(-)
>>
>> diff --git a/doc/client-api.txt b/doc/client-api.txt
>> index 839a78c..7ca65cc 100644
>> --- a/doc/client-api.txt
>> +++ b/doc/client-api.txt
>> @@ -466,7 +466,7 @@ Transfer hierarchy
>>
>> Service org.bluez.obex.client
>> Interface org.bluez.obex.Transfer
>> -Object path [variable prefix]/{transfer0,transfer1,...}
>> +Object path [variable prefix]/{session0,session1,...}/{transfer0,...}
>>
>> Methods dict GetProperties()
>
> It would be even better to explicitly mention that the "[variable
> prefix]" here is the same as the "[variable prefix]" in the Session.
This documentation pattern can be widely found in Obexd and Bluez, as
well as oFono. It's implicit that the variable prefix matches in both
cases.
> Or perhaps change it like this?
>
> -Object path [variable prefix]/{transfer0,transfer1,...}
> +Object path [session prefix]/{transfer0,...}
Having said that, I'm not against using this other style. In that case
we would need to change lots of files for consistency.
Cheers,
Mikel
On Tue, 2012-08-21 at 09:23 +0200, Mikel Astiz wrote:
> From: Mikel Astiz <[email protected]>
>
> The client D-Bus documentation should mention that all transfer paths
> contain a prefix consisting of the path of the session they belong to.
>
> This can be conveniently used by clients to install D-Bus signal matches
> that concentrate on the relevant signals.
> ---
> doc/client-api.txt | 2 +-
> 1 files changed, 1 insertions(+), 1 deletions(-)
>
> diff --git a/doc/client-api.txt b/doc/client-api.txt
> index 839a78c..7ca65cc 100644
> --- a/doc/client-api.txt
> +++ b/doc/client-api.txt
> @@ -466,7 +466,7 @@ Transfer hierarchy
>
> Service org.bluez.obex.client
> Interface org.bluez.obex.Transfer
> -Object path [variable prefix]/{transfer0,transfer1,...}
> +Object path [variable prefix]/{session0,session1,...}/{transfer0,...}
>
> Methods dict GetProperties()
It would be even better to explicitly mention that the "[variable
prefix]" here is the same as the "[variable prefix]" in the Session.
Or perhaps change it like this?
-Object path [variable prefix]/{transfer0,transfer1,...}
+Object path [session prefix]/{transfer0,...}
Using this knowledge efficiently is not always possible, however. D-Bus
itself has a "path_namespace" filter [1], but many D-Bus bindings don't
expose it (Python [2], GIO D-Bus [3]). Therefore a client using those
bindings still has to receive all Transfer signals and do its own
filtering.
[1] http://dbus.freedesktop.org/doc/dbus-specification.html#message-bus-routing-match-rules
[2] http://dbus.freedesktop.org/doc/dbus-python/api/dbus.connection.Connection-class.html#add_signal_receiver
[3] http://developer.gnome.org/gio/stable/GDBusConnection.html#g-dbus-connection-signal-subscribe
--
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.