[Nautilus-list] Re: Metadata Ideas

[Darin Adler <darin eazel com>]

This is my first cut response to Ian's metadata ideas from last week, sent
to the gnome-vfs list since the message never got through to the Nautilus
list. I thought that those on Nautilus list might want to see it too.

Note that with the May 31 deadline fast approaching, we probably won't get
this into GNOME VFS in time for Nautilus 1.0

    -- Darin

----------
From: Darin Adler <darin eazel com>
Date: Wed, 24 May 2000 07:57:46 -0700
To: Ian McKellar <yakk yakk net au>, <gnome-vfs helixcode com>
Subject: Re: [GNOME VFS] Metadata Ideas

It looks good. Here are a first set detailed comments:

One problem I see with this interface is lack of error reporting. I don't
see how you're going to handle it when one of these calls doesn't work.

I'm also a bit confused about making incremental changes to the metadata.
Lets say you want to modify only the shared metadata. How do you get only
the shared metadata for a particular item so you can start modifying it?

Can you tell shared from unshared metadata when returned from the query
interfaces?

What's the format when you get both metadata for the item itself and for
children? There's nothing in XML itself that necessarily makes it clear how
to do that. You can have nested metadata, but you'd have to define a scheme
for the metadata for the children and prevent attached metadata from
conflicting with it somehow.

How can you copy all the metadata from one object to another with this API?
We want to do that when we move or copy a file.

Tying gnome-vfs to a particular version of gnome-xml is OK, I guess, but
could be a minor problem with the 1.X -> 2.0 transition gnome-xml is
currently going through.

What are the semantics when a file is deleted, renamed, or copied using
gnome-vfs calls? Does the VFS take care of removing, re-tagging, or copying
the metadata or not? Is that allowed to be different for each VFS module?
What about when the file is deleted or renamed without using gnome-vfs
calls?

> /* type of query callbacks */
> typedef void (GnomeVFSQueryCallback)(GnomeVFSURI uri, gchar *namespace,
> gboolean children, xmlDocPtr xml, gpointer user_data);

I prefer a simpler callback. No reason to feed the user's parameters back;
that just makes things more complicated, but we do have to have a way of
indicating an error in the callback:

    typedef void (* GnomeVFSQueryCallback) (GnomeVFSResult result,
                                            xmlDocPtr metadata,
                                            gpointer callback_data);

Also, you must make it clear if the client then owns the passed-in document
and must free it or must copy it and look at the data. For most designs we
use the latter approach, but for the XML library it could be a problem.

> /* attach metadata to an URI and namespace [does not block] */
> void gnome_vfs_metadata_attach (GnomeVFSURI uri, gchar *namespace,
> gboolean shared, xmlDocPtr metadata);

This should be:

    GnomeVFSResult gnome_vfs_metadata_attach (GnomeVFSURI *uri,
                                              const gchar *namespace,
                                              gboolean shared,
                                              xmlDocPtr metadata);

Also, you must be clear. Does gnome_vfs_metadata_attach take ownership of
the document pointer or not?

Also, Nautilus currently uses async. I/O for writing as well as reading
metadata, so I think we'll need an async. version of this as well.

> /* query metadata for URI and namespace [blocks] */
> xmlDocPtr gnome_vfs_metadata_query(GnomeVFSURI uri, gchar *namespace,
> gboolean children);

Need a way to indicate an error.

As I mentioned above, what format does the returned document use for the
child metadata? If you pass this same document back to attach does it attach
the child parts to the children? If not, what about the confusion of
metadata attached to the parent that exactly matches the format normally
used to indicate child metadata?

    GnomeVFSResult gnome_vfs_metadata_query (GnomeVFSURI *uri,
                                             const gchar *namespace,
                                        gboolean include_child_metadata,
                                             xmlDocPtr *metadata);

> /* query metadata for URI and namespace [return result via callback] */
> void gnome_vfs_metadata_async_query(GnomeVFSURI uri, gchar *namespace,
> gboolean children, GnomeVFSQueryCallback callback, gpointer user_data);

You must return an async. handle so the operation can be canceled:

    void gnome_vfs_metadata_async_query (GnomeVFSAsyncHandle **handle,
                                         GnomeVFSURI *uri,
                                         const gchar *namespace,
                                         gboolean include_child_metadata,
                                         GnomeVFSQueryCallback callback,
                                         gpointer callback_data);

> /* detach metadata from an URI and namespace [does not block] */
> void gnome_vfs_metadata_detach(GnomeVFSURI uri, gchar *namespace);

If this does not block, how do you know when it's done? Can you cancel it?
How can you tell if it succeeds or fails?

    void gnome_vfs_metadata_detach (GnomeVFSURI *uri,
                                    const gchar *namespace);

> I think this model is flexible and efficient enough for Nautilus and other
> applications.

I'm sure it will be efficient enough since it falls back to exactly what
Nautilus currently supports. But it's not yet flexible enough (as described
above).

    -- Darin