diff options
| -rw-r--r-- | extensions/Channel_Type_File.xml | 274 |
1 files changed, 146 insertions, 128 deletions
diff --git a/extensions/Channel_Type_File.xml b/extensions/Channel_Type_File.xml index 1377a9b9e..b8717ad04 100644 --- a/extensions/Channel_Type_File.xml +++ b/extensions/Channel_Type_File.xml @@ -27,21 +27,20 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ a socket, the type of socket (local Unix, IPv4, etc.) when the File channel is created.</p> - <p>The File channel type may be requested for handles of type - HANDLE_TYPE_CONTACT.</p> - </tp:docstring> + <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> - <property name="Direction" type="u" tp:type="File_Transfer_Direction" - access="read"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The direction of the file transfer.</p> + <p>If something goes wrong with the transfer, you should call Close + on the channel.</p> - <p>This property should become useless with the new request API.</p> - </tp:docstring> - </property> + <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> + </tp:docstring> <property name="State" type="u" tp:type="File_Transfer_State" - access="readwrite"> + access="read"> <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> @@ -53,7 +52,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <p>The file's MIME type. This cannot change once the channel has been created.</p> - <p>This property is mandatory. Protocols which do not have a + <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:docstring> @@ -65,7 +65,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ as a suggested filename for the receiver. This cannot change once the channel has been created.</p> - <p>If this property is an empty string, then its value is unspecified.</p> + <p>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.</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:docstring> </property> @@ -75,29 +81,41 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ transfer is guaranteed to be this size. This cannot change once the channel has been created.</p> - <p>If this property is UINT64_MAX, then its value is unspecified.</p> + <p>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.</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:docstring> </property> - <property name="EstimatedSize" type="t" access="readwrite"> + <property name="ContentHashType" type="u" tp:type="File_Hash_Type" + access="readwrite"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>An estimate of the size of the file. This property should be used - when the protocol doesn't allow exact file sizes (For example, accurate - to the nearest megabyte). This property should not be set if the Size - property can, or has, been set. This cannot change once the channel - has been created.</p> - - <p>If this property is UINT64_MAX, then its value is unspecified.</p> + <p>The type of the ContentHash property from values of the + File_Hash_Type enum.</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:docstring> </property> - <property name="ContentMD5" type="s" access="readwrite"> + <property name="ContentHash" type="s" access="readwrite"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>MD5 digest of the file as a string of 32 ASCII hex digits, which - SHOULD be lower-case if they are letters. This cannot change once - the channel has been created.</p> - - <p>If this property is an empty string, then its value is unspecified.</p> + <p>Hash of the contents of the file transfer, of type described + in the value of the ContentHashType 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 + 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> @@ -106,7 +124,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <p>Description of the file transfer. This cannot change once the channel has been created.</p> - <p>If this property is an empty string, then its value is unspecified.</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:docstring> </property> @@ -141,56 +161,68 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> </property> - <property name="SocketPath" type="s" access="readwrite"> + <property name="InitialOffset" type="t" access="read"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Path to the UNIX socket in use.</p> + <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>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>If this is an empty string, its value is undefined.</p> + <p>This property MUST NOT change after the state of the transfer has + changed to Open.</p> </tp:docstring> </property> - <tp:enum name="File_Transfer_Direction"> - <tp:enumvalue suffix="Incoming" value="0"> + <tp:enum name="File_Transfer_State" type="u"> + <tp:enumvalue suffix="None" value="0"> <tp:docstring> - The file transfer is incoming. + The file transfer is currently not set up correctly. </tp:docstring> </tp:enumvalue> - <tp:enumvalue suffix="Outgoing" value="1"> + <tp:enumvalue suffix="Not_Offered" value="1"> <tp:docstring> - The file transfer is outgoing. + The file transfer is waiting for the local user to offer the file + as a transfer. </tp:docstring> </tp:enumvalue> - </tp:enum> - - <tp:enum name="File_Transfer_State"> - <tp:enumvalue suffix="Local_Pending" value="0"> + <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. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Local_Pending" value="3"> <tp:docstring> The file transfer is waiting to be accepted/closed locally. </tp:docstring> </tp:enumvalue> - <tp:enumvalue suffix="Remote_Pending" value="1"> + <tp:enumvalue suffix="Remote_Pending" value="4"> <tp:docstring> The file transfer is waiting to be accepted/closed remotely. </tp:docstring> </tp:enumvalue> - <tp:enumvalue suffix="Open" value="2"> + <tp:enumvalue suffix="Open" value="5"> <tp:docstring> The file transfer is open for traffic. </tp:docstring> </tp:enumvalue> - <tp:enumvalue suffix="Completed" value="3"> + <tp:enumvalue suffix="Completed" value="6"> <tp:docstring> The file transfer has been completed successfully. </tp:docstring> </tp:enumvalue> - <tp:enumvalue suffix="Canceled" value="4"> + <tp:enumvalue suffix="Canceled" value="7"> <tp:docstring> The file transfer has been canceled. </tp:docstring> </tp:enumvalue> </tp:enum> - <tp:enum name="File_Transfer_State_Change_Reason"> + <tp:enum name="File_Transfer_State_Change_Reason" type="u"> <tp:enumvalue suffix="None" value="0"> <tp:docstring> No reason was specified. @@ -218,106 +250,92 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:enumvalue> </tp:enum> - <!-- Taken from org.freedesktop.Telepathy.Channel.Type.Tubes --> - <tp:enum name="Socket_Address_Type" type="u"> - <tp:enumvalue suffix="Unix" value="0"> + <tp:enum name="File_Hash_Type" type="u"> + <tp:enumvalue suffix="None" value="0"> <tp:docstring> - A Unix socket. The variant contains a byte-array, signature 'ay', - containing the path of the socket. + No hash. </tp:docstring> </tp:enumvalue> - - <tp:enumvalue suffix="Abstract_Unix" value="1"> + <tp:enumvalue suffix="MD5" value="1"> <tp:docstring> - An abstract Unix socket. The variant contains a byte-array, - signature 'ay', containing the path of the socket including the - leading null byte. + MD5 digest as a string of 32 ASCII hex digits, which SHOULD be + lower-case if they are letters. </tp:docstring> </tp:enumvalue> - - <tp:enumvalue suffix="IPv4" value="2"> + <tp:enumvalue suffix="SHA1" value="2"> <tp:docstring> - An IPv4 socket. The variant contains a Socket_Address_IPv4, - i.e. a structure with signature (sq) - in which the string is an IPv4 dotted-quad address literal - (and must not be a DNS name), while the 16-bit unsigned integer is - the port number. + SHA1 digest as a string of ASCII hex digits, which SHOULD be + lower-case if they are letters. </tp:docstring> </tp:enumvalue> - - <tp:enumvalue suffix="IPv6" value="3"> + <tp:enumvalue suffix="SHA256" value="3"> <tp:docstring> - An IPv6 socket. The variant contains a Socket_Address_IPv6, - i.e. a structure with signature (sq) - in which the string is an IPv6 address literal as specified in - RFC2373 (and must not be a DNS name), while the 16-bit unsigned - integer is the port number. + SHA1 digest as a string of ASCII hex digits, which SHOULD be + lower-case if they are letters. </tp:docstring> </tp:enumvalue> - </tp:enum> - <!-- Taken from org.freedesktop.Telepathy.Channel.Type.Tubes --> - <tp:enum name="Socket_Access_Control" type="u"> - <tp:enumvalue suffix="Localhost" value="0"> + <method name="AcceptFile"> + <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. + </tp:docstring> + <arg direction="in" name="address_type" type="u" tp:type="Socket_Address_Type"> <tp:docstring> - The IP or Unix socket can be accessed by any local user (e.g. - a Unix socket that accepts all local connections, or an IP socket - listening on 127.0.0.1 (or ::1) or rejecting connections not from - that address). The associated variant must be ignored. + The type of address the connection manager should listen on. </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Port" value="1"> + </arg> + <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"> <tp:docstring> - May only be used on IP sockets. The associated variant must contain - a struct Socket_Address_IPv4 (or Socket_Address_IPv6) - containing the string form of an IP address of the appropriate - version, and a port number. The socket can only be accessed if the - connecting process has that address and port number; all other - connections will be rejected. + A parameter for the access control type, to be interpreted as + specified in the documentation for the Socket_Access_Control enum. </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Netmask" value="2"> + </arg> + <arg direction="in" name="offset" type="t"> <tp:docstring> - May only be used on IP sockets. The associated variant must contain - a struct Socket_Netmask_IPv4 (or Socket_Netmask_IPv6) with - signature (sy), containing the string form of an - IP address of the appropriate version, and a prefix length "n". - The socket can only be accessed if the first n bits of the - connecting address match the first n bits of the given address. + 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. </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Credentials" value="3"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The connecting process must send a single zero (NUL) byte when - it first connects, which is not considered to be part of the data - stream. If the operating system uses sendmsg() with SCM_CREDS or - SCM_CREDENTIALS to pass credentials over sockets, the connecting - process must do so if possible; if not, it must still send the - byte.</p> - - <p>The listening process will disconnect the connection unless it - can determine by OS-specific means that the connecting process - has the same user ID as the listening process.</p> - - <p>The associated variant must be ignored.</p> + </arg> + <arg direction="out" name="address" type="v"> + <tp:docstring> + The address on which the connection manager will listen for + connections for this file transfer. </tp:docstring> - </tp:enumvalue> - </tp:enum> + </arg> - <!-- Taken from org.freedesktop.Telepathy.Channel.Type.Tubes --> - <tp:mapping name="Supported_Socket_Map"> - <tp:docstring>The supported socket address and access-control types - for tubes. See GetAvailableStreamTubeTypes.</tp:docstring> - <tp:member name="Address_Type" type="u" tp:type="Socket_Address_Type"/> - <tp:member name="Access_Control" type="au" - tp:type="Socket_Access_Control[]"/> - </tp:mapping> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + 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: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. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> - <method name="AcceptFile"> + <method name="OfferFile"> <tp:docstring> - Accept a file transfer that's in the "local pending" state. The file - transfer becomes open after this method is called. + Offer a file transfer that's in the "not offered" state. The file transfer + becomes remote pending after this method is called. </tp:docstring> <arg direction="in" name="address_type" type="u" tp:type="Socket_Address_Type"> <tp:docstring> @@ -353,8 +371,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> <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 "not offered" state, or there isn't + enough information for the transfer to start. </tp:docstring> </tp:error> </tp:possible-errors> @@ -381,10 +399,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <signal name="TransferredBytesChanged"> <tp:docstring> - Emitted when the number of transferred bytes changes. This will not change - with every single byte change. Instead, the most frequent this signal will - be emmitted is once a second. This should be sufficient, and the - TransferredBytes property should not be polled. + 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. </tp:docstring> <arg name="count" type="t"> <tp:docstring> |