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