Added org.freedesktop.Telepathy.Channel.Type.File.DRAFT spec file. (Jonny Lamb)

Signed-off-by: Jonny Lamb <jonny.lamb@collabora.co.uk>

svn path=/trunk/; revision=1731

3 files changed, 401 insertions, 1 deletions

diff --git a/extensions/Channel_Type_File.xml b/extensions/Channel_Type_File.xml
new file mode 100644
index 000000000..1377a9b9e
--- /dev/null
+++ b/extensions/Channel_Type_File.xml
@@ -0,0 +1,398 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Type_File" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+  <tp:copyright>
+    Copyright (C) 2008 Collabora Limited
+  </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
+Library 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.Type.File.DRAFT"
+    tp:causes-havoc="experimental">
+    <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
+    <tp:docstring>
+      <p>A channel type for files offered for transferring.
+      The actual transmission of the data is done by reading or writing
+      a socket, the type of socket (local Unix, IPv4, etc.) when the File
+      channel is created.</p>
+
+      <p>The File channel type may be requested for handles of type
+      HANDLE_TYPE_CONTACT.</p>
+    </tp:docstring>
+
+    <property name="Direction" type="u" tp:type="File_Transfer_Direction"
+      access="read">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>The direction of the file transfer.</p>
+
+        <p>This property should become useless with the new request API.</p>
+      </tp:docstring>
+    </property>
+
+    <property name="State" type="u" tp:type="File_Transfer_State"
+      access="readwrite">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>The state of the file transfer as described by the
+        File_Transfer_State enum.</p>
+      </tp:docstring>
+    </property>
+
+    <property name="ContentType" type="s" access="readwrite">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>The file's MIME type. This cannot change once the channel has
+        been created.</p>
+
+        <p>This property is mandatory. Protocols which do not have a
+        content-type property with file transfers should set this value to
+        application/octet-stream.</p>
+      </tp:docstring>
+    </property>
+
+    <property name="Filename" type="s" access="readwrite">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>The name of the file on the sender's side. This is therefore given
+        as a suggested filename for the receiver. This cannot change
+        once the channel has been created.</p>
+
+        <p>If this property is an empty string, then its value is unspecified.</p>
+      </tp:docstring>
+    </property>
+
+    <property name="Size" type="t" access="readwrite">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>The size of the file. If this property is set, then the file
+        transfer is guaranteed to be this size. This cannot change once
+        the channel has been created.</p>
+
+        <p>If this property is UINT64_MAX, then its value is unspecified.</p>
+      </tp:docstring>
+    </property>
+
+    <property name="EstimatedSize" type="t" access="readwrite">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>An estimate of the size of the file. This property should be used
+        when the protocol doesn't allow exact file sizes (For example, accurate
+        to the nearest megabyte). This property should not be set if the Size
+        property can, or has, been set. This cannot change once the channel
+        has been created.</p>
+
+        <p>If this property is UINT64_MAX, then its value is unspecified.</p>
+      </tp:docstring>
+    </property>
+
+    <property name="ContentMD5" type="s" access="readwrite">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>MD5 digest of the file as a string of 32 ASCII hex digits, which
+        SHOULD be lower-case if they are letters. This cannot change once
+        the channel has been created.</p>
+
+        <p>If this property is an empty string, then its value is unspecified.</p>
+      </tp:docstring>
+    </property>
+
+    <property name="Description" type="s" access="readwrite">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Description of the file transfer. This cannot change once the
+        channel has been created.</p>
+
+        <p>If this property is an empty string, then its value is unspecified.</p>
+      </tp:docstring>
+    </property>
+
+    <property name="AvailableSocketTypes" type="a{uau}"
+      tp:type="Supported_Socket_Map" access="read">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>A mapping from address types (members of Socket_Address_Type) to
+        arrays of access-control type (members of Socket_Access_Control)
+        that the connection manager supports for sockets with that
+        address type. For simplicity, if a CM supports offering a
+        particular type of file transfer, it is assumed to support accepting
+        it.</p>
+
+        <p>A typical value for a host that supports only Unix sockets:</p>
+
+        <pre>
+          {
+            Socket_Address_Type_Unix:
+              [Socket_Access_Control_Localhost, Socket_Access_Control_Credentials]
+            Socket_Address_Type_Abstract_Unix:
+              [Socket_Access_Control_Localhost, Socket_Access_Control_Credentials]
+          }
+        </pre>
+      </tp:docstring>
+    </property>
+
+    <property name="TransferredBytes" type="t" access="read">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>The number of bytes that have been transferred at the time of
+        requesting the property. This will be updated as the file transfer
+        continues.</p>
+      </tp:docstring>
+    </property>
+
+    <property name="SocketPath" type="s" access="readwrite">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Path to the UNIX socket in use.</p>
+
+        <p>If this is an empty string, its value is undefined.</p>
+      </tp:docstring>
+    </property>
+
+    <tp:enum name="File_Transfer_Direction">
+      <tp:enumvalue suffix="Incoming" value="0">
+        <tp:docstring>
+          The file transfer is incoming.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Outgoing" value="1">
+        <tp:docstring>
+          The file transfer is outgoing.
+        </tp:docstring>
+      </tp:enumvalue>
+    </tp:enum>
+
+    <tp:enum name="File_Transfer_State">
+      <tp:enumvalue suffix="Local_Pending" value="0">
+        <tp:docstring>
+          The file transfer is waiting to be accepted/closed locally.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Remote_Pending" value="1">
+        <tp:docstring>
+          The file transfer is waiting to be accepted/closed remotely.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Open" value="2">
+        <tp:docstring>
+          The file transfer is open for traffic.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Completed" value="3">
+        <tp:docstring>
+          The file transfer has been completed successfully.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Canceled" value="4">
+        <tp:docstring>
+          The file transfer has been canceled.
+        </tp:docstring>
+      </tp:enumvalue>
+    </tp:enum>
+
+    <tp:enum name="File_Transfer_State_Change_Reason">
+      <tp:enumvalue suffix="None" value="0">
+        <tp:docstring>
+          No reason was specified.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Local_Stopped" value="1">
+        <tp:docstring>
+          The file transfer was canceled by the local user.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Remote_Stopped" value="2">
+        <tp:docstring>
+          The file transfer was canceled by the remote user.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Local_Error" value="3">
+        <tp:docstring>
+          The file transfer was canceled because of a local error.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Remote_Error" value="4">
+        <tp:docstring>
+          The file transfer was canceled because of a remote error.
+        </tp:docstring>
+      </tp:enumvalue>
+    </tp:enum>
+
+    <!-- Taken from org.freedesktop.Telepathy.Channel.Type.Tubes -->
+    <tp:enum name="Socket_Address_Type" type="u">
+      <tp:enumvalue suffix="Unix" value="0">
+        <tp:docstring>
+          A Unix socket. The variant contains a byte-array, signature 'ay',
+          containing the path of the socket.
+        </tp:docstring>
+      </tp:enumvalue>
+
+      <tp:enumvalue suffix="Abstract_Unix" value="1">
+        <tp:docstring>
+          An abstract Unix socket. The variant contains a byte-array,
+          signature 'ay', containing the path of the socket including the
+          leading null byte.
+        </tp:docstring>
+      </tp:enumvalue>
+
+      <tp:enumvalue suffix="IPv4" value="2">
+        <tp:docstring>
+          An IPv4 socket. The variant contains a Socket_Address_IPv4,
+          i.e. a structure with signature (sq)
+          in which the string is an IPv4 dotted-quad address literal
+          (and must not be a DNS name), while the 16-bit unsigned integer is
+          the port number.
+        </tp:docstring>
+      </tp:enumvalue>
+
+      <tp:enumvalue suffix="IPv6" value="3">
+        <tp:docstring>
+          An IPv6 socket. The variant contains a Socket_Address_IPv6,
+          i.e. a structure with signature (sq)
+          in which the string is an IPv6 address literal as specified in
+          RFC2373 (and must not be a DNS name), while the 16-bit unsigned
+          integer is the port number.
+        </tp:docstring>
+      </tp:enumvalue>
+
+    </tp:enum>
+
+    <!-- Taken from org.freedesktop.Telepathy.Channel.Type.Tubes -->
+    <tp:enum name="Socket_Access_Control" type="u">
+      <tp:enumvalue suffix="Localhost" value="0">
+        <tp:docstring>
+          The IP or Unix socket can be accessed by any local user (e.g.
+          a Unix socket that accepts all local connections, or an IP socket
+          listening on 127.0.0.1 (or ::1) or rejecting connections not from
+          that address). The associated variant must be ignored.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Port" value="1">
+        <tp:docstring>
+          May only be used on IP sockets. The associated variant must contain
+          a struct Socket_Address_IPv4 (or Socket_Address_IPv6)
+          containing the string form of an IP address of the appropriate
+          version, and a port number. The socket can only be accessed if the
+          connecting process has that address and port number; all other
+          connections will be rejected.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Netmask" value="2">
+        <tp:docstring>
+          May only be used on IP sockets. The associated variant must contain
+          a struct Socket_Netmask_IPv4 (or Socket_Netmask_IPv6) with
+          signature (sy), containing the string form of an
+          IP address of the appropriate version, and a prefix length "n".
+          The socket can only be accessed if the first n bits of the
+          connecting address match the first n bits of the given address.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Credentials" value="3">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>The connecting process must send a single zero (NUL) byte when
+            it first connects, which is not considered to be part of the data
+            stream. If the operating system uses sendmsg() with SCM_CREDS or
+            SCM_CREDENTIALS to pass credentials over sockets, the connecting
+            process must do so if possible; if not, it must still send the
+            byte.</p>
+
+          <p>The listening process will disconnect the connection unless it
+            can determine by OS-specific means that the connecting process
+            has the same user ID as the listening process.</p>
+
+          <p>The associated variant must be ignored.</p>
+        </tp:docstring>
+      </tp:enumvalue>
+    </tp:enum>
+
+    <!-- Taken from org.freedesktop.Telepathy.Channel.Type.Tubes -->
+    <tp:mapping name="Supported_Socket_Map">
+      <tp:docstring>The supported socket address and access-control types
+        for tubes. See GetAvailableStreamTubeTypes.</tp:docstring>
+      <tp:member name="Address_Type" type="u" tp:type="Socket_Address_Type"/>
+      <tp:member name="Access_Control" type="au"
+        tp:type="Socket_Access_Control[]"/>
+    </tp:mapping>
+
+    <method name="AcceptFile">
+      <tp:docstring>
+        Accept a file transfer that's in the "local pending" state. The file 
+        transfer becomes open after this method is called.
+      </tp:docstring>
+      <arg direction="in" name="address_type" type="u" tp:type="Socket_Address_Type">
+        <tp:docstring>
+          The type of address the connection manager should listen on.
+        </tp:docstring>
+      </arg>
+      <arg direction="in" name="access_control" type="u" tp:type="Socket_Access_Control">
+        <tp:docstring>
+          The type of access control the connection manager should apply to
+          the socket.
+        </tp:docstring>
+      </arg>
+      <arg direction="in" name="access_control_param" type="v">
+        <tp:docstring>
+          A parameter for the access control type, to be interpreted as
+          specified in the documentation for the Socket_Access_Control enum.
+        </tp:docstring>
+      </arg>
+      <arg direction="out" name="address" type="v">
+        <tp:docstring>
+          The address on which the connection manager will listen for
+          connections for this file transfer.
+        </tp:docstring>
+      </arg>
+
+      <tp:possible-errors>
+        <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+          <tp:docstring>
+            The given address type or access-control mechanism is not supported.
+          </tp:docstring>
+        </tp:error>
+        <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+          <tp:docstring>
+          The file transfer is not in the "local pending" state, which is the only
+          state this method makes sense.
+          </tp:docstring>
+        </tp:error>
+      </tp:possible-errors>
+    </method>
+
+    <signal name="FileTransferStateChanged">
+      <tp:docstring>
+        Emitted when the state of a file transfer changes.
+      </tp:docstring>
+      <arg name="state" type="u" tp:type="File_Transfer_State">
+        <tp:docstring>
+          The new state of the file transfer; see the File_Transfer_State enumeration.
+        </tp:docstring>
+      </arg>
+      <arg name="reason" type="u" tp:type="File_Transfer_State_Change_Reason">
+        <tp:docstring>
+          The reason for the state change; see the File_Transfer_State_Change_Reason
+          enumeration.
+          The value will always be File_Transfer_State_Change_Reason_None, except
+          when changing state to canceled.
+        </tp:docstring>
+      </arg>
+    </signal>
+
+    <signal name="TransferredBytesChanged">
+      <tp:docstring>
+        Emitted when the number of transferred bytes changes. This will not change
+        with every single byte change. Instead, the most frequent this signal will
+        be emmitted is once a second. This should be sufficient, and the
+        TransferredBytes property should not be polled.
+      </tp:docstring>
+      <arg name="count" type="t">
+        <tp:docstring>
+          The number of already transferred bytes.
+        </tp:docstring>
+      </arg>
+    </signal>
+  </interface>
+
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/extensions/Makefile.am b/extensions/Makefile.am
index 72ae28aec..d4cee5c8f 100644
--- a/extensions/Makefile.am
+++ b/extensions/Makefile.am
@@ -11,7 +11,8 @@ EXTRA_DIST = \
     misc.xml \
     Channel_Handler.xml \
     Stream_Engine.xml \
-    Tube_Handler.xml
+    Tube_Handler.xml \
+    Channel_Type_File.xml
 
 noinst_LTLIBRARIES = libemp-extensions.la
 
diff --git a/extensions/misc.xml b/extensions/misc.xml
index 72d3a4124..40eccde1f 100644
--- a/extensions/misc.xml
+++ b/extensions/misc.xml
@@ -7,5 +7,6 @@
 <xi:include href="Stream_Engine.xml"/>
 <xi:include href="Channel_Handler.xml"/>
 <xi:include href="Tube_Handler.xml"/>
+<xi:include href="Channel_Type_File.xml"/>
 
 </tp:spec>