Proposed draft for the thumbnail D-Bus specification

[Philip Van Hoof]

Hey Alexander!

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:

<signal name="Error">
      <arg type="u" name="handle" />
      <arg type="as" name="failed_uris" /> <!-- added //-->
      <arg type="i" name="error_code" />
      <arg type="s" name="message" />
</signal>

The specialized thumbnailers now also have to pass which uris failed as
an out parameter. The Create method has been adapted to this:

<node name="/com/company/Thumbnailer">
  <interface name="org.freedesktop.thumbnailer.Thumbnailer">  
    <method name="Create">
      <arg type="as" name="uris" direction="in" />
      <arg type="s" name="mime_hint" direction="in" />
      <arg type="as" name="failed_uris" direction="out" /> <!-- added //-->
    </method>
  </interface>
</node>

> I still want to thumbnail all the other files that are
> thumbnailable.

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.

"

Relevant sections:

Error occurred:
http://live.gnome.org/ThumbnailerSpec#head-522e22554be2f71e9a80b4b1671dae7d745c43a7

Request was started:
http://live.gnome.org/ThumbnailerSpec#head-6096e140fd753c832921e9368729f7c37f5f5467

Request was completed:
http://live.gnome.org/ThumbnailerSpec#head-2fd1f5dc49d4bdd85662febe2462eccb7c41f427

The Create method (specialized thumbnailers):
http://live.gnome.org/ThumbnailerSpec#head-f010d715d5b784efd82c592472f0fb8edfcc8383


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
information.

"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.

Short:

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
sufficient?



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
reporting requirements:

https://stage.maemo.org/svn/maemo/projects/haf/trunk/hildon-thumbnail/


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 
http://pvanhoof.be/blog
http://codeminded.be