Chan.T.FileTransfer — Telepathy D-Bus Interface Specification

# Interface Channel.Type.FileTransfer

Interface Index (Compact) | Summary | Description | Methods | Signals | Properties | Types

### Methods

AcceptFile | (u: Address_Type, u: Access_Control, v: Access_Control_Param, t: Offset) | → | v: Address |
ProvideFile | (u: Address_Type, u: Access_Control, v: Access_Control_Param) | → | v: Address |

### Signals

FileTransferStateChanged | (u: State, u: Reason) |
TransferredBytesChanged | (t: Count) |
InitialOffsetDefined | (t: InitialOffset) |
URIDefined | (s: URI) |

### Properties

State | u (File_Transfer_State) | Read only |  |
ContentType | s | Read only | Immutable, Requestable |
Filename | s | Read only | Immutable, Requestable |
Size | t | Read only | Immutable, Requestable |
ContentHashType | u (File_Hash_Type) | Read only | Immutable, Requestable |
ContentHash | s | Read only | Immutable, Requestable |
Description | s | Read only | Immutable, Requestable |
Date | x (Unix_Timestamp64) | Read only | Immutable, Requestable |
AvailableSocketTypes | a{uau} (Supported_Socket_Map) | Read only | Immutable, Requestable |
TransferredBytes | t | Read only |  |
InitialOffset | t | Read only | Requestable |
URI | s | Read/Write | Sometimes immutable, Requestable |

### Types

File_Transfer_State | Enum | u |
File_Transfer_State_Change_Reason | Enum | u |
File_Hash_Type | Enum | u |

Added in 0.17.18. (as stable API)
Objects implementing this interface must also implement:

- org.freedesktop.Telepathy.Channel

### Description

A channel type for transferring files. The transmission of data between contacts is achieved by reading from or writing to a socket. The type of the socket (local Unix, IPv4, etc.) is decided on when the file transfer is offered or accepted.

A socket approach is used to make the transfer less dependent on both client and connection manager knowing the same protocols. As an example, when browsing an SMB share in a file manager, one selects "Send file" and chooses a contact. Instead of passing a URL which would then require the connection manager to connect to the SMB share itself, the client passes a stream from which the connection manager reads, requiring no further connection to the share. It also allows connection managers to be more restricted in their access to the system, allowing tighter security policies with eg SELinux, or more flexible deployments which cross user or system boundaries.

The Telepathy client should connect to the socket or address that the connection manager has set up and provided back to the clients through the two methods.

- In order to send a file, one should request a FileTransfer channel for a contact, including at least the mandatory properties (Filename, Size and ContentType). Then, one should call ProvideFile to configure the socket that will be used to transfer the file.
- In order to receive an incoming file transfer, one should call AcceptFile and then wait until the state changes to Open. When the receiver wants to resume a transfer, the Offset argument should be should be set to a non-zero value when calling AcceptFile.
- Once the offset has been negotiated, the InitialOffsetDefined signal is emitted and the InitialOffset property is defined. The InitialOffsetDefined signal is emitted before channel becomes Open. The receiver MUST check the value of InitialOffset for a difference in offset from the requested value in AcceptFile.
- When the state changes to Open, Clients can start the transfer of the file using the offset previously announced.

If something goes wrong with the transfer, Channel.Close should be called on the channel.

The File channel type may be requested for handles of type HANDLE_TYPE_CONTACT. If the channel is requested for any other handle type then the behaviour is undefined.

Connection managers SHOULD NOT advertise support for file transfer to other contacts unless it has been indicated by a call to UpdateCapabilities.

##### Rationale:

People would send us files, and it would always fail. That would be silly.

# Methods

(Permalink)

## AcceptFile (u: Address_Type, u: Access_Control, v: Access_Control_Param, t: Offset) → v: Address

### Parameters

- Address_Type — u (Socket_Address_Type)
The type of address the connection manager should listen on.
- Access_Control — u (Socket_Access_Control)
The type of access control the connection manager should apply to the socket.
- Access_Control_Param — v
A parameter for the access control type, to be interpreted as specified in the documentation for the Socket_Access_Control enum.
- Offset — t
The desired offset in bytes where the file transfer should start. The offset is taken from the beginning of the file. Specifying an offset of zero will start the transfer from the beginning of the file. The offset that is actually given in the InitialOffset property can differ from this argument where the requested offset is not supported. (For example, some protocols do not support offsets at all so the InitialOffset property will always be 0.)

