extensions/Channel_Type_File_Transfer.xml

   1 <?xml version="1.0" ?>
   2 <node name="/Channel_Type_File_Transfer" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
   3   <tp:copyright>
   4     Copyright (C) 2008 Collabora Limited
   5   </tp:copyright>
   6   <tp:license xmlns="http://www.w3.org/1999/xhtml">
   7     <p>This library is free software; you can redistribute it and/or
   8 modify it under the terms of the GNU Lesser General Public
   9 License as published by the Free Software Foundation; either
  10 version 2.1 of the License, or (at your option) any later version.</p>
  11
  12 <p>This library is distributed in the hope that it will be useful,
  13 but WITHOUT ANY WARRANTY; without even the implied warranty of
  14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15 Library General Public License for more details.</p>
  16
  17 <p>You should have received a copy of the GNU Lesser General Public
  18 License along with this library; if not, write to the Free Software
  19 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
  20   </tp:license>
  21   <interface name="org.freedesktop.Telepathy.Channel.Type.FileTransfer.DRAFT"
  22     tp:causes-havoc="experimental">
  23     <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
  24     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  25       <p>A channel type for files offered for transferring. The
  26       transmission of data between contacts is achieved by reading from
  27       or writing to a socket. The type of the socket (local Unix, IPv4,
  28       etc.) is decided on when the file transfer is offered or accepted.</p>
  29
  30       <p>The Telepathy client should connect to the socket or address that
  31       the connection manager has set up and provided back to the clients
  32       through the two methods.</p>
  33
  34       <ul><li>In order to send a file, one should request a FileTransfer
  35       channel for a contact, and fill the mandatory properties
  36       (<tp:member-ref>Filename</tp:member-ref>, and
  37       <tp:member-ref>Size</tp:member-ref>). After these are set, one should
  38       call <tp:member-ref>OfferFile</tp:member-ref> to offer the transfer to
  39       the contact.</li>
  40
  41       <li>In order to receive an incoming file transfer, one should call
  42       <tp:member-ref>AcceptFile</tp:member-ref> and then wait until the state
  43       changes to Open. If the receiver is resuming a transfer then he or she
  44       should set a non-zero Offset argument when calling
  45       <tp:member-ref>AcceptFile</tp:member-ref>. When the state changes to Open,
  46       the receiver must check the <tp:member-ref>InitialOffset</tp:member-ref>
  47       property for a difference in offset from the requested value in
  48       AcceptFile.</li></ul>
  49
  50       <p>If something goes wrong with the transfer,
  51       <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Close</tp:dbus-ref>
  52       should be called on the channel.</p>
  53
  54       <p>The File channel type may be requested for handles of type
  55       HANDLE_TYPE_CONTACT. If the channel is requested for any other
  56       handle type then the behaviour is undefined.</p>
  57     </tp:docstring>
  58
  59     <property name="State" type="u" tp:type="File_Transfer_State"
  60       access="read" tp:name-for-bindings="State">
  61       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  62         <p>The state of the file transfer as described by the
  63         File_Transfer_State enum.</p>
  64       </tp:docstring>
  65     </property>
  66
  67     <property name="ContentType" type="s" access="read"
  68       tp:name-for-bindings="Content_Type">
  69       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  70         <p>The file's MIME type. This cannot change once the channel has
  71         been created.</p>
  72
  73         <p>This property is mandatory when requesting the channel with the
  74         <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
  75         method. Protocols which do not have a content-type property with file
  76         transfers should set this value to application/octet-stream.</p>
  77       </tp:docstring>
  78     </property>
  79
  80     <property name="Filename" type="s" access="read"
  81       tp:name-for-bindings="Filename">
  82       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  83         <p>The name of the file on the sender's side. This is therefore given
  84         as a suggested filename for the receiver. This cannot change
  85         once the channel has been created.</p>
  86
  87         <p>This property should be the basename of the file being sent. For example,
  88         if the sender sends the file /home/user/monkey.pdf then this property should
  89         be set to monkey.pdf.</p>
  90
  91         <p>This property is mandatory when requesting the channel with the
  92         <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
  93         method. This property cannot be empty and must be set to a sensible value.</p>
  94       </tp:docstring>
  95     </property>
  96
  97     <property name="Size" type="t" access="read"
  98       tp:name-for-bindings="Size">
  99       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 100         <p>The size of the file. If this property is set, then the file
 101         transfer is guaranteed to be this size. This cannot change once
 102         the channel has been created.</p>
 103
 104         <p>When you are creating a channel with this property, its value
 105         MUST be accurate and in bytes. However, when receiving a file, this
 106         property still must be in bytes but might not be entirely accurate
 107         to the byte.</p>
 108
 109         <p>This property is mandatory when requesting the channel with the
 110         <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
 111         method. If this property is UINT64_MAX, then its value is
 112         unspecified.</p>
 113       </tp:docstring>
 114     </property>
 115
 116     <property name="ContentHashType" type="u" tp:type="File_Hash_Type"
 117       access="read" tp:name-for-bindings="Content_Hash_Type">
 118       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 119         <p>The type of the <tp:member-ref>ContentHash</tp:member-ref> property.</p>
 120
 121         <p>This property is optional when requesting the channel with the
 122         <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
 123         method. However, if you wish to include the <tp:member-ref>ContentHash</tp:member-ref>
 124         property you MUST also include this property. If you omit this property from a
 125         <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
 126         method call then its value will be assumed to be File_Hash_Type_None.</p>
 127       </tp:docstring>
 128     </property>
 129
 130     <property name="ContentHash" type="s" access="read"
 131       tp:name-for-bindings="Content_Hash">
 132       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 133         <p>Hash of the contents of the file transfer, of type described
 134         in the value of the <tp:member-ref>ContentHashType</tp:member-ref>
 135         property.</p>
 136
 137         <p>This property is optional when requesting the channel with the
 138         <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
 139         method. Its value MUST correspond to the appropriate type of the
 140         <tp:member-ref>ContentHashType</tp:member-ref> property. If the
 141         ContentHashType property is not set, or set to File_Hash_Type_None,
 142         then this property will not even be looked at.</p>
 143       </tp:docstring>
 144     </property>
 145
 146     <property name="Description" type="s" access="read"
 147       tp:name-for-bindings="Description">
 148       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 149         <p>Description of the file transfer. This cannot change once the
 150         channel has been created.</p>
 151
 152         <p>This property is optional when requesting the channel with the
 153         <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
 154         method. If this property is an empty string, then its value is
 155         unspecified.</p>
 156       </tp:docstring>
 157     </property>
 158
 159     <property name="Date" type="t" access="read"
 160       tp:type="Unix_Timestamp64" tp:name-for-bindings="Date">
 161       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 162         <p>The last modification time of the file being transferred. This
 163         cannot change once the channel has been created</p>
 164
 165         <p>This property is optional when requesting the channel with the
 166         <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
 167         method.</p>
 168       </tp:docstring>
 169     </property>
 170
 171     <property name="AvailableSocketTypes" type="a{uau}"
 172       tp:type="Supported_Socket_Map" access="read"
 173       tp:name-for-bindings="Available_Socket_Types">
 174       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 175         <p>A mapping from address types (members of Socket_Address_Type) to
 176         arrays of access-control type (members of Socket_Access_Control)
 177         that the connection manager supports for sockets with that
 178         address type. For simplicity, if a CM supports offering a
 179         particular type of file transfer, it is assumed to support accepting
 180         it.</p>
 181
 182         <p>A typical value for a host that supports only Unix sockets:</p>
 183
 184         <pre>
 185           {
 186             Socket_Address_Type_Unix:
 187               [Socket_Access_Control_Localhost, Socket_Access_Control_Credentials]
 188             Socket_Address_Type_Abstract_Unix:
 189               [Socket_Access_Control_Localhost, Socket_Access_Control_Credentials]
 190           }
 191         </pre>
 192       </tp:docstring>
 193     </property>
 194
 195     <property name="TransferredBytes" type="t" access="read"
 196       tp:name-for-bindings="Transferred_Bytes">
 197       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 198         <p>The number of bytes that have been transferred at the time of
 199         requesting the property. This will be updated as the file transfer
 200         continues.</p>
 201       </tp:docstring>
 202     </property>
 203
 204     <property name="InitialOffset" type="t" access="read"
 205       tp:name-for-bindings="Initial_Offset">
 206       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 207         <p>The offset in bytes from where the file should be sent. This MUST
 208         be checked by both the receiver and the sender after the state
 209         becomes Open, but before any data is sent or received. Until the
 210         state changes to Open, this property is undefined.</p>
 211
 212         <p>Before setting the <tp:member-ref>State</tp:member-ref> property to
 213         Open, the connection manager MUST set the InitialOffset property,
 214         possibly to 0.</p>
 215
 216         <p>This property MUST NOT change after the state of the transfer has
 217         changed to Open.</p>
 218       </tp:docstring>
 219     </property>
 220
 221     <tp:enum name="File_Transfer_State" type="u">
 222       <tp:enumvalue suffix="None" value="0">
 223         <tp:docstring>
 224           An invalid state type used as a null value. This value MUST NOT
 225           appear in the State property.
 226         </tp:docstring>
 227       </tp:enumvalue>
 228       <tp:enumvalue suffix="Not_Offered" value="1">
 229         <tp:docstring>
 230           The transfer is waiting for the local client to call the OfferFile
 231           method, in order to offer a file to be transferred.
 232         </tp:docstring>
 233       </tp:enumvalue>
 234       <tp:enumvalue suffix="Accepted" value="2">
 235         <tp:docstring>
 236           The client has accepted the incoming file transfer, but the transfer
 237           is not open. The client should now wait for the state to change to Open
 238           and check the offset value.
 239         </tp:docstring>
 240       </tp:enumvalue>
 241       <tp:enumvalue suffix="Local_Pending" value="3">
 242         <tp:docstring>
 243           The file transfer is waiting to be accepted/closed locally.
 244         </tp:docstring>
 245       </tp:enumvalue>
 246       <tp:enumvalue suffix="Remote_Pending" value="4">
 247         <tp:docstring>
 248           The file transfer is waiting to be accepted/closed remotely.
 249         </tp:docstring>
 250       </tp:enumvalue>
 251       <tp:enumvalue suffix="Open" value="5">
 252         <tp:docstring>
 253           The file transfer is open for traffic.
 254         </tp:docstring>
 255       </tp:enumvalue>
 256       <tp:enumvalue suffix="Completed" value="6">
 257         <tp:docstring>
 258           The file transfer has been completed successfully.
 259         </tp:docstring>
 260       </tp:enumvalue>
 261       <tp:enumvalue suffix="Cancelled" value="7">
 262         <tp:docstring>
 263           The file transfer has been cancelled.
 264         </tp:docstring>
 265       </tp:enumvalue>
 266     </tp:enum>
 267
 268     <tp:enum name="File_Transfer_State_Change_Reason" type="u">
 269       <tp:enumvalue suffix="None" value="0">
 270         <tp:docstring>
 271           No reason was specified.
 272         </tp:docstring>
 273       </tp:enumvalue>
 274       <tp:enumvalue suffix="Requested" value="1">
 275         <tp:docstring>
 276           The change in state was requested.
 277         </tp:docstring>
 278       </tp:enumvalue>
 279       <tp:enumvalue suffix="Local_Stopped" value="1">
 280         <tp:docstring>
 281           The file transfer was cancelled by the local user.
 282         </tp:docstring>
 283       </tp:enumvalue>
 284       <tp:enumvalue suffix="Remote_Stopped" value="2">
 285         <tp:docstring>
 286           The file transfer was cancelled by the remote user.
 287         </tp:docstring>
 288       </tp:enumvalue>
 289       <tp:enumvalue suffix="Local_Error" value="3">
 290         <tp:docstring>
 291           The file transfer was cancelled because of a local error.
 292         </tp:docstring>
 293       </tp:enumvalue>
 294       <tp:enumvalue suffix="Remote_Error" value="4">
 295         <tp:docstring>
 296           The file transfer was cancelled because of a remote error.
 297         </tp:docstring>
 298       </tp:enumvalue>
 299     </tp:enum>
 300
 301     <tp:enum name="File_Hash_Type" type="u">
 302       <tp:enumvalue suffix="None" value="0">
 303         <tp:docstring>
 304           No hash.
 305         </tp:docstring>
 306       </tp:enumvalue>
 307       <tp:enumvalue suffix="MD5" value="1">
 308         <tp:docstring>
 309           MD5 digest as a string of 32 ASCII hex digits.
 310         </tp:docstring>
 311       </tp:enumvalue>
 312       <tp:enumvalue suffix="SHA1" value="2">
 313         <tp:docstring>
 314           SHA1 digest as a string of ASCII hex digits.
 315         </tp:docstring>
 316       </tp:enumvalue>
 317       <tp:enumvalue suffix="SHA256" value="3">
 318         <tp:docstring>
 319           SHA256 digest as a string of ASCII hex digits.
 320         </tp:docstring>
 321       </tp:enumvalue>
 322     </tp:enum>
 323
 324     <method name="AcceptFile" tp:name-for-bindings="Accept_File">
 325       <tp:docstring>
 326         Accept a file transfer that's in the Local_Pending state. The file
 327         transfer's state becomes Accepted after this method is called. At this
 328         point, the receiver must wait for the state to change to Open, and then
 329         <tp:member-ref>InitialOffset</tp:member-ref> should be checked in case
 330         its value differs from the offset that was specified as an argument
 331         to AcceptFile.
 332       </tp:docstring>
 333       <arg direction="in" name="Address_Type" type="u" tp:type="Socket_Address_Type">
 334         <tp:docstring>
 335           The type of address the connection manager should listen on.
 336         </tp:docstring>
 337       </arg>
 338       <arg direction="in" name="Access_Control" type="u" tp:type="Socket_Access_Control">
 339         <tp:docstring>
 340           The type of access control the connection manager should apply to
 341           the socket.
 342         </tp:docstring>
 343       </arg>
 344       <arg direction="in" name="Access_Control_Param" type="v">
 345         <tp:docstring>
 346           A parameter for the access control type, to be interpreted as
 347           specified in the documentation for the Socket_Access_Control enum.
 348         </tp:docstring>
 349       </arg>
 350       <arg direction="in" name="Offset" type="t">
 351         <tp:docstring>
 352           The desired offset in bytes where the file transfer should start.
 353           The offset is taken from the beginning of the file. Specifying an
 354           offset of zero will start the transfer from the beginning of the
 355           file. The offset that is actually given in the
 356           <tp:member-ref>InitialOffset</tp:member-ref> property can differ
 357           from this argument where the requested offset is not supported.
 358           (For example, some protocols do not support offsets at all so
 359           the InitialOffset property will always be 0.)
 360         </tp:docstring>
 361       </arg>
 362       <arg direction="out" name="Address" type="v">
 363         <tp:docstring>
 364           The address on which the connection manager will listen for
 365           connections for this file transfer.
 366         </tp:docstring>
 367       </arg>
 368
 369       <tp:possible-errors>
 370         <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
 371           <tp:docstring>
 372             The given address type or access-control mechanism is not supported.
 373           </tp:docstring>
 374         </tp:error>
 375         <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
 376         <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/>
 377           <tp:docstring>
 378             Your address type, access control, access control parameter,
 379             offset, or a combination of all four is invalid.
 380           </tp:docstring>
 381         <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
 382           <tp:docstring>
 383             The file transfer is not in the Local_Pending state, there isn't
 384             or there is a local error with acquiring a socket.
 385           </tp:docstring>
 386         </tp:error>
 387       </tp:possible-errors>
 388     </method>
 389
 390     <method name="OfferFile" tp:name-for-bindings="Offer_File">
 391       <tp:docstring>
 392         Offer a file transfer that's in the Not_Offered state. Open a socket
 393         that the client can use to provide a file to the connection manager.
 394         The channel MUST be in the Not_Offered state, and will change state
 395         to Remote_Pending when this method is called.
 396       </tp:docstring>
 397       <arg direction="in" name="Address_Type" type="u" tp:type="Socket_Address_Type">
 398         <tp:docstring>
 399           The type of address the connection manager should listen on.
 400         </tp:docstring>
 401       </arg>
 402       <arg direction="in" name="Access_Control" type="u" tp:type="Socket_Access_Control">
 403         <tp:docstring>
 404           The type of access control the connection manager should apply to
 405           the socket.
 406         </tp:docstring>
 407       </arg>
 408       <arg direction="in" name="Access_Control_Param" type="v">
 409         <tp:docstring>
 410           A parameter for the access control type, to be interpreted as
 411           specified in the documentation for the Socket_Access_Control enum.
 412         </tp:docstring>
 413       </arg>
 414       <arg direction="out" name="Address" type="v">
 415         <tp:docstring>
 416           The address on which the connection manager will listen for
 417           connections for this file transfer.
 418         </tp:docstring>
 419       </arg>
 420
 421       <tp:possible-errors>
 422         <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
 423           <tp:docstring>
 424             The given address type or access-control mechanism is not supported.
 425           </tp:docstring>
 426         </tp:error>
 427         <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/>
 428           <tp:docstring>
 429             Your address type, access control, access control parameter, or
 430             a combination of all three is invalid.
 431           </tp:docstring>
 432         <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
 433           <tp:docstring>
 434             The file transfer is not in the Not_Offered state, there isn't
 435             enough information for the transfer to start, or a local error
 436             with acquiring a socket.
 437           </tp:docstring>
 438         </tp:error>
 439       </tp:possible-errors>
 440     </method>
 441
 442     <signal name="FileTransferStateChanged"
 443       tp:name-for-bindings="File_Transfer_State_Changed">
 444       <tp:docstring>
 445         Emitted when the state of a file transfer changes.
 446       </tp:docstring>
 447       <arg name="State" type="u" tp:type="File_Transfer_State">
 448         <tp:docstring>
 449           The new state of the file transfer; see the File_Transfer_State enumeration.
 450         </tp:docstring>
 451       </arg>
 452       <arg name="Reason" type="u" tp:type="File_Transfer_State_Change_Reason">
 453         <tp:docstring>
 454           The reason for the state change; see the File_Transfer_State_Change_Reason
 455           enumeration.
 456           The value will always be File_Transfer_State_Change_Reason_None, except
 457           when changing state to cancelled.
 458         </tp:docstring>
 459       </arg>
 460     </signal>
 461
 462     <signal name="TransferredBytesChanged"
 463       tp:name-for-bindings="Transferred_Bytes_Changed">
 464       <tp:docstring>
 465         Emitted when the number of transferred bytes changes. This will not be
 466         signalled with every single byte change. Instead, the most frequent
 467         this signal will be emitted is once a second. This should be
 468         sufficient, and the <tp:member-ref>TransferredBytes</tp:member-ref>
 469         property SHOULD NOT be polled.
 470       </tp:docstring>
 471       <arg name="Count" type="t">
 472         <tp:docstring>
 473           The number of already transferred bytes.
 474         </tp:docstring>
 475       </arg>
 476     </signal>
 477   </interface>
 478
 479 </node>
 480 <!-- vim:set sw=2 sts=2 et ft=xml: -->