From: Xavier Claessens Date: Fri, 21 Nov 2008 16:20:23 +0000 (+0000) Subject: upgrade to new FT draft X-Git-Url: https://git.0d.be/?p=empathy.git;a=commitdiff_plain;h=49c4ad76cbb6220e6400ba06c5a12a9dee8a9449 upgrade to new FT draft svn path=/trunk/; revision=1841 --- diff --git a/extensions/Channel_Type_File.xml b/extensions/Channel_Type_File.xml deleted file mode 100644 index b8717ad0..00000000 --- a/extensions/Channel_Type_File.xml +++ /dev/null @@ -1,416 +0,0 @@ - - - - Copyright (C) 2008 Collabora Limited - - -

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 files offered for transferring. - The actual transmission of the data is done by reading or writing - a socket, the type of socket (local Unix, IPv4, etc.) when the File - channel is created.

- -

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, you should call Close - 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 behviour is undefined.

- - - - -

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 - CreateChannels requests method. Protocols which do not have a - content-type property with file transfers should set this value to - application/octet-stream.

- - - - - -

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 - CreateChannels requests method. This property cannot be empty and - must be set to a sensible value.

- - - - - -

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 - CreateChannels requests method. If this property is UINT64_MAX, - then its value is unspecified.

- - - - - -

The type of the ContentHash property from values of the - File_Hash_Type enum.

- -

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

- - - - - -

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 - CreateChannels requests 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 of the file transfer. This cannot change once the - channel has been created.

- -

This property is optional when requesting the channel with the - CreateChannel requests method. If this property is an empty string, - then its value is unspecified.

- - - - - -

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.

- -

A typical value for a host that supports only Unix sockets:

- - 
-          {
-            Socket_Address_Type_Unix:
-              [Socket_Access_Control_Localhost, Socket_Access_Control_Credentials]
-            Socket_Address_Type_Abstract_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 from the beginning of the file that the transfer should - start from. This should be checked by the receiver after the transfer - changes state from Accepted to Open.

- -

Before setting the State property to Open, the connection manager - MUST set the InitialOffset property. If there is no offset then this - value MUST be set to 0.

- -

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

- - - - - - - The file transfer is currently not set up correctly. - - - - - The file transfer is waiting for the local user to offer the file - as a transfer. - - - - - The file transfer has been accepted locally, but not currently open. - The transfer should now wait for the state to change to open and - check the offset value. - - - - - The file transfer is waiting to be accepted/closed locally. - - - - - The file transfer is waiting to be accepted/closed remotely. - - - - - The file transfer is open for traffic. - - - - - The file transfer has been completed successfully. - - - - - The file transfer has been canceled. - - - - - - - - No reason was specified. - - - - - The file transfer was canceled by the local user. - - - - - The file transfer was canceled by the remote user. - - - - - The file transfer was canceled because of a local error. - - - - - The file transfer was canceled because of a remote error. - - - - - - - - No hash. - - - - - MD5 digest as a string of 32 ASCII hex digits, which SHOULD be - lower-case if they are letters. - - - - - SHA1 digest as a string of ASCII hex digits, which SHOULD be - lower-case if they are letters. - - - - - SHA1 digest as a string of ASCII hex digits, which SHOULD be - lower-case if they are letters. - - - - - - - Accept a file transfer that's in the "local pending" state. The file - transfer's state becomes accepted after this method is called. At this - point, the receiver must wait for the state to change to open. When this - happens, the InitialOffset property should be read to find from where the - file is actually being sent. - - - - The type of address the connection manager should listen on. - - - - - The type of access control the connection manager should apply to - the socket. - - - - - A parameter for the access control type, to be interpreted as - specified in the documentation for the Socket_Access_Control enum. - - - - - The offset in bytes of wthere the file tranfer should start from. - The offset is taken from the beginning of the file. Values of zero - will start the transfer from the beginning of the file. - - - - - The address on which the connection manager will listen for - connections for this file transfer. - - - - - - - The given address type or access-control mechanism is not supported. - - - - - - - The file transfer is not in the "local pending" state, which is the only - state this method makes sense. - - - - - - - - Offer a file transfer that's in the "not offered" state. The file transfer - becomes remote pending after this method is called. - - - - The type of address the connection manager should listen on. - - - - - The type of access control the connection manager should apply to - the socket. - - - - - A parameter for the access control type, to be interpreted as - specified in the documentation for the Socket_Access_Control enum. - - - - - The address on which the connection manager will listen for - connections for this file transfer. - - - - - - - The given address type or access-control mechanism is not supported. - - - - - - - The file transfer is not in the "not offered" state, or there isn't - enough information for the transfer to start. - - - - - - - - Emitted when the state of a file transfer changes. - - - - The new state of the file transfer; see the File_Transfer_State enumeration. - - - - - 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 canceled. - - - - - - - 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. - - - - The number of already transferred bytes. - - - - - - - diff --git a/extensions/Channel_Type_File_Transfer.xml b/extensions/Channel_Type_File_Transfer.xml new file mode 100644 index 00000000..4838f7f1 --- /dev/null +++ b/extensions/Channel_Type_File_Transfer.xml @@ -0,0 +1,480 @@ + + + + Copyright (C) 2008 Collabora Limited + + +

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 files offered for transferring. 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.

+ +

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, and fill the mandatory properties + (Filename, and + Size). After these are set, one should + call OfferFile to offer the transfer to + the contact.
    • + +
  • In order to receive an incoming file transfer, one should call + AcceptFile and then wait until the state + changes to Open. If the receiver is resuming a transfer then he or she + should set a non-zero Offset argument when calling + AcceptFile. When the state changes to Open, + the receiver must check the InitialOffset + property for a difference in offset from the requested value in + AcceptFile.
+ +

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.

+ + + + +

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 + 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.

+ + + + + +

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.

+ + + + + +

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 property is UINT64_MAX, then its value is + unspecified.

+ + + + + +

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.

+ + + + + +

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 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 is an empty string, then its value is + unspecified.

+ + + + + +

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.

+ + + + + +

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.

+ +

A typical value for a host that supports only Unix sockets:

+ + 
+          {
+            Socket_Address_Type_Unix:
+              [Socket_Access_Control_Localhost, Socket_Access_Control_Credentials]
+            Socket_Address_Type_Abstract_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 checked by both the receiver and the sender after the state + becomes Open, but before any data is sent or received. Until the + state changes to Open, 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.

+ + + + + + + An invalid state type used as a null value. This value MUST NOT + appear in the State property. + + + + + The transfer is waiting for the local client to call the OfferFile + method, in order to offer a file to be transferred. + + + + + The client has accepted the incoming file transfer, but the transfer + is not open. The client should now wait for the state to change to Open + and check the offset value. + + + + + The file transfer is waiting to be accepted/closed locally. + + + + + The file transfer is waiting to be accepted/closed remotely. + + + + + The file transfer is open for traffic. + + + + + The file transfer has been completed successfully. + + + + + The file transfer has been cancelled. + + + + + + + + No reason was specified. + + + + + The change in state was requested. + + + + + The file transfer was cancelled by the local user. + + + + + The file transfer was cancelled by the remote user. + + + + + The file transfer was cancelled because of a local error. + + + + + The file transfer was cancelled because of a remote error. + + + + + + + + No hash. + + + + + MD5 digest as a string of 32 ASCII hex digits. + + + + + SHA1 digest as a string of ASCII hex digits. + + + + + SHA256 digest as a string of ASCII hex digits. + + + + + + + Accept a file transfer that's in the Local_Pending state. The file + transfer's state becomes Accepted after this method is called. At this + point, the receiver must wait for the state to change to Open, and then + InitialOffset should be checked in case + its value differs from the offset that was specified as an argument + to AcceptFile. + + + + The type of address the connection manager should listen on. + + + + + The type of access control the connection manager should apply to + the socket. + + + + + A parameter for the access control type, to be interpreted as + specified in the documentation for the Socket_Access_Control enum. + + + + + 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.) + + + + + The address on which the connection manager will listen for + connections for this file transfer. + + + + + + + The given address type or access-control mechanism is not supported. + + + + + + Your address type, access control, access control parameter, + offset, or a combination of all four is invalid. + + + + The file transfer is not in the Local_Pending state, there isn't + or there is a local error with acquiring a socket. + + + + + + + + Offer a file transfer that's in the Not_Offered state. Open a socket + that the client can use to provide a file to the connection manager. + The channel MUST be in the Not_Offered state, and will change state + to Remote_Pending when this method is called. + + + + The type of address the connection manager should listen on. + + + + + The type of access control the connection manager should apply to + the socket. + + + + + A parameter for the access control type, to be interpreted as + specified in the documentation for the Socket_Access_Control enum. + + + + + The address on which the connection manager will listen for + connections for this file transfer. + + + + + + + The given address type or access-control mechanism is not supported. + + + + + Your address type, access control, access control parameter, or + a combination of all three is invalid. + + + + The file transfer is not in the Not_Offered state, there isn't + enough information for the transfer to start, or a local error + with acquiring a socket. + + + + + + + + Emitted when the state of a file transfer changes. + + + + The new state of the file transfer; see the File_Transfer_State enumeration. + + + + + 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 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. + + + + The number of already transferred bytes. + + + + + + + diff --git a/extensions/misc.xml b/extensions/misc.xml index 40eccde1..3182d4f1 100644 --- a/extensions/misc.xml +++ b/extensions/misc.xml @@ -7,6 +7,6 @@ - +