### Returns

- Address — v
The address on which the connection manager will listen for connections for this file transfer.

Accept a file transfer that's in the Pending state. The file transfer's state becomes Accepted after this method is called. At this point the client can connect to the socket. CM MUST emit InitialOffsetDefined and change the state to Open before writing to the socket. Then InitialOffset should be respected in case its value differs from the offset that was specified as an argument to AcceptFile.

### Possible Errors

- Not Implemented
The given address type or access-control mechanism is not supported.
- Network Error
Raised when there is an error reading from or writing to the network.
- Invalid Argument
Raised when one of the provided arguments is invalid.
- Not Available
The file transfer is not in the Pending state, there isn't or there is a local error with acquiring a socket.

(Permalink)

## ProvideFile (u: Address_Type, u: Access_Control, v: Access_Control_Param) → v: Address

### Parameters

- Address_Type — u (Socket_Address_Type)
The type of address the connection manager should listen on.
- Access_Control — u (Socket_Access_Control)
The type of access control the connection manager should apply to the socket.
- Access_Control_Param — v
A parameter for the access control type, to be interpreted as specified in the documentation for the Socket_Access_Control enum.

### Returns

- Address — v
The address on which the connection manager will listen for connections for this file transfer.

Provide the file for an outgoing file transfer which has been offered. Opens a socket that the client can use to provide a file to the connection manager. The channel MUST have been requested, and will change state to Open when this method is called if its state was Accepted.

### Possible Errors

- Not Implemented
The given address type or access-control mechanism is not supported.
- Invalid Argument
Raised when one of the provided arguments is invalid.
- Not Available
Channel is not an outgoing transfer, ProvideFile has already been called, or there was a local error acquiring the socket.

# Signals

(Permalink)

## FileTransferStateChanged (u: State, u: Reason)

### Parameters

- State — u (File_Transfer_State)
The new state of the file transfer; see the File_Transfer_State enumeration.
- Reason — u (File_Transfer_State_Change_Reason)
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 cancelled.

Emitted when the state of a file transfer changes.
(Permalink)

## TransferredBytesChanged (t: Count)

### Parameters

- Count — t
The number of already transferred bytes.

Emitted when the number of transferred bytes changes. This will not be signalled with every single byte change. Instead, the most frequent this signal will be emitted is once a second. This should be sufficient, and the TransferredBytes property SHOULD NOT be polled.
(Permalink)

## InitialOffsetDefined (t: InitialOffset)

### Parameters

- InitialOffset — t
The value of the InitialOffset property.

Emitted when the value of the InitialOffset property has been negotiated. This signal MUST be emitted before the channel becomes Open and clients have to use this offset when transferring the file.
(Permalink)

## URIDefined (s: URI)

Added in 0.21.9.

### Parameters

- URI — s
The value of the URI property.

Emitted when the value of the URI property has been set. This signal MUST only be emitted on incoming file transfers, and only if the handler sets the URI property before accepting the file.

# Properties

Accessed using the org.freedesktop.DBus.Properties interface.
(Permalink)

## State — u (File_Transfer_State)

Read only

The state of the file transfer as described by the File_Transfer_State enum.

(Permalink)

## ContentType — s

Read only
This property is immutable which means that it can never change once the channel has been created. Immutable properties SHOULD appear in the channel detail list of NewChannels signals.
This property is requestable, which means that it is allowed in the properties hash of a channel request such as in the CreateChannel and EnsureChannel methods on Requests and ChannelDispatcher. The property should also appear in either the Fixed_Properties or Allowed_Properties of a RequestableChannelClass advertised by the CM.

The file's MIME type. This cannot change once the channel has been created.

This property is mandatory when requesting the channel with the Connection.Interface.Requests.CreateChannel method. Protocols which do not have a content-type property with file transfers should set this value to application/octet-stream.

(Permalink)

## Filename — s

Read only
This property is immutable which means that it can never change once the channel has been created. Immutable properties SHOULD appear in the channel detail list of NewChannels signals.
This property is requestable, which means that it is allowed in the properties hash of a channel request such as in the CreateChannel and EnsureChannel methods on Requests and ChannelDispatcher. The property should also appear in either the Fixed_Properties or Allowed_Properties of a RequestableChannelClass advertised by the CM.

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.

