Tweak Dmedia.Resolve() DBus method

[Jason Gerard DeRose]

From an application perspective, the fundamental job of Dmedia is to resolve Dmedia file IDs into a regular file path.

For example, this file ID:

5PULSAF3PFR4VPNJMLSAJ362HG475NDKKISDYXW7WUJCFUJN

Might resolve into the regular file path:

/media/MyDrive/.dmedia/files/5P/ULSAF3PFR4VPNJMLSAJ362HG475NDKKISDYXW7WUJCFUJN

We want existing applications to require minimal change to integrate with Dmedia. There are certain things that would require deeper integration for the best user experience (for example, displaying a download progress as a file is downloaded from another device on the same localnetwork), but for a bare-bones integration, resolving file IDs is probably all the app will do.

So I've been thinking about our Resolve() method and some changes needed to make it easier to work with, and easier to use from languages besides Python.

Our current Resolve() method takes a file ID, and returns the file path if the file is available locally. Otherwise there is an unhanded exception, which isn't the right approach. So instead I think we should return a struct with (_id, status, filename).

Returning back the ID makes things easier for apps that are making an asynchronous method call, so that's the justification for that.

The status will be an int used as a flag to indicate the possible result states, which I think from the get-go should include:

0 - the file was resolved
1 - the file is not currently available on this device
2 - the file is unknown (not in the Dmedia library)
3 - the file ID was malformed (wrong length, not base32, etc)

And finally the filename, which will be the regular file path when the status is 0, and otherwise will be an empty string.

So the new Resolve() in signature will remain 's', and the new out signature will be '(sis)'.

What do people think about this?

Note we'll eventually have a helper C library (with GI bindings) to make it easier for applications than directly using the DBus API. That said, we still want the DBus API to be as well designed as possible.

Some interesting questions to ponder:

1) When the file isn't available on this device, to we still update the atime for that file? Personally, I think we should

2) When the file isn't available on this device, do we automatically try and download it from elsewhere, or should we require the app to explicitly request this?

3) Like above, what about when the file is on a removable drive not currently connected. Do we prompt the user to plug in a specific drive?