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/Write | Sometimes immutable, Requestable | |
| ContentHash | s | Read/Write | Sometimes 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 |
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 e.g. 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.
The FileTransfer channel type may be requested for handles of 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.
Sending a file
- A client should request a FileTransfer channel to a contact, including at least the mandatory properties. For example:
- The channel is returned and if hashing information is to be
sent, it is calculated now. Note that if the client who
requested the channel isn't the channel handler, the
URI property should be set in the
channel request.
The handler can update the ContentHashType and ContentHash properties appropriately using the D-Bus properties' Set method.
Rationale:
If the handler didn't request the file, it will not know what file to actually send over the socket to the connection manager. - The handler calls ProvideFile to configure the socket that will be used to transfer the file. At this point, the file transfer invitation is actually sent to the other contact by the CM and the ContentHashType, ContentHash, and URI properties are now immutable.
- The transfer State changes to Pending as the recipient decides whether to accept the transfer.
- If the transfer is accepted, the State changes to Open and the handler must then start sending the file to the CM using the socket previously set up in the ProvideFile call.
{
ChannelType: FileTransfer1,
TargetHandleType: Contact,
TargetID: "foo@bar.com",
Filename: "wickedparty.jpg",
Size: 1020357
}Receiving a file
- A wild FileTransfer channel appears.
- The URI property MAY be set by the channel handler before calling AcceptFile to inform observers where the file will be saved. If the property is set by an approver, the channel handler MUST save the file to that location.
- The handler then calls AcceptFile to configure the socket that will be used to receive the file.
- When the transfer State changes to Open, the handler MUST check the InitialOffset property to see if it differs from the value given in AcceptFile and act accordingly.
- The handler can now start receiving the file from the CM using the socket previously set up in the AcceptFile call.
During a file transfer
To reject an incoming file transfer, or to cancel an ongoing transfer, handlers should call Channel.Close.
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
Emitted when the TransferredBytes property changes. This signal SHOULD NOT be emitted for every byte transferred; instead it should be signalled a maximum of once a second.
Rationale:
The TransferredBytes property SHOULD NOT be polled.
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. Protocols which do not have a "content type" property with file transfers should set this value to application/octet-stream.
This property is mandatory when requesting a file transfer channel.
Filename — s
The name of the file on the sender's side. This is therefore given as a suggested filename for the receiver.
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 a file transfer channel; it cannot be empty and MUST be set to a sensible value.
Size — t
The size of the file.
For outgoing transfers, the value of this property MUST be in bytes, and accurate to the nearest byte. For incoming transfers, the value of this property MUST be in bytes but clients SHOULD NOT treat it as accurate to the nearest byte.
This property is mandatory when requesting a file transfer channel. 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.
For outgoing file transfers, this property is mutable until ProvideFile has been called. The property, along with ContentHash, can be updated using the D-Bus properties interface. Its value MUST correspond to the appropriate type of the ContentHash property.
For incoming file transfers, this property is always immutable.
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.
This property is optional when requesting file transfer channels. Its default value is None.
ContentHash — s
Hash of the contents of the file transfer, of type described by the value of the ContentHashType property.
For outgoing file transfers, this property is mutable until ProvideFile has been called. The property, along with ContentHashType, can be updated using the D-Bus properties interface. Its value MUST correspond to the appropriate type of the ContentHashType property. If the ContentHashType property is not set, or set to None, then this property should not be set.
For incoming file transfers, this property is always immutable.
This property is optional when requesting file transfer channels. Its default value is the empty string.
Description — s
Description of the file transfer.
This property is optional when requesting a file transfer channel. 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 property is optional when requesting a file transfer channel.
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 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.
URI — s
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
File_Transfer_State — u
- None (0)
- Pending (1)
- Open (2)
- Completed (3)
- Cancelled (4)
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)