This property should be the basename of the file being sent. For example, if the sender sends the file /home/user/monkey.pdf then this property should be set to monkey.pdf.

This property is mandatory when requesting the channel with the Connection.Interface.Requests.CreateChannel method. This property cannot be empty and MUST be set to a sensible value.

(Permalink)

## Size — t

Read only
This property is immutable which means that it can never change once the channel has been created. Immutable properties SHOULD appear in the channel detail list of NewChannels signals.
This property is requestable, which means that it is allowed in the properties hash of a channel request such as in the CreateChannel and EnsureChannel methods on Requests and ChannelDispatcher. The property should also appear in either the Fixed_Properties or Allowed_Properties of a RequestableChannelClass advertised by the CM.

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.

When you are creating a channel with this property, its value MUST be accurate and in bytes. However, when receiving a file, this property still MUST be in bytes but might not be entirely accurate to the byte.

This property is mandatory when requesting the channel with the Connection.Interface.Requests.CreateChannel method. If this information isn't provided in the protocol, connection managers MUST set it to UINT64_MAX.

(Permalink)

## ContentHashType — u (File_Hash_Type)

Read only
This property is immutable which means that it can never change once the channel has been created. Immutable properties SHOULD appear in the channel detail list of NewChannels signals.
This property is requestable, which means that it is allowed in the properties hash of a channel request such as in the CreateChannel and EnsureChannel methods on Requests and ChannelDispatcher. The property should also appear in either the Fixed_Properties or Allowed_Properties of a RequestableChannelClass advertised by the CM.

The type of the ContentHash property.

This property is optional when requesting the channel with the Connection.Interface.Requests.CreateChannel method. However, if you wish to include the ContentHash property you MUST also include this property. If you omit this property from a Connection.Interface.Requests.CreateChannel method call then its value will be assumed to be File_Hash_Type_None.

For each supported hash type, implementations SHOULD include an entry in RequestableChannelClasses with this property fixed to that hash type. If the protocol supports offering a file without a content hash, implementations SHOULD list this property in Allowed in a requestable channel class, mapping hash types they don't understand to None.

(Permalink)

## ContentHash — s

Read only
This property is immutable which means that it can never change once the channel has been created. Immutable properties SHOULD appear in the channel detail list of NewChannels signals.
This property is requestable, which means that it is allowed in the properties hash of a channel request such as in the CreateChannel and EnsureChannel methods on Requests and ChannelDispatcher. The property should also appear in either the Fixed_Properties or Allowed_Properties of a RequestableChannelClass advertised by the CM.

Hash of the contents of the file transfer, of type described in the value of the ContentHashType property.

This property is optional when requesting the channel with the Connection.Interface.Requests.CreateChannel method. Its value MUST correspond to the appropriate type of the ContentHashType property. If the ContentHashType property is not set, or set to File_Hash_Type_None, then this property will not even be looked at.

(Permalink)

## Description — s

Read only
This property is immutable which means that it can never change once the channel has been created. Immutable properties SHOULD appear in the channel detail list of NewChannels signals.
This property is requestable, which means that it is allowed in the properties hash of a channel request such as in the CreateChannel and EnsureChannel methods on Requests and ChannelDispatcher. The property should also appear in either the Fixed_Properties or Allowed_Properties of a RequestableChannelClass advertised by the CM.

Description of the file transfer. This cannot change once the channel has been created.

This property is optional when requesting the channel with the Connection.Interface.Requests.CreateChannel method. If this property was not provided by the remote party, connection managers MUST set it to the empty string.

(Permalink)

## Date — x (Unix_Timestamp64)

Read only
This property is immutable which means that it can never change once the channel has been created. Immutable properties SHOULD appear in the channel detail list of NewChannels signals.
This property is requestable, which means that it is allowed in the properties hash of a channel request such as in the CreateChannel and EnsureChannel methods on Requests and ChannelDispatcher. The property should also appear in either the Fixed_Properties or Allowed_Properties of a RequestableChannelClass advertised by the CM.

The last modification time of the file being transferred. This cannot change once the channel has been created

This property is optional when requesting the channel with the Connection.Interface.Requests.CreateChannel method.

(Permalink)

## AvailableSocketTypes — a{uau} (Supported_Socket_Map)

