Bug 39644

I suggest we could have Channel.Interface.FTMetadata:
  property ServiceName: s
  property Stuff: a{sv}

by analogy to Service[Name] and Parameters on C.T.{Stream,DBus}Tube and C.I.Tube. These could just be shoved into a data form or something in the FT offer.

Having a separate ServiceName property would make it easier for applications to exchange files, bypassing the standard handler. For instance, the Banshee Telepathy plugin currently matches on MimeType; I think it would be more robust to be able to explicitly direct transfers to Banshee, just like one can direct tubes (and ytstenut channels) to particular named services. Splitting it out of the a{sv} makes it possible to use it in a filter.

We could restrict the 'v' to 's' and 'as', or possibly just have an a{ss} like Tubes and use the same XMPP-level representation as used by tubes, and reserve a specific key for the ServiceName property. or we could make a new thing.

We would define a caps URI for our metadata extension on FT; and advertise supported values of ServiceName as fragments at the end of it ("#uk.co.wjt.icedcoffee"). Clients can use ContactCaps to get at and set this information.

Here's a branch, you cool guys.

http://people.freedesktop.org/~jonny/telepathy-spec-ft_metadata/spec/Channel_Interface_File_Transfer_Metadata.html is pretty the HTML for your pleasure.

I think that a handler should be able to set/add more metadata when it receives a channel already created. Also it would be much more useful if metadata could be sent as "triples" (e.g. to transfer RDF metadata)

Is it possible to add, for example, a method provideMetadata (for the sender) and a method acceptMetadata (for the receiver) to get more flexibility?
These methods should be able to transfer an RDF/XML string...

Of course it could be possible to set an rdf/xml string as the value of a ss pair, but still a handler will not be able to set it...

(In reply to comment #3)
> I think that a handler should be able to set/add more metadata when it receives
> a channel already created. Also it would be much more useful if metadata could
> be sent as "triples" (e.g. to transfer RDF metadata)

By a similar token, some people might want to send XML metadata, or JSON, or whatever. They're all equally well-supported by just bunging a string into the dictionary of metadata.

> Is it possible to add, for example, a method provideMetadata (for the sender)
> and a method acceptMetadata (for the receiver) to get more flexibility?
> These methods should be able to transfer an RDF/XML string...

I don't quite understand what you're after here. You want to send more than one batch of metadata alongside a file transfer? Could you explain the use case here a little more? As it is, the sender provides metadata when they create the FT channel, and the recipient receives it when they receive the offer. Is this insufficient?

(In reply to comment #4)
> (In reply to comment #3)
> > I think that a handler should be able to set/add more metadata when it receives
> > a channel already created. Also it would be much more useful if metadata could
> > be sent as "triples" (e.g. to transfer RDF metadata)
> 
> By a similar token, some people might want to send XML metadata, or JSON, or
> whatever. They're all equally well-supported by just bunging a string into the
> dictionary of metadata.

It could be argued that a{ss} is overly restrictive for the metadata parameter, and we could support more types for the values (cf. http://telepathy.freedesktop.org/spec/Channel_Interface_Tube.html#Property:Parameters). But…

(In reply to comment #4)
> (In reply to comment #3)
> > Is it possible to add, for example, a method provideMetadata (for the sender)
> > and a method acceptMetadata (for the receiver) to get more flexibility?
> > These methods should be able to transfer an RDF/XML string...
> 
> I don't quite understand what you're after here. You want to send more than one
> batch of metadata alongside a file transfer? Could you explain the use case
> here a little more? As it is, the sender provides metadata when they create the
> FT channel, and the recipient receives it when they receive the offer. Is this
> insufficient?

My use case is this:

In kde-telepathy we want to transfer metadata that we get from nepomuk together with the file, but we want to keep as simple as possible sending a file from a program, therefore the program should just choose the file and the target.
The handler is then started and it should check the services supported by the other side and eventually, if "nepomuk metadata" are supported, add metadata to the file transfer.

The metadata is stored in triples that can be related to the file (i.e. "Filename" "Author is" "John") but also not related direcly to the file (i.e. "John" "email address is" "john@foo.com)
We want to be able to choose which metadata is transferred or to avoid sending them to someone from some external configuration dialog. Moreover nepomuk could be disabled and in this case no metadata should be sent.
Including this into a library is in my opinion redundant (we want to link directly to Telepathy-Qt4), and therefore it should be handled by the handler once it receives the channel.

Our plan (that I also started to implement) was to add a stream tube service and when the handler receives a file transfer channel and the state changes to accepted, if the other side supports that service, open a streamtube, transfer the metadata and when the channel is closed send the real file.
Since you are implementing this interface, I think that something like this could be supported directly by telepathy...

(In reply to comment #6)
> Since you are implementing this interface, I think that something like this
> could be supported directly by telepathy...

Jonny and I spoke about this in real life about this. There are basically four parts of your use case:

• Discover whether the other person supports Nepomuk metadata:

  This is possible with this API: you make the Handler accept a channel class
  specifying ServiceName: org.kde.telepathy in it, and this will show up in
  ContactCapabilities on the other side.

  So:
    HandlerChannelFilters = [
  
    { org.fd.T.Channel.ChannelType: FileTransfer,
  
      org.fd.T.C.TargetHandleType: Contact,
       },
       { org.fd.T.Channel.ChannelType: FileTransfer,
         org.fd.T.C.TargetHandleType: Contact,
         org.fd.T.Channel.Interface.FTMetadata.ServiceName: 'org.kde.telepathy',
       },
    ]

• Allow the handler to set the metadata, not the offerer: unfortunately this
  isn't really possible with the current API. The file offer is sent to the
  peer the moment the channel is requested, and the API doesn't allow it
  to be sent later. (I argued extensively for this behaviour, and I think I was
  wrong.) The same problem exists for the hash: the requester has to
  hash the file even if some other process is gonna send it… something to be
  fixed in a future Telepathy.

• Include arbitrary metadata with the file offer: this API does support that,
  but…


• Specifically sending triples: well, supporting arbitrarily-typed metadata is
  not that easy. a{ss} has a pretty obvious representation in XMPP. To send
  triples, we'd have to support a(sss) as well… and then it's not that clear
  what to do on the wire.

  a{ss}—or potentially even a{sas}—maps really easily to data forms.

  With the currently-suggested API, KDE-Telepathy could send
      { "nepomuk-metadata":
          "stringified representation of the triples",
      }.

  If we used a{sas} rather than a{ss} then it could be
      { "nepomuk-metadata":
          ["filename", "author is", "john",
           "john", "email address is", "john@foo.com",
          ]
      }
  (that is, flattening the list of n triples into a list of 3n strings, which
  lets the data retain *some* structure, if not all of it). or:

      { "nepomuk-1": ["filename", "author is", "john"],
        "nepomuk-2": ["john", "email address is", "john@foo.com"],
      }

  It has to be a dictionary because data forms are essentially a{sas} dictionaries.

I think it would be good in any case to make Metadata be a{sas}. Since the on-the-wire representation, data forms, are basically that already, using that would allow applications a smidge more structure. I think this is the only structural complaint I have about this interface (other than acknowledging that it's potentially onerous that only the requester can provide the metadata (and hash)).

(I have updated my branch to have Metadata as an a(sas) now. HTML in the same place.)

(In reply to comment #8)
> a(sas)

a{sas}

I merged this.