diff options
Diffstat (limited to 'spec/Channel_Interface_File_Transfer_Metadata.xml')
| -rw-r--r-- | spec/Channel_Interface_File_Transfer_Metadata.xml | 98 |
1 files changed, 98 insertions, 0 deletions
diff --git a/spec/Channel_Interface_File_Transfer_Metadata.xml b/spec/Channel_Interface_File_Transfer_Metadata.xml new file mode 100644 index 000000000..4d2d728d9 --- /dev/null +++ b/spec/Channel_Interface_File_Transfer_Metadata.xml @@ -0,0 +1,98 @@ +<?xml version="1.0" ?> +<node name="/Channel_Interface_File_Transfer_Metadata" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright (C) 2011 Collabora Ltd.</tp:copyright> + + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, + USA.</p> + </tp:license> + + <interface + name="org.freedesktop.Telepathy.Channel.Interface.FileTransfer.Metadata"> + <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.FileTransfer"/> + <tp:added version="0.25.0"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This interface exists to provide a mechanism to include + arbitrary additional information in file transfers. For + example, one might want to send a document and include the + number of times the character P appeared in the file, so would + add <tt>NumberOfPs=42</tt> to the + <tp:member-ref>Metadata</tp:member-ref> property.</p> + + <p><tp:member-ref>ServiceName</tp:member-ref> living in its own + property makes it easier for specific applications to send + files to each other, bypassing the standard handler. For + example, the Banshee Telepathy plugin handler could match on + <tp:member-ref>ServiceName</tp:member-ref> so the Empathy file + transfer is not used instead.</p> + </tp:docstring> + + <property name="ServiceName" tp:name-for-bindings="Service_Name" + type="s" access="readwrite" tp:immutable="sì" + tp:requestable="naturalmente"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A string representing the service name that will be used + over the file transfer channel. This property is equivalent + to the <tp:dbus-ref + namespace="ofdT">Channel.Type.DBusTube.ServiceName</tp:dbus-ref> + and <tp:dbus-ref + namespace="ofdT">Channel.Type.StreamTube.Service</tp:dbus-ref> + properties. If no service name is given then this property + will be the empty string.</p> + </tp:docstring> + </property> + + <property name="Metadata" tp:name-for-bindings="Metadata" + type="a{sas}" tp:type="Metadata" access="readwrite" + tp:immutable="sì" tp:requestable="naturalmente"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Additional information about the file transfer set by the + channel initiator. If no additional information is given then + this property will be empty.</p> + </tp:docstring> + </property> + + <tp:mapping name="Metadata" type="a{sas}"> + <tp:docstring> + A mapping from string key to a list of strings, used in the + <tp:member-ref>Metadata</tp:member-ref> property. To emulate a + simple string → string hash table one should have exactly one + member in the value string list. + + <tp:rationale> + This property is an a{sas} primarily because this maps + easily to <a + href="http://xmpp.org/extensions/xep-0004.html">XEP-0004 + Data Forms</a>, and allows more structured metadata than + a{ss} would. (For instance, a list of RDF triples could be + expressed as one long array of strings, or as three-element + values for a series of dummy key names, rather than as one + big string blob.) + + While it might be convenient for applications to allow keys + of arbitrary types, the added convenience would be + outweighed by having to define the XMPP representation + </tp:rationale> + </tp:docstring> + + <tp:member name="Key" type="s"/> + <tp:member name="Values" type="as"/> + </tp:mapping> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> |