[xdg-draft] JobViewServer

[Rafael Fernández López]

Hi all,

Kevin and me have been working on a specification for freedesktop of the 
JobViewServer (known on KDE as kuiserver).

There are two main parts on the communication: jobs themselves, what can be 
considered the clients, and the server.

The server should be a DBUS autostart service, so when a job asks for this 
service and no server is running, automatically one of the available services 
is started.

> JobView < (org.kde.JobView) - (org.freedesktop.JobView)

- void terminate(string errorMessage)
The job has finished (correctly or aborted). errorMessage will be a null 
string if the job did finish correctly, and will contain the string reason of 
why the job did finish unexpectedly if the job did not finish correctly.

- void setSuspended(bool suspended)
The job has been suspended or resumed. This method will only be called if the 
job had those capabilities (@see requestView() on the JobViewServer). 
suspended parameter will determine if the job is suspended or resumed, 
depending on its value, true or false, respectively.

- void setTotalAmount(uint64 amount, string unit)
Informs about the total amount of work the job has to do. unit for instance 
could be "Mb" when downloading a file, "Contacts" when importing contacts on 
a instant messaging app. amount is the number of total elements to process. 
unit parameter should not contain whitespaces at the beginning or at the end.

- void setProcessedAmount(uint64 amount, string unit)
Sets the amount of already processed elements. Parameters have the same effect 
as on the previous call.

- void setPercent(uint32 percent)
Sets the percent finished of the job until now.

- void setSpeed(uint64 bytesPerSecond)
If applicable, sets the current speed of the job in bytes per second. Useful 
when the job is talking about I/O operations.

- void setInfoMessage(string message)
Tells an informative message of what the job is working on. Useful values 
could be for instance "Copying", "Moving", "Importing Contacts", "Burning ISO 
image"...

- bool setDescriptionField(uint32 number, string name, string value)
Sets extra information about the job. number parameter sets the ID for the 
description field. name specifies what is the description field name, and 
value which value it has. If the description field has been correctly saved, 
then true is returned, false otherwise. Depending on the implementation, it 
can force number be as much 2, for instance, but we encourage to freely let 
the interface user set the number he/she wants. The name and value strings 
can be changed by a later call to setDescriptionField with the same number 
parameter. For instance you could do:

setDescriptionField(1, "Contact", "John Whatever");
setDescriptionField(1, "Contact", "Alice Whatever");

If you want to remove a description field, you only will need to set name and 
value to null strings, and the server should remove the information.

- void suspendRequested() [signal]
This signal is called when a suspend event is requested by the Server. The job 
needs to be connected to this signal if it wants to react to this event. Note 
that the job needs the capabilities to be suspended/resumed (@see 
requestView() on the JobViewServer).

- void resumeRequested() [signal]
Same as the previous signal, but with a resume event. Note that the job needs 
the capabilities to be suspended/resumed (@see requestView() on the 
JobViewServer).

- void cancelRequested() [signal]
This signal will only be emitted if the job has been manually cancelled. Note 
that the job needs the capabilities to be cancelled (@see requestView() on 
the JobViewServer).


> JobViewServer < (org.kde.JobViewServer) - (org.freedesktop.JobViewServer)

- objectPath requestView(string appName, string appIconName, uint32 
capabilities)
The job requests to be shown with appName, for instance "Kopete", appIconName, 
for example "kopete" and with certain capabilities. This last parameter 
supports bit operations. Meaning:

0x0001 => user should be able to cancel the job
0x0002 => user should be able to suspend/resume the job

The return value is an object path that determines the interaction with the 
job itself until it finishes its execution.


Before presenting this document to xdg, we need to have an implementation, and 
that is what I'm going to do with kuiserver from now. I'm going to adapt it 
to this specification, and after having it, we will present this xml 
interface to the freedesktop community.

Before getting hands to work, I'd love to know if you have comments on the 
interface, or if you think something could be improved before working on the 
code itself.


Bye and thanks,
Rafael Fernández López

GPG Fingerprint: B9F4 4730 43F8 FFDD CC5E BA8E 724E 406E 3F01 D070
-------------- next part --------------
A non-text attachment was scrubbed...
Name: org.kde.JobViewServer.xml
Type: text/xml
Size: 696 bytes
Desc: not available
URL: <http://mail.kde.org/pipermail/kde-core-devel/attachments/20080220/92ff4e47/attachment.xml>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: org.kde.JobView.xml
Type: text/xml
Size: 1912 bytes
Desc: not available
URL: <http://mail.kde.org/pipermail/kde-core-devel/attachments/20080220/92ff4e47/attachment-0001.xml>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part.
URL: <http://mail.kde.org/pipermail/kde-core-devel/attachments/20080220/92ff4e47/attachment.sig>