Proposed draft for the thumbnail D-Bus specification
Philip Van Hoof
spam at pvanhoof.be
Sun Oct 26 07:15:50 PDT 2008
On Fri, 2008-10-10 at 11:26 +0200, Alexander Larsson wrote:
> I don't like that the service errors out if any one file in the
> requested set fails to thumbnail. You don't even know which one failed.
> This is useless.
I have changed the error signal of the Generic thumbnailer to this:
<arg type="u" name="handle" />
<arg type="as" name="failed_uris" /> <!-- added //-->
<arg type="i" name="error_code" />
<arg type="s" name="message" />
The specialized thumbnailers now also have to pass which uris failed as
an out parameter. The Create method has been adapted to this:
<arg type="as" name="uris" direction="in" />
<arg type="s" name="mime_hint" direction="in" />
<arg type="as" name="failed_uris" direction="out" /> <!-- added //-->
> I still want to thumbnail all the other files that are
The currently adapted spec now mentions for Error:
An error does not necessarily mean that the entire queued request will
have stopped running and that therefore `Ready` signals wont happen
anymore. It's normal behaviour to emit multiple errors per queued
request. It's on the other hand also normal behaviour to emit just one
error and have all URIs that failed in `failed_uris`. An error does not
imply that either `Started` or `Finished` won't happen anymore.
`Started` and `Finished` must happen for all requests that got scheduled
using `Queue`. Also for the requests that failed for example completely.
And for Ready it now mentions:
Every URI that completed successfully must be reported using this
signal. It's possible that succeeded URIs are grouped together in
`uris`. It's also possible that only one URI is available in `uris` and
that multiple `Ready` signals will be emitted.
Request was started:
Request was completed:
The Create method (specialized thumbnailers):
In practice this means that if two out of ten has an error, then as a
result will both Ready signals and Error signals be emitted.
In how many Ready signals the thumbnailer emits the eight succeeded uris
is up to the thumbnailer itself.
In how many Error signals the thumbnailer emits the two failed ones, is
up to the thumbnailer itself.
If all ten failed, then the thumbnailer must not emit any Ready signals,
but instead must emit only Error signals. In how many Error signals the
thumbnailer emits the ten failures is up to the thumbnailer itself.
The thumbnailer is allowed to group all completions together in one
Ready signal. The thumbnailer is allowed to group all failures together
in one Error signal.
The thumbnailer is not allowed to make any item in a request disappear:
Either an item in a queued request got completed, and therefore it can
be found in one of the Ready signals, or an item in a queued request
failed and therefore it can be found in one of the Error signals.
If the results of these practical use-cases are not implied or are not
clear from the current specification, then please let me know about
this. Perhaps also point me to where I could make the current
specification more clear about it.
> A better solution would be to write out a failed thumbnail (as per
> the spec) and then call either Ready with a boolean success argument
> or a separate Failed signal.
The failed thumbnail directory is a specification of "thumbnail-spec,
the storage specification".
Although my prototype ain't doing it, is it a requirement of the storage
"thumbnail-spec" to indeed write in this directory additional failure
"Thumbnailer-spec, the D-Bus spec" merely says: "I depend on the storage
spec called thumbnail-spec". This by implication means that "Thumbnailer
spec, the D-Bus one" requires the usage of the fail directory.
It's my prototype being wrong in not doing it, not the specification.
> Also, wrt failed thumbnailings. What id should be used to look for
> failed thumbnailings?
What do you mean? Atm the spec requires passing back which URIs failed.
Which means that the app developer can use the returned URI in the list
of failed URIs to determine which exact thumbnail failed. Is that
The prototype will be adapted for all this tomorrow morning (EST).
This is the Subversion repository of the latest prototype, it's in this
repository where I will commit the changes needed for these Error
As a reminder is this the spec: http://live.gnome.org/ThumbnailerSpec
Philip Van Hoof, freelance software developer
home: me at pvanhoof dot be
gnome: pvanhoof at gnome dot org
More information about the xdg