This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details.
You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
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.
If something goes wrong with the transfer,
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
People would send us files, and it would always fail. That would be silly.
The state of the file transfer as described by the File_Transfer_State enum.
The file's MIME type. This cannot change once the channel has been created.
This property is mandatory when requesting the channel with the
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
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
The type of the
This property is optional when requesting the channel with the
For each supported hash type, implementations SHOULD include an entry
in
Hash of the contents of the file transfer, of type described
in the value of the
This property is optional when requesting the channel with the
Description of the file transfer. This cannot change once the channel has been created.
This property is optional when requesting the channel with the
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
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] }
The number of bytes that have been transferred at the time of requesting the property. This will be updated as the file transfer continues.
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
Before setting the
This property MUST NOT change after the state of the transfer has changed to Open.
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
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
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.
The collection of files to which this channel belongs, or the empty string if this channel does not belong to a collection of files.
A channel's FileCollection property can never change.
At least on GTalk and apparently also on iChat the user can send a set of files to a contact and that contact can then pick and choose which files to actually receive.
The CM should emit all new FT channels belonging to one collection at the same time. UIs supporting this feature can then bundle all these channels together in some way, and show a nice UI. UIs not supporting it will treat them as separate transfers, which is not great but a reasonable fallback.
No mechanism is currently defined to indicate whether the UI should expect any more files in the same collection. UIs SHOULD assume that more file transfers may be added to a collection. It is possible that a "no more channels in this collection" indication will be added in a future version of this specification.