[Telepathy] File Sharing Utility

Fri Apr 10 04:14:14 PDT 2009

It might be more convenient to include the whole spec over here. Here
it goes (spacing done to improve view ability):

org.freedesktop.Telepathy.Connection.Interface.FileSharing.DRAFT

Implementations of this interface must also implement:
   * org.freedesktop.Telepathy.Connection

An interface on connections to support protocols which allow users to
designate a set of files as available for retrieval by other users of
their choosing. Other features specified by this interface include
file metadata, revisions, and download mirrors.

Methods:

	CreateFileListing ( s: Title, s: File_Listing, s: Description)-> b

	In order to be able to publish a file one should have a File_Listing
node. Here the Discription parameter is optional. Returns whether the
File_Listing was created ('true') or not ('false').

	Parameters

	Title - s
		This will be the title of the File_Listing.

	File_Listing - s
		This is how the File_Listing of the user will be referenced.

	Discription - s
		This is optional and can be use to give the discription of the
File_Listing that is being created.

	Returns

		Returns 'true' if the File_Listing was created and 'false' if it was not.	

	Possible Error	

	org.freedesktop.Telepathy.Error.Disconnected
		The connection is not currently connected and cannot be used. This
error may also be raised when operations are performed on a Connection
			for which StatusChanged  has signalled status Disconnected for
reason None.

	AddSubSection ( s: Title, s: File_Listing_Parent, s:
File_Listing_Derived, s: Description) -> b

	This method is called in order to add a SubSection
(File_Listing_Derived) to an already existing File_Listing
(File_Listing_Parent). This method returns whether the creation of the
SubSection was successful ('true') or not ('false').

	Parameters

	Title - s
		This will be the title of the subsection.

	File_Listing_Parent - s
		This is how the repository of the user will be referenced.

	File_Listing_Derived - s
		This is how the SubSection will be referenced.

	Discription - s
		This is optional and can be use to give the discription of the
SubSection that is being created.

	Returns

		Returns 'true' if the SubSection was created and 'false' if it was not.	

	Possible Error	

	org.freedesktop.Telepathy.Error.Disconnected
		The connection is not currently connected and cannot be used. This
error may also be raised when operations are performed on a Connection
			for which StatusChanged  has signalled status Disconnected for
reason None.

	org.freedesktop.Telepathy.Error.InvalidHandle
    		The File_Listing_Parent specified is unknown on this channel or
connection. (generic description)

	org.freedesktop.Telepathy.Error.PermissionDenied
    		The user is not permitted to perform the requested operation.
(generic description)

	SuscribeList ( s: File_List, s: Subscription_Type, s: Subscription_Depth) -> b

	This method is called when one wants to suscribe to a File_List.
This method returns whether the subscription was successful ('true')
or not ('false').
	note: "no-ops" for AIM

	Parameters

	File_List - s
		This is the File_List user wants to subscibe.

	Subscription_Type - s
		This gives the subscription type.

	Subscription_Depth - s
		Since a pubsub FileListing might have many SubSections,therefore
this parameter gives the depth a user want to subscribe to.

	Returns

		Returns 'true' if the subscription was done and 'false' if it was not.	

	Possible Error	

	org.freedesktop.Telepathy.Error.Disconnected
		The connection is not currently connected and cannot be used. This
error may also be raised when operations are performed on a Connection
			for which StatusChanged  has signalled status Disconnected for
reason None.

	org.freedesktop.Telepathy.Error.InvalidHandle
    		The File_List specified is unknown on this channel or
connection. (generic description)

	UnSuscribeList ( s: File_List) -> b

	This method is called when one wants to unsuscribe to a File_List.
This method returns whether the subscription was successful ('true')
or not ('false').
	note: "no-ops" for AIM

	Parameters

	File_List - s
		This is the File_List user wants to unsubscibe from

	Returns

		Returns 'true' if the unsubscription was done and 'false' if it was not.	

	Possible Error	

	org.freedesktop.Telepathy.Error.Disconnected
		The connection is not currently connected and cannot be used. This
error may also be raised when operations are performed on a Connection
			for which StatusChanged  has signalled status Disconnected for
reason None.

	org.freedesktop.Telepathy.Error.InvalidHandle
    		The File_List specified is unknown on this channel or
connection. (generic description)

	PublishFile ( s: File_List, s: Filename, q: ItemId, as: Metadata, s:
Mirrors) -> b

	This method is called in order to to add a file to the File_List of
published files. This method returns whether the file was published
successfully 	('true') or not ('false').

	Parameters

	File_List - s
		This is the File_List user wants to publish file to.

	Filename - s
		This is the FileName user want to publish.

	ItemId - q
		This Id is used to create more than one version of the same file.

	Metadata - as
		This list all the metadata about the file which includes
