diff options
| -rw-r--r-- | extensions/Channel_Type_File_Transfer.xml (renamed from extensions/Channel_Type_File.xml) | 254 | ||||
| -rw-r--r-- | extensions/misc.xml | 2 |
2 files changed, 160 insertions, 96 deletions
diff --git a/extensions/Channel_Type_File.xml b/extensions/Channel_Type_File_Transfer.xml index b8717ad04..4838f7f1d 100644 --- a/extensions/Channel_Type_File.xml +++ b/extensions/Channel_Type_File_Transfer.xml @@ -1,5 +1,5 @@ <?xml version="1.0" ?> -<node name="/Channel_Type_File" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> +<node name="/Channel_Type_File_Transfer" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> <tp:copyright> Copyright (C) 2008 Collabora Limited </tp:copyright> @@ -18,48 +18,67 @@ Library General Public License for more details.</p> License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> </tp:license> - <interface name="org.freedesktop.Telepathy.Channel.Type.File.DRAFT" + <interface name="org.freedesktop.Telepathy.Channel.Type.FileTransfer.DRAFT" tp:causes-havoc="experimental"> <tp:requires interface="org.freedesktop.Telepathy.Channel"/> - <tp:docstring> - <p>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.</p> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>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.</p> <p>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.</p> - <p>If something goes wrong with the transfer, you should call Close - on the channel.</p> + <ul><li>In order to send a file, one should request a FileTransfer + channel for a contact, and fill the mandatory properties + (<tp:member-ref>Filename</tp:member-ref>, and + <tp:member-ref>Size</tp:member-ref>). After these are set, one should + call <tp:member-ref>OfferFile</tp:member-ref> to offer the transfer to + the contact.</li> + + <li>In order to receive an incoming file transfer, one should call + <tp:member-ref>AcceptFile</tp:member-ref> 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 + <tp:member-ref>AcceptFile</tp:member-ref>. When the state changes to Open, + the receiver must check the <tp:member-ref>InitialOffset</tp:member-ref> + property for a difference in offset from the requested value in + AcceptFile.</li></ul> + + <p>If something goes wrong with the transfer, + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Close</tp:dbus-ref> + should be called on the channel.</p> <p>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.</p> + handle type then the behaviour is undefined.</p> </tp:docstring> <property name="State" type="u" tp:type="File_Transfer_State" - access="read"> + access="read" tp:name-for-bindings="State"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The state of the file transfer as described by the File_Transfer_State enum.</p> </tp:docstring> </property> - <property name="ContentType" type="s" access="readwrite"> + <property name="ContentType" type="s" access="read" + tp:name-for-bindings="Content_Type"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The file's MIME type. This cannot change once the channel has been created.</p> <p>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.</p> + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref> + method. Protocols which do not have a content-type property with file + transfers should set this value to application/octet-stream.</p> </tp:docstring> </property> - <property name="Filename" type="s" access="readwrite"> + <property name="Filename" type="s" access="read" + tp:name-for-bindings="Filename"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The name of the file on the sender's side. This is therefore given as a suggested filename for the receiver. This cannot change @@ -70,12 +89,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ be set to monkey.pdf.</p> <p>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.</p> + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref> + method. This property cannot be empty and must be set to a sensible value.</p> </tp:docstring> </property> - <property name="Size" type="t" access="readwrite"> + <property name="Size" type="t" access="read" + tp:name-for-bindings="Size"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The size of the file. If this property is set, then the file transfer is guaranteed to be this size. This cannot change once @@ -87,51 +107,70 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ to the byte.</p> <p>This property is mandatory when requesting the channel with the - CreateChannels requests method. If this property is UINT64_MAX, - then its value is unspecified.</p> + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref> + method. If this property is UINT64_MAX, then its value is + unspecified.</p> </tp:docstring> </property> <property name="ContentHashType" type="u" tp:type="File_Hash_Type" - access="readwrite"> + access="read" tp:name-for-bindings="Content_Hash_Type"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The type of the ContentHash property from values of the - File_Hash_Type enum.</p> + <p>The type of the <tp:member-ref>ContentHash</tp:member-ref> property.</p> <p>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.</p> + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref> + method. However, if you wish to include the <tp:member-ref>ContentHash</tp:member-ref> + property you MUST also include this property. If you omit this property from a + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref> + method call then its value will be assumed to be File_Hash_Type_None.</p> </tp:docstring> </property> - <property name="ContentHash" type="s" access="readwrite"> + <property name="ContentHash" type="s" access="read" + tp:name-for-bindings="Content_Hash"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Hash of the contents of the file transfer, of type described - in the value of the ContentHashType property.</p> + in the value of the <tp:member-ref>ContentHashType</tp:member-ref> + property.</p> <p>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 + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref> + method. Its value MUST correspond to the appropriate type of the + <tp:member-ref>ContentHashType</tp:member-ref> property. If the ContentHashType property is not set, or set to File_Hash_Type_None, then this property will not even be looked at.</p> </tp:docstring> </property> - <property name="Description" type="s" access="readwrite"> + <property name="Description" type="s" access="read" + tp:name-for-bindings="Description"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Description of the file transfer. This cannot change once the channel has been created.</p> <p>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.</p> + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref> + method. If this property is an empty string, then its value is + unspecified.</p> + </tp:docstring> + </property> + + <property name="Date" type="t" access="read" + tp:type="Unix_Timestamp64" tp:name-for-bindings="Date"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The last modification time of the file being transferred. This + cannot change once the channel has been created</p> + + <p>This property is optional when requesting the channel with the + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref> + method.</p> </tp:docstring> </property> <property name="AvailableSocketTypes" type="a{uau}" - tp:type="Supported_Socket_Map" access="read"> + tp:type="Supported_Socket_Map" access="read" + tp:name-for-bindings="Available_Socket_Types"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>A mapping from address types (members of Socket_Address_Type) to arrays of access-control type (members of Socket_Access_Control) @@ -153,7 +192,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> </property> - <property name="TransferredBytes" type="t" access="read"> + <property name="TransferredBytes" type="t" access="read" + tp:name-for-bindings="Transferred_Bytes"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The number of bytes that have been transferred at the time of requesting the property. This will be updated as the file transfer @@ -161,15 +201,17 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> </property> - <property name="InitialOffset" type="t" access="read"> + <property name="InitialOffset" type="t" access="read" + tp:name-for-bindings="Initial_Offset"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>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.</p> + <p>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.</p> - <p>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.</p> + <p>Before setting the <tp:member-ref>State</tp:member-ref> property to + Open, the connection manager MUST set the InitialOffset property, + possibly to 0.</p> <p>This property MUST NOT change after the state of the transfer has changed to Open.</p> @@ -179,20 +221,21 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:enum name="File_Transfer_State" type="u"> <tp:enumvalue suffix="None" value="0"> <tp:docstring> - The file transfer is currently not set up correctly. + An invalid state type used as a null value. This value MUST NOT + appear in the State property. </tp:docstring> </tp:enumvalue> <tp:enumvalue suffix="Not_Offered" value="1"> <tp:docstring> - The file transfer is waiting for the local user to offer the file - as a transfer. + The transfer is waiting for the local client to call the OfferFile + method, in order to offer a file to be transferred. </tp:docstring> </tp:enumvalue> <tp:enumvalue suffix="Accepted" value="2"> <tp:docstring> - 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 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. </tp:docstring> </tp:enumvalue> <tp:enumvalue suffix="Local_Pending" value="3"> @@ -215,9 +258,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ The file transfer has been completed successfully. </tp:docstring> </tp:enumvalue> - <tp:enumvalue suffix="Canceled" value="7"> + <tp:enumvalue suffix="Cancelled" value="7"> <tp:docstring> - The file transfer has been canceled. + The file transfer has been cancelled. </tp:docstring> </tp:enumvalue> </tp:enum> @@ -228,24 +271,29 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ No reason was specified. </tp:docstring> </tp:enumvalue> + <tp:enumvalue suffix="Requested" value="1"> + <tp:docstring> + The change in state was requested. + </tp:docstring> + </tp:enumvalue> <tp:enumvalue suffix="Local_Stopped" value="1"> <tp:docstring> - The file transfer was canceled by the local user. + The file transfer was cancelled by the local user. </tp:docstring> </tp:enumvalue> <tp:enumvalue suffix="Remote_Stopped" value="2"> <tp:docstring> - The file transfer was canceled by the remote user. + The file transfer was cancelled by the remote user. </tp:docstring> </tp:enumvalue> <tp:enumvalue suffix="Local_Error" value="3"> <tp:docstring> - The file transfer was canceled because of a local error. + The file transfer was cancelled because of a local error. </tp:docstring> </tp:enumvalue> <tp:enumvalue suffix="Remote_Error" value="4"> <tp:docstring> - The file transfer was canceled because of a remote error. + The file transfer was cancelled because of a remote error. </tp:docstring> </tp:enumvalue> </tp:enum> @@ -258,57 +306,60 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:enumvalue> <tp:enumvalue suffix="MD5" value="1"> <tp:docstring> - MD5 digest as a string of 32 ASCII hex digits, which SHOULD be - lower-case if they are letters. + MD5 digest as a string of 32 ASCII hex digits. </tp:docstring> </tp:enumvalue> <tp:enumvalue suffix="SHA1" value="2"> <tp:docstring> - 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. </tp:docstring> </tp:enumvalue> <tp:enumvalue suffix="SHA256" value="3"> <tp:docstring> - SHA1 digest as a string of ASCII hex digits, which SHOULD be - lower-case if they are letters. + SHA256 digest as a string of ASCII hex digits. </tp:docstring> </tp:enumvalue> </tp:enum> - <method name="AcceptFile"> + <method name="AcceptFile" tp:name-for-bindings="Accept_File"> <tp:docstring> - 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. + 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 + <tp:member-ref>InitialOffset</tp:member-ref> should be checked in case + its value differs from the offset that was specified as an argument + to AcceptFile. </tp:docstring> - <arg direction="in" name="address_type" type="u" tp:type="Socket_Address_Type"> + <arg direction="in" name="Address_Type" type="u" tp:type="Socket_Address_Type"> <tp:docstring> The type of address the connection manager should listen on. </tp:docstring> </arg> - <arg direction="in" name="access_control" type="u" tp:type="Socket_Access_Control"> + <arg direction="in" name="Access_Control" type="u" tp:type="Socket_Access_Control"> <tp:docstring> The type of access control the connection manager should apply to the socket. </tp:docstring> </arg> - <arg direction="in" name="access_control_param" type="v"> + <arg direction="in" name="Access_Control_Param" type="v"> <tp:docstring> A parameter for the access control type, to be interpreted as specified in the documentation for the Socket_Access_Control enum. </tp:docstring> </arg> - <arg direction="in" name="offset" type="t"> + <arg direction="in" name="Offset" type="t"> <tp:docstring> - 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 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 + <tp:member-ref>InitialOffset</tp:member-ref> 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.) </tp:docstring> </arg> - <arg direction="out" name="address" type="v"> + <arg direction="out" name="Address" type="v"> <tp:docstring> The address on which the connection manager will listen for connections for this file transfer. @@ -323,38 +374,44 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:error> <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> + <tp:docstring> + Your address type, access control, access control parameter, + offset, or a combination of all four is invalid. + </tp:docstring> <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> <tp:docstring> - The file transfer is not in the "local pending" state, which is the only - state this method makes sense. + The file transfer is not in the Local_Pending state, there isn't + or there is a local error with acquiring a socket. </tp:docstring> </tp:error> </tp:possible-errors> </method> - <method name="OfferFile"> + <method name="OfferFile" tp:name-for-bindings="Offer_File"> <tp:docstring> - Offer a file transfer that's in the "not offered" state. The file transfer - becomes remote pending after this method is called. + 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. </tp:docstring> - <arg direction="in" name="address_type" type="u" tp:type="Socket_Address_Type"> + <arg direction="in" name="Address_Type" type="u" tp:type="Socket_Address_Type"> <tp:docstring> The type of address the connection manager should listen on. </tp:docstring> </arg> - <arg direction="in" name="access_control" type="u" tp:type="Socket_Access_Control"> + <arg direction="in" name="Access_Control" type="u" tp:type="Socket_Access_Control"> <tp:docstring> The type of access control the connection manager should apply to the socket. </tp:docstring> </arg> - <arg direction="in" name="access_control_param" type="v"> + <arg direction="in" name="Access_Control_Param" type="v"> <tp:docstring> A parameter for the access control type, to be interpreted as specified in the documentation for the Socket_Access_Control enum. </tp:docstring> </arg> - <arg direction="out" name="address" type="v"> + <arg direction="out" name="Address" type="v"> <tp:docstring> The address on which the connection manager will listen for connections for this file transfer. @@ -367,44 +424,51 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ The given address type or access-control mechanism is not supported. </tp:docstring> </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> + <tp:docstring> + Your address type, access control, access control parameter, or + a combination of all three is invalid. + </tp:docstring> <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> <tp:docstring> - The file transfer is not in the "not offered" state, or there isn't - enough information for the transfer to start. + 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. </tp:docstring> </tp:error> </tp:possible-errors> </method> - <signal name="FileTransferStateChanged"> + <signal name="FileTransferStateChanged" + tp:name-for-bindings="File_Transfer_State_Changed"> <tp:docstring> Emitted when the state of a file transfer changes. </tp:docstring> - <arg name="state" type="u" tp:type="File_Transfer_State"> + <arg name="State" type="u" tp:type="File_Transfer_State"> <tp:docstring> The new state of the file transfer; see the File_Transfer_State enumeration. </tp:docstring> </arg> - <arg name="reason" type="u" tp:type="File_Transfer_State_Change_Reason"> + <arg name="Reason" type="u" tp:type="File_Transfer_State_Change_Reason"> <tp:docstring> 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. + when changing state to cancelled. </tp:docstring> </arg> </signal> - <signal name="TransferredBytesChanged"> + <signal name="TransferredBytesChanged" + tp:name-for-bindings="Transferred_Bytes_Changed"> <tp:docstring> 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. + sufficient, and the <tp:member-ref>TransferredBytes</tp:member-ref> + property SHOULD NOT be polled. </tp:docstring> - <arg name="count" type="t"> + <arg name="Count" type="t"> <tp:docstring> The number of already transferred bytes. </tp:docstring> diff --git a/extensions/misc.xml b/extensions/misc.xml index 40eccde1f..3182d4f13 100644 --- a/extensions/misc.xml +++ b/extensions/misc.xml @@ -7,6 +7,6 @@ <xi:include href="Stream_Engine.xml"/> <xi:include href="Channel_Handler.xml"/> <xi:include href="Tube_Handler.xml"/> -<xi:include href="Channel_Type_File.xml"/> +<xi:include href="Channel_Type_File_Transfer.xml"/> </tp:spec> |