Read only
This property is immutable which means that it can never change once the channel has been created. Immutable properties SHOULD appear in the channel detail list of NewChannels signals.
This property is requestable, which means that it is allowed in the properties hash of a channel request such as in the CreateChannel and EnsureChannel methods on Requests and ChannelDispatcher. The property should also appear in either the Fixed_Properties or Allowed_Properties of a RequestableChannelClass advertised by the CM.

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. Connection Managers MUST support at least Socket_Address_Type_IPv4.

A typical value for a host without IPv6 support:

              {
                Socket_Address_Type_IPv4:
                  [Socket_Access_Control_Localhost, Socket_Access_Control_Port,
                   Socket_Access_Control_Netmask],
                Socket_Address_Type_Unix:
                  [Socket_Access_Control_Localhost, Socket_Access_Control_Credentials]
              }

(Permalink)

## TransferredBytes — t

Read only

The number of bytes that have been transferred at the time of requesting the property. This will be updated as the file transfer continues.

(Permalink)

## InitialOffset — t

Read only
This property is requestable, which means that it is allowed in the properties hash of a channel request such as in the CreateChannel and EnsureChannel methods on Requests and ChannelDispatcher. The property should also appear in either the Fixed_Properties or Allowed_Properties of a RequestableChannelClass advertised by the CM.

The offset in bytes from where the file should be sent. This MUST be respected by both the receiver and the sender after the state becomes Open, but before any data is sent or received. Until the InitialOffsetDefined signal is emitted, this property is undefined.

Before setting the State property to Open, the connection manager MUST set the InitialOffset property, possibly to 0.

This property MUST NOT change after the state of the transfer has changed to Open.

(Permalink)

## URI — s

Read/Write
Depending on the protocol, this property may be immutable which means that it can never change once the channel has been created. Immutable properties SHOULD appear in the channel detail list of NewChannels signals.
This property is requestable, which means that it is allowed in the properties hash of a channel request such as in the CreateChannel and EnsureChannel methods on Requests and ChannelDispatcher. The property should also appear in either the Fixed_Properties or Allowed_Properties of a RequestableChannelClass advertised by the CM.
Added in 0.21.9.

For outgoing file transfers, this requestable property allows the channel requester to inform observers (and the handler, if it is not the requester itself) of the URI of the file being transferred. Note that the connection manager SHOULD NOT read this file directly; the handler streams the file into the CM through the socket negotiated using ProvideFile.

On outgoing file transfers, this property MUST NOT change after the channel is requested.

For incoming file transfers, this property MAY be set by the channel handler before calling AcceptFile to inform observers where the incoming file will be saved. If set by an approver, the handler MUST save the file to that location. Setting this property once AcceptFile has been called MUST fail. Once this property has been set URIDefined is emitted.

If set, this URI SHOULD generally point to a file on the local system, as defined by RFC 1738 §3.10; that is, it should be of the form `file:///path/to/file` or `file://localhost/path/to/file`. For outgoing files, this URI MAY use a different scheme, such as `http:`, if a remote resource is being transferred to a contact.

# Types

Enum (Permalink)

## File_Transfer_State — u

- None (0)
An invalid state type used as a null value. This value MUST NOT appear in the State property.
- Pending (1)
The file transfer is waiting to be accepted/closed by the receiver. The receiver has to call AcceptFile, then wait for the state to change to Open and check the offset value.
- Accepted (2)
The receiver has accepted the transfer. The sender now has to call ProvideFile to actually start the transfer. The receiver should now wait for the state to change to Open and check the offset value.
- Open (3)
The file transfer is open for traffic.
- Completed (4)
The file transfer has been completed successfully.
- Cancelled (5)
The file transfer has been cancelled.

Enum (Permalink)

## File_Transfer_State_Change_Reason — u

- None (0)
No reason was specified.
- Requested (1)
The change in state was requested.
- Local_Stopped (2)
The file transfer was cancelled by the local user.
- Remote_Stopped (3)
The file transfer was cancelled by the remote user.
- Local_Error (4)
The file transfer was cancelled because of a local error.
- Remote_Error (5)
The file transfer was cancelled because of a remote error.

Enum (Permalink)

## File_Hash_Type — u

- None (0)
No hash.
- MD5 (1)
MD5 digest as a string of 32 ASCII hex digits.
- SHA1 (2)
SHA1 digest as a string of ASCII hex digits.
- SHA256 (3)
SHA256 digest as a string of ASCII hex digits.