Size,Modified,CheckSum,Ckecksumtype and Mime.

	Mirrors	- s
		This list the mirrors from where the file can be fetched.

	Return
		Returns 'true' if the Filename was published and 'false' if it was not.

	Possible Error	

	org.freedesktop.Telepathy.Error.Disconnected
		The connection is not currently connected and cannot be used. This
error may also be raised when operations are performed on a Connection
			for which StatusChanged  has signalled status Disconnected for
reason None.

	org.freedesktop.Telepathy.Error.InvalidHandle
    		The File_List specified is unknown on this channel or
connection. (generic description)

	org.freedesktop.Telepathy.Error.PermissionDenied
		The user is not permitted to perform the requested operation.
(generic description)

	DeleteRevision ( s: File_List, q: File_Item_Id) -> b

	This method is called in order to delete a revision from the list of
published files on a File_List. This method returns whether the file
was 		deleted successfully ('true') or not ('false').

	Parameters

	File_List - s
		This is the File_List which is holding the file with the Item_Id
equal to File_Item_Id

	File_Item_Id - q
		This is the ItemId of the FileName that has to be deleted

	Return
		Returns 'true' if the FileItemId was deleted and 'false' if it was not.

	Possible Error	

	org.freedesktop.Telepathy.Error.Disconnected
		The connection is not currently connected and cannot be used. This
error may also be raised when operations are performed on a Connection
			for which StatusChanged  has signalled status Disconnected for
reason None.

	org.freedesktop.Telepathy.Error.InvalidHandle
    		The File_List specified is unknown on this channel or
connection. (generic description)

	org.freedesktop.Telepathy.Error.PermissionDenied
		The user is not permitted to perform the requested operation.
(generic description)

	MakeRevision ( s: File_List, s: Filename, q: ItemId, as: Metadata, s:
Mirrors) -> b

	This method is called in order to make a revision to an existing file
on File_List. Use a different ItemId than the original file. This
method 		returns whether the file was revised successfully ('true') or
not ('false').

	Parameters

	File_List - s
		This is the File_List on which the file user want to make revision
to is listed.

	Filename - s
		This is the FileName user want to publish.

	ItemId - q
		This Id is used to create more than one version of the same file.

	Metadata - as
		This list all the metadata about the file which includes
Size,Modified,CheckSum,Ckecksumtype and Mime.

	Mirrors	- s
		This list the mirrors from where the file can be fetched.

	Return
		Returns 'true' if the FileName was published and 'false' if it was not.

	Possible Error	

	org.freedesktop.Telepathy.Error.Disconnected
		The connection is not currently connected and cannot be used. This
error may also be raised when operations are performed on a Connection
			for which StatusChanged  has signalled status Disconnected for
reason None.

	org.freedesktop.Telepathy.Error.InvalidHandle
    		The File_List specified is unknown on this channel or
connection. (generic description)

	org.freedesktop.Telepathy.Error.PermissionDenied
		The user is not permitted to perform the requested operation.
(generic description)

	SetPermissions ( s: File_List, u: User_Handle, s: Affilation) -> Nothing

	This method is called in order to set permissions for users regarding
a File_List owned by an owner.  This method returns whether
permissions were set successfully ('true') or not ('false').

	Parameter

	File_List - s	
		This is the File_List owner want to change permission of.

	UserHandle - u
		UserHandle of the user whose permission/affilation are being changed.

	Affilation - s
		This is the permission that will be set for the User_Handle

	Return
		Nothing

	Possible Error

	org.freedesktop.Telepathy.Error.Disconnected
		The connection is not currently connected and cannot be used. This
error may also be raised when operations are performed on a Connection
			for which StatusChanged  has signalled status Disconnected for
reason None.

	org.freedesktop.Telepathy.Error.InvalidHandle
    		The File_List specified is unknown on this channel or
connection. (generic description)

	org.freedesktop.Telepathy.Error.PermissionDenied
		The user is not permitted to perform the requested operation.
(generic description)

	GetRepoList( u: User_Handle ) -> as

	This method is called to request the File_list which are hosted by User_Handle.

	Parameter

	User_Handle - u
		The Contact_Handle of the user whose list of hosted File_List is
being requested.

	Return
		Returns an array of strings where each string represents a File_List
hosted by the User.

	Possible Error

	org.freedesktop.Telepathy.Error.Disconnected
		The connection is not currently connected and cannot be used. This
error may also be raised when operations are performed on a Connection
			for which StatusChanged  has signalled status Disconnected for
reason None.

	org.freedesktop.Telepathy.Error.InvalidHandle
    		The User_handle specified is unknown on this channel or
connection. (generic description)

	org.freedesktop.Telepathy.Error.PermissionDenied
		The user is not permitted to perform the requested operation.
(generic description)

	GetFileList( s: File_List, u: User_Handle ) -> as

	This method is called to request the list of files in a File_List
hosted by the user with Contact_Handle as User_Handle.

	Parameter

	File_List - s
		This is the File_List whose list of included file is being requested

	User_Handle - u
		The Contact_Handle of the user whose list of hosted File_List is
being requested.

	Return
		Returns an array of strings where each string represents a Filename
hosted by the User. If their is a Subsection at the same hierarchy
level, it is aso retturned in this array.

	Possible Error

	org.freedesktop.Telepathy.Error.Disconnected
		The connection is not currently connected and cannot be used. This
error may also be raised when operations are performed on a Connection
			for which StatusChanged  has signalled status Disconnected for
reason None.

	org.freedesktop.Telepathy.Error.InvalidHandle
    		The File_List/User_handle specified is unknown on this channel
or connection. (generic description)

	org.freedesktop.Telepathy.Error.PermissionDenied
		The user is not permitted to perform the requested operation.
(generic description)

	RequestFile(s: File_List, u: User_Handle, s: Filename) -> nothing

		In order to request for a file to be sent one must request a
FileSharing channel for the mirror hosting the file including the
following mandatory 		properties (Protocol, FileId). After this
RequestFile is called to to configure the socket that will be used to
complete this operation.

	Parameter	

		File_List - s
			This is the File_List whose list of included file is being requested

		User_Handle - u
			The Contact_Handle of the user whose list of hosted File_List is
being requested.

		Filename - s
			File which is being requested to be sent

	Possible Error

	org.freedesktop.Telepathy.Error.Disconnected
		The connection is not currently connected and cannot be used. This
error may also be raised when operations are performed on a Connection
			for which StatusChanged  has signalled status Disconnected for
reason None.

	org.freedesktop.Telepathy.Error.InvalidHandle
    		The File_List/User_handle specified is unknown on this channel
or connection. (generic description)

	org.freedesktop.Telepathy.Error.PermissionDenied
		The user is not permitted to perform the requested operation.
(generic description)

Signals

	NotificationChange( s: File_List, s: File_List_Title, s:
Filename_Modified, s: Description, as: Metadata, s: Mirror)

	This signal is sent to every user which is subscribed to the
File_List in which the change has been made.

	Parameter

	File_List - s
		This is the File_List on which the change has been done

	File_List_Title - s
		This is the title of the File_List which has been modified

	Filename_Modified - s
		This is Filename on File_List which has been changed

	Discription - s
		This is the Discripton of the File_List which has been modified

	Metadata - as
		This is the Metadata of the file which has been added/deleted

	Mirror - s
		Mirror of the modified file.

Structure types

	Metadata ( u: Size, s: Modified, s: CheckSum, s: Checksumtype, s: Mime )

	This represents all the information needed about the file.

	Members

	Size - s
		Size of the file in KB

	Modified - s
		The last modified time of the revision

	CheckSum - s
		Checksum of the file

	Checksumtype - s
		The type of CheckSum used

	Mime - s
		Mime Type of the file

On Fri, Apr 10, 2009 at 3:50 AM, kartik rustagi <kashes911 at gmail.com> wrote:
> Changes suggested to the specification have been made. This
> specification will now work for XMPP and AIM (atleast). For the
> requirement of AIM I have referred :
> http://dev.aol.com/aimclient/OpenAIM168/java-docs/index.html
>
> The modified spec can be looked up at:
> http://pastebin.com/f3222e122
>
> I am waiting for speedy recommendations as I am following a
> rigid(almost) timeline.
>
> Thanks
> Kartik Rustagi
>
> On Tue, Apr 7, 2009 at 3:40 AM, kartik rustagi <kashes911 at gmail.com> wrote:
>> I have written the first draft of the File Sharing Specification.I
>> will request you to kindly review this and suggest changes so that I
>> can finalise this and move forward with the implementation.
>>
>> The specification can be found at:
>>
>> http://pastebin.com/f11d72989
>>
>>
>> And even poorly formated version at :
>>
>> http://wiki.sugarlabs.org/go/0-th
>>
>> I again request to review this as soon as possible (I am following a Time Line)
>>
>>
>> The XEP-0214 specification can be found on :
>> http://xmpp.org/extensions/xep-0214.html
>>
>>
>> Regards
>> Kartik Rustagi
>>
>