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>A socket approach is used to make the transfer less dependent on both
  31       client and connection manager knowing the same protocols. As an example,
  32       when browsing an SMB share in a file manager, one selects "Send file"
  33       and chooses a contact. Instead of passing a URL which would then require
  34       the connection manager to connect to the SMB share itself, the client
  35       passes a stream from which the connection manager reads, requiring no
  36       further connection to the share. It also allows connection managers to
  37       be more restricted in their access to the system, allowing tighter
  38       security policies with eg SElinux, or more flexible deployments which
  39       cross user or system boundaries.</p>
  40
  41       <p>If the connection manager relies on a library using file path only for
  42       file transfers, it can use the Socket_Address_Type_Local_Path
  43       <tp:type>Socket_Address_Type</tp:type>. In that case the file will be
  44       read and written directly by the CM.</p>
  45
  46       <p>The Telepathy client should connect to the socket or address that
  47       the connection manager has set up and provided back to the clients
  48       through the two methods.</p>
  49
  50       <ul><li>In order to send a file, one should request a FileTransfer
  51       channel for a contact, including at least the mandatory properties
  52       (<tp:member-ref>Filename</tp:member-ref>,
  53       <tp:member-ref>Size</tp:member-ref> and <tp:member-ref>ContentType</tp:member-ref>).
  54       Then, one should
  55       call <tp:member-ref>ProvideFile</tp:member-ref> to configure the socket that
  56       will be used to transfer the file.</li>
  57
  58       <li>In order to receive an incoming file transfer, one should call
  59       <tp:member-ref>AcceptFile</tp:member-ref> and then wait until the state
  60       changes to Open. When the receiver wants to resume a transfer, the Offset
  61       argument should be should be set to a non-zero value when calling
  62       <tp:member-ref>AcceptFile</tp:member-ref>.</li>
  63
  64     <li>Once the offset has been negotiated, the
  65       <tp:member-ref>InitialOffsetDefined</tp:member-ref> signal
  66       is emitted and the <tp:member-ref>InitialOffset</tp:member-ref> property
  67       is defined. The <tp:member-ref>InitialOffsetDefined</tp:member-ref>
  68       signal is emitted before channel becomes Open.
  69       The receiver MUST check the value of
  70       <tp:member-ref>InitialOffset</tp:member-ref> for a difference in offset
  71       from the requested value in AcceptFile.</li>
  72
  73       <li>When the state changes to Open, Clients can start the transfer of the
  74       file using the offset previously announced.
  75       </li></ul>
  76
  77       <p>If something goes wrong with the transfer,
  78       <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Close</tp:dbus-ref>
  79       should be called on the channel.</p>
  80
  81       <p>The File channel type may be requested for handles of type
  82       HANDLE_TYPE_CONTACT. If the channel is requested for any other
  83       handle type then the behaviour is undefined.</p>
  84     </tp:docstring>
  85
  86     <property name="State" type="u" tp:type="File_Transfer_State"
  87       access="read" tp:name-for-bindings="State">
  88       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  89         <p>The state of the file transfer as described by the
  90         File_Transfer_State enum.</p>
  91       </tp:docstring>
  92     </property>
  93
  94     <property name="ContentType" type="s" access="read"
  95       tp:name-for-bindings="Content_Type">
  96       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
  97         <p>The file's MIME type. This cannot change once the channel has
  98         been created.</p>
  99
 100         <p>This property is mandatory when requesting the channel with the
 101         <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
 102         method. Protocols which do not have a content-type property with file
 103         transfers should set this value to application/octet-stream.</p>
 104       </tp:docstring>
 105     </property>
 106
 107     <property name="Filename" type="s" access="read"
 108       tp:name-for-bindings="Filename">
 109       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 110         <p>The name of the file on the sender's side. This is therefore given
 111         as a suggested filename for the receiver. This cannot change
 112         once the channel has been created.</p>
 113
 114         <p>This property should be the basename of the file being sent. For example,
 115         if the sender sends the file /home/user/monkey.pdf then this property should
 116         be set to monkey.pdf.</p>
 117
 118         <p>This property is mandatory when requesting the channel with the
 119         <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
 120         method. This property cannot be empty and MUST be set to a sensible value.</p>
 121       </tp:docstring>
 122     </property>
 123
 124     <property name="Size" type="t" access="read"
 125       tp:name-for-bindings="Size">
 126       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 127         <p>The size of the file. If this property is set, then the file
 128         transfer is guaranteed to be this size. This cannot change once
 129         the channel has been created.</p>
 130
 131         <p>When you are creating a channel with this property, its value
 132         MUST be accurate and in bytes. However, when receiving a file, this
 133         property still MUST be in bytes but might not be entirely accurate
 134         to the byte.</p>
 135
 136         <p>This property is mandatory when requesting the channel with the
 137         <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
 138         method. If this information isn't provided in the protocol, connection managers MUST set it
 139         to UINT64_MAX.</p>
 140       </tp:docstring>
 141     </property>
 142
 143     <property name="ContentHashType" type="u" tp:type="File_Hash_Type"
 144       access="read" tp:name-for-bindings="Content_Hash_Type">
 145       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 146         <p>The type of the <tp:member-ref>ContentHash</tp:member-ref> property.</p>
 147
 148         <p>This property is optional when requesting the channel with the
 149         <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
 150         method. However, if you wish to include the <tp:member-ref>ContentHash</tp:member-ref>
 151         property you MUST also include this property. If you omit this property from a
 152         <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
 153         method call then its value will be assumed to be File_Hash_Type_None.</p>
 154       </tp:docstring>
 155     </property>
 156
 157     <property name="ContentHash" type="s" access="read"
 158       tp:name-for-bindings="Content_Hash">
 159       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 160         <p>Hash of the contents of the file transfer, of type described
 161         in the value of the <tp:member-ref>ContentHashType</tp:member-ref>
 162         property.</p>
 163
 164         <p>This property is optional when requesting the channel with the
 165         <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
 166         method. Its value MUST correspond to the appropriate type of the
 167         <tp:member-ref>ContentHashType</tp:member-ref> property. If the
 168         ContentHashType property is not set, or set to File_Hash_Type_None,
 169         then this property will not even be looked at.</p>
 170       </tp:docstring>
 171     </property>
 172
 173     <property name="Description" type="s" access="read"
 174       tp:name-for-bindings="Description">
 175       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 176         <p>Description of the file transfer. This cannot change once the
 177         channel has been created.</p>
 178
 179         <p>This property is optional when requesting the channel with the
 180         <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
 181         method. If this property was not provided by the remote party, connection managers MUST set it to
 182         the empty string.</p>
 183       </tp:docstring>
 184     </property>
 185
 186     <property name="Date" type="t" access="read"
 187       tp:type="Unix_Timestamp64" tp:name-for-bindings="Date">
 188       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 189         <p>The last modification time of the file being transferred. This
 190         cannot change once the channel has been created</p>
 191
 192         <p>This property is optional when requesting the channel with the
 193         <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
 194         method.</p>
 195       </tp:docstring>
 196     </property>
 197
 198     <property name="AvailableSocketTypes" type="a{uau}"
 199       tp:type="Supported_Socket_Map" access="read"
 200       tp:name-for-bindings="Available_Socket_Types">
 201       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 202         <p>A mapping from address types (members of Socket_Address_Type) to
 203         arrays of access-control type (members of Socket_Access_Control)
 204         that the connection manager supports for sockets with that
 205         address type. For simplicity, if a CM supports offering a
 206         particular type of file transfer, it is assumed to support accepting
 207         it.</p>
 208
 209         <p>A typical value for a host that supports only Unix sockets:</p>
 210
 211         <pre>
 212           {
 213             Socket_Address_Type_Unix:
 214               [Socket_Access_Control_Localhost, Socket_Access_Control_Credentials]
 215             Socket_Address_Type_Abstract_Unix:
 216               [Socket_Access_Control_Localhost, Socket_Access_Control_Credentials]
 217           }
 218         </pre>
 219       </tp:docstring>
 220     </property>
 221
 222     <property name="TransferredBytes" type="t" access="read"
 223       tp:name-for-bindings="Transferred_Bytes">
 224       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 225         <p>The number of bytes that have been transferred at the time of
 226         requesting the property. This will be updated as the file transfer
 227         continues.</p>
 228       </tp:docstring>
 229     </property>
 230
 231     <property name="InitialOffset" type="t" access="read"
 232       tp:name-for-bindings="Initial_Offset">
 233       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
 234         <p>The offset in bytes from where the file should be sent. This MUST
 235         be respected by both the receiver and the sender after the state
 236         becomes Open, but before any data is sent or received. Until the
 237         <tp:member-ref>InitialOffsetDefined</tp:member-ref> signal
 238         is emitted, this property is undefined.</p>
 239
 240         <p>Before setting the <tp:member-ref>State</tp:member-ref> property to
 241         Open, the connection manager MUST set the InitialOffset property,
 242         possibly to 0.</p>
 243
 244         <p>This property MUST NOT change after the state of the transfer has
 245         changed to Open.</p>
 246       </tp:docstring>
 247     </property>
 248
 249     <tp:enum name="File_Transfer_State" type="u">
 250       <tp:enumvalue suffix="None" value="0">
 251         <tp:docstring>
 252           An invalid state type used as a null value. This value MUST NOT
 253           appear in the State property.
 254         </tp:docstring>
 255       </tp:enumvalue>
 256       <tp:enumvalue suffix="Pending" value="1">
 257         <tp:docstring>
 258           The file transfer is waiting to be accepted/closed by the receiver.
 259           The receiver has to call <tp:member-ref>AcceptFile</tp:member-ref>,
 260           then wait for the state to change to Open and check the offset value.
 261         </tp:docstring>
 262       </tp:enumvalue>
 263       <tp:enumvalue suffix="Accepted" value="2">
 264         <tp:docstring>
 265           The receiver has accepted the transfer. The sender now has to
 266           call <tp:member-ref>ProvideFile</tp:member-ref> to actually start the transfer.
 267           The receiver should now wait for the state to change to Open
 268           and check the offset value.
 269         </tp:docstring>
 270       </tp:enumvalue>
 271       <tp:enumvalue suffix="Open" value="3">
 272         <tp:docstring>
 273           The file transfer is open for traffic.
 274         </tp:docstring>
 275       </tp:enumvalue>
 276       <tp:enumvalue suffix="Completed" value="4">
 277         <tp:docstring>
 278           The file transfer has been completed successfully.
 279         </tp:docstring>
 280       </tp:enumvalue>
 281       <tp:enumvalue suffix="Cancelled" value="5">
 282         <tp:docstring>
 283           The file transfer has been cancelled.
 284         </tp:docstring>
 285       </tp:enumvalue>
 286     </tp:enum>
 287
 288     <tp:enum name="File_Transfer_State_Change_Reason" type="u">
 289       <tp:enumvalue suffix="None" value="0">
 290         <tp:docstring>
 291           No reason was specified.
 292         </tp:docstring>
 293       </tp:enumvalue>
 294       <tp:enumvalue suffix="Requested" value="1">
 295         <tp:docstring>
 296           The change in state was requested.
 297         </tp:docstring>
 298       </tp:enumvalue>
 299       <tp:enumvalue suffix="Local_Stopped" value="2">
 300         <tp:docstring>
 301           The file transfer was cancelled by the local user.
 302         </tp:docstring>
 303       </tp:enumvalue>
 304       <tp:enumvalue suffix="Remote_Stopped" value="3">
 305         <tp:docstring>
 306           The file transfer was cancelled by the remote user.
 307         </tp:docstring>
 308       </tp:enumvalue>
 309       <tp:enumvalue suffix="Local_Error" value="4">
 310         <tp:docstring>
 311           The file transfer was cancelled because of a local error.
 312         </tp:docstring>
 313       </tp:enumvalue>
 314       <tp:enumvalue suffix="Remote_Error" value="5">
 315         <tp:docstring>
 316           The file transfer was cancelled because of a remote error.
 317         </tp:docstring>
 318       </tp:enumvalue>
 319     </tp:enum>
 320
 321     <tp:enum name="File_Hash_Type" type="u">
 322       <tp:enumvalue suffix="None" value="0">
 323         <tp:docstring>
 324           No hash.
 325         </tp:docstring>
 326       </tp:enumvalue>
 327       <tp:enumvalue suffix="MD5" value="1">
 328         <tp:docstring>
 329           MD5 digest as a string of 32 ASCII hex digits.
 330         </tp:docstring>
 331       </tp:enumvalue>
 332       <tp:enumvalue suffix="SHA1" value="2">
 333         <tp:docstring>
 334           SHA1 digest as a string of ASCII hex digits.
 335         </tp:docstring>
 336       </tp:enumvalue>
 337       <tp:enumvalue suffix="SHA256" value="3">
 338         <tp:docstring>
 339           SHA256 digest as a string of ASCII hex digits.
 340         </tp:docstring>
 341       </tp:enumvalue>
 342     </tp:enum>
 343
 344     <method name="AcceptFile" tp:name-for-bindings="Accept_File">
 345       <tp:docstring>
 346         Accept a file transfer that's in the Pending state. The file
 347         transfer's state becomes Accepted after this method is called.
 348         At this point the client can connect to the socket. CM MUST emit
 349         <tp:member-ref>InitialOffsetDefined</tp:member-ref> and change
 350         the state to Open before writing to the socket.
 351         Then <tp:member-ref>InitialOffset</tp:member-ref> should be respected in case
 352         its value differs from the offset that was specified as an argument
 353         to AcceptFile.
 354       </tp:docstring>
 355       <arg direction="in" name="Address_Type" type="u" tp:type="Socket_Address_Type">
 356         <tp:docstring>
 357           The type of address the connection manager should listen on.
 358         </tp:docstring>
 359       </arg>
 360       <arg direction="in" name="Access_Control" type="u" tp:type="Socket_Access_Control">
 361         <tp:docstring>
 362           The type of access control the connection manager should apply to
 363           the socket.
 364         </tp:docstring>
 365       </arg>
 366       <arg direction="in" name="Access_Control_Param" type="v">
 367         <tp:docstring>
 368           A parameter for the access control type, to be interpreted as
 369           specified in the documentation for the Socket_Access_Control enum.
 370         </tp:docstring>
 371       </arg>
 372       <arg direction="in" name="Offset" type="t">
 373         <tp:docstring>
 374           The desired offset in bytes where the file transfer should start.
 375           The offset is taken from the beginning of the file. Specifying an
 376           offset of zero will start the transfer from the beginning of the
 377           file. The offset that is actually given in the
 378           <tp:member-ref>InitialOffset</tp:member-ref> property can differ
 379           from this argument where the requested offset is not supported.
 380           (For example, some protocols do not support offsets at all so
 381           the InitialOffset property will always be 0.)
 382         </tp:docstring>
 383       </arg>
 384       <arg direction="out" name="Address" type="v">
 385         <tp:docstring>
 386           The address on which the connection manager will listen for
 387           connections for this file transfer.
 388         </tp:docstring>
 389       </arg>
 390
 391       <tp:possible-errors>
 392         <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
 393           <tp:docstring>
 394             The given address type or access-control mechanism is not supported.
 395           </tp:docstring>
 396         </tp:error>
 397         <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
 398         <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/>
 399           <tp:docstring>
 400             Your address type, access control, access control parameter,
 401             offset, or a combination of all four is invalid.
 402           </tp:docstring>
 403         <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
 404           <tp:docstring>
 405             The file transfer is not in the Pending state, there isn't
 406             or there is a local error with acquiring a socket.
 407           </tp:docstring>
 408         </tp:error>
 409       </tp:possible-errors>
 410     </method>
 411
 412     <method name="ProvideFile" tp:name-for-bindings="Provide_File">
 413       <tp:docstring>
 414         Provide the file for an outgoing file transfer which has been offered.
 415         Opens a socket that the client can use to provide a file to the connection manager.
 416         The channel MUST have been requested, and will change state
 417         to Open when this method is called if its state was Accepted.
 418       </tp:docstring>
 419       <arg direction="in" name="Address_Type" type="u" tp:type="Socket_Address_Type">
 420         <tp:docstring>
 421           The type of address the connection manager should listen on.
 422         </tp:docstring>
 423       </arg>
 424       <arg direction="in" name="Access_Control" type="u" tp:type="Socket_Access_Control">
 425         <tp:docstring>
 426           The type of access control the connection manager should apply to
 427           the socket.
 428         </tp:docstring>
 429       </arg>
 430       <arg direction="in" name="Access_Control_Param" type="v">
 431         <tp:docstring>
 432           A parameter for the access control type, to be interpreted as
 433           specified in the documentation for the Socket_Access_Control enum.
 434         </tp:docstring>
 435       </arg>
 436       <arg direction="out" name="Address" type="v">
 437         <tp:docstring>
 438           The address on which the connection manager will listen for
 439           connections for this file transfer.
 440         </tp:docstring>
 441       </arg>
 442
 443       <tp:possible-errors>
 444         <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
 445           <tp:docstring>
 446             The given address type or access-control mechanism is not supported.
 447           </tp:docstring>
 448         </tp:error>
 449         <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/>
 450           <tp:docstring>
 451             Your address type, access control, access control parameter, or
 452             a combination of all three is invalid.
 453           </tp:docstring>
 454         <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
 455           <tp:docstring>
 456             Channel is not an outgoing transfer, ProvideFile has already been called,
 457             or there was a local error acquiring the socket.
 458           </tp:docstring>
 459         </tp:error>
 460       </tp:possible-errors>
 461     </method>
 462
 463     <signal name="FileTransferStateChanged"
 464       tp:name-for-bindings="File_Transfer_State_Changed">
 465       <tp:docstring>
 466         Emitted when the state of a file transfer changes.
 467       </tp:docstring>
 468       <arg name="State" type="u" tp:type="File_Transfer_State">
 469         <tp:docstring>
 470           The new state of the file transfer; see the File_Transfer_State enumeration.
 471         </tp:docstring>
 472       </arg>
 473       <arg name="Reason" type="u" tp:type="File_Transfer_State_Change_Reason">
 474         <tp:docstring>
 475           The reason for the state change; see the File_Transfer_State_Change_Reason
 476           enumeration.
 477           The value will always be File_Transfer_State_Change_Reason_None, except
 478           when changing state to cancelled.
 479         </tp:docstring>
 480       </arg>
 481     </signal>
 482
 483     <signal name="TransferredBytesChanged"
 484       tp:name-for-bindings="Transferred_Bytes_Changed">
 485       <tp:docstring>
 486         Emitted when the number of transferred bytes changes. This will not be
 487         signalled with every single byte change. Instead, the most frequent
 488         this signal will be emitted is once a second. This should be
 489         sufficient, and the <tp:member-ref>TransferredBytes</tp:member-ref>
 490         property SHOULD NOT be polled.
 491       </tp:docstring>
 492       <arg name="Count" type="t">
 493         <tp:docstring>
 494           The number of already transferred bytes.
 495         </tp:docstring>
 496       </arg>
 497     </signal>
 498
 499     <signal name="InitialOffsetDefined"
 500       tp:name-for-bindings="Initial_Offset_Defined">
 501       <tp:docstring>
 502         Emitted when the value of the <tp:member-ref>InitialOffset</tp:member-ref>
 503         property has been negotiated. This signal MUST be emitted before the channel
 504         becomes Open and clients have to use this offset when transferring the
 505         file.
 506       </tp:docstring>
 507       <arg name="InitialOffset" type="t">
 508         <tp:docstring>
 509           The value of the <tp:member-ref>InitialOffset</tp:member-ref> property.
 510         </tp:docstring>
 511       </arg>
 512     </signal>
 513
 514   </interface>
 515
 516 </node>
 517 <!-- vim:set sw=2 sts=2 et ft=xml: -->