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) |
Properties
State | u (File_Transfer_State) | Read only | |
ContentType | s | Read only | |
Filename | s | Read only | |
Size | t | Read only | |
ContentHashType | u (File_Hash_Type) | Read only | |
ContentHash | s | Read only | |
Description | s | Read only | |
Date | x (Unix_Timestamp64) | Read only | |
AvailableSocketTypes | a{uau} (Supported_Socket_Map) | Read only | |
TransferredBytes | t | Read only | |
InitialOffset | t | Read only |
Types
File_Transfer_State | Enum | u | |
File_Transfer_State_Change_Reason | Enum | u | |
File_Hash_Type | Enum | u |
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.
People would send us files, and it would always fail. That would be silly.
Methods
AcceptFile (u: Address_Type, u: Access_Control, v: Access_Control_Param, t: Offset) → v: Address
Parameters
- Address_Type — u (Socket_Address_Type)
- Access_Control — u (Socket_Access_Control)
- Access_Control_Param — v
- Offset — t
Returns
- Address — v
Possible Errors
- Not Implemented
- Network Error
- Invalid Argument
- Not Available
ProvideFile (u: Address_Type, u: Access_Control, v: Access_Control_Param) → v: Address
Parameters
- Address_Type — u (Socket_Address_Type)
- Access_Control — u (Socket_Access_Control)
- Access_Control_Param — v
Returns
- Address — v
Possible Errors
- Not Implemented
- Invalid Argument
- Not Available
Signals
FileTransferStateChanged (u: State, u: Reason)
Parameters
- State — u (File_Transfer_State)
- Reason — u (File_Transfer_State_Change_Reason)
TransferredBytesChanged (t: Count)
Parameters
- Count — t
InitialOffsetDefined (t: InitialOffset)
Parameters
- InitialOffset — t
Properties
State — u (File_Transfer_State)
The state of the file transfer as described by the File_Transfer_State enum.
ContentType — s
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.
Filename — s
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.
Size — t
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.
ContentHashType — u (File_Hash_Type)
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.
ContentHash — s
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.
Description — s
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.
Date — x (Unix_Timestamp64)
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.
AvailableSocketTypes — a{uau} (Supported_Socket_Map)
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] }
TransferredBytes — t
The number of bytes that have been transferred at the time of requesting the property. This will be updated as the file transfer continues.
InitialOffset — t
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.
Types
File_Transfer_State — u
- None (0)
- Pending (1)
- Accepted (2)
- Open (3)
- Completed (4)
- Cancelled (5)
File_Transfer_State_Change_Reason — u
- None (0)
- Requested (1)
- Local_Stopped (2)
- Remote_Stopped (3)
- Local_Error (4)
- Remote_Error (5)
File_Hash_Type — u
- None (0)
- MD5 (1)
- SHA1 (2)
- SHA256 (3)