JobViewServer specification proposal
Rafael Fernández López
ereslibre at kde.org
Sat Apr 5 03:06:16 PDT 2008
At this point I plan to do a really verbose explanation of the D-Bus interface
that we designed with everybody in mind. Obviously this interface will
probably need improvements and corrections. After designing this interface,
we implemented it, so we have a real and working example to look at.
The main idea of this approach is that we have a daemon that implements the
JobViewServer implementation which is registered only once on the bus. After
that, applications or libraries (GIO/KIO, whatever) can call to that
interface to register a new job. This interface will return a D-Bus path with
the newly created job path, that has been registered on the bus and that
implements the JobView interface (its path into the bus will be something
like '/JobViewServer/JobView_k', where k is the number of job), which has
lots of state methods.
When the job has been registered our application or library will make calls to
the already registered jobs, resulting in changes on our running server.
Detailed description of interfaces
· object_path requestView(string appName,
This is the only method of this interface. It asks the server to
register a new job for the application @p appName, with icon
@p appIconName, and @p capabilities. The new job object path will be
returned from the service. This path, as said before, is of the
Capabilities is a bitfield, which can contain:
· 0x0001 => user should be able to cancel the job
· 0x0002 => user should be able to suspend/resume the job
For showing what our implementation does at the moment when calling this
method with parameters 'Nautilus', 'nautilus', 0, we get the next:
· void terminate(string errorMessage)
This method forces the job to be removed from the service with a certain
@p errorMessage. If this message is an empty string, then we assume
there was no error.
As an example, on our case, this method becomes called always that a job
finished. When its execution was successfull we send an empty string
here, in other case, we send the error message cause.
So to sum up, this method is what tells the service to unregister the
job from the bus.
· void setSuspended(bool suspended)
Suspends or resumes the job depending on @p suspended. Of course this
method can only be called if the capability of this job contains a
0x0002 when this job was registered on the bus.
· void setTotalAmount(uint64 amount, string unit)
This method sets the total amount of the work. The parameter @p amount
sets the amount itself, while the @p unit parameter can have certain
values (not i18n at this point):
· "files": how many files the job has to treat.
· "folders": how many folders the job has to work with.
· "bytes": how many bytes the job has.
· "contacts": how many contacts .
· "mails": how many mails the job has to work with.
Depending on our needs, and if some application asks it, we can add more
strings at this point. For example, a schedule application may
need "events" when importing/exporting events from/to a file.
· void setProcessedAmount(uint64 amount, string unit)
Same as the above but with the processed amount.
Note: with this two methods, we can get the next example
Note 2: we added those strings instead of i18n them because of problems
with @p amount and plurals on some languages. For this reason we decided
to use a list of 'hard-coded' units, being easy to expand, and
translations can be perfect.
· void setPercent(uint percent)
Sets the percent finished at the moment of the overall process.
You can get a result as the next snapshot:
· void setSpeed(uint64 bytesPerSecond)
For I/O operations we can set the bytes per second of the operation.
The result can be seen here:
· void setInfoMessage(string message)
Sets the information message for this job. For example, "Copying",
I took a screenshot of our implementation that you can see here:
· bool setDescriptionField(uint number,
This method can set description fields. They are registered by a
@p number. It is important to point out that if you want to register
for example number '2', there is no need of having registered first
number '1' or '0'. This lets us to write easier code on the caller since
we do not have to track the ids.
On the JobViewServer this will make a new string to be shown, of the
type: "Name: Value". For example: "From: http://www.whatever.com" when
downloading a file.
Note: This is implemented internally but not visible at the moment on
the kuiserver GUI.
· void clearDescriptionField(uint number)
If we want to remove a description field, we only have to call to this
method with the correct @p number parameter.
Now, since from the job server service we have the ability to pause/resume
or cancel jobs (depending on the jobs capabilities), we need to include
signals to the JobView interface that will be emitted when the user
performed an action on the server (on the window you saw on previous
screenshots you can select a job [a row], and then click on 'Cancel' or on
· void suspendRequested() [signal]
When we click on "Pause", this signal is emitted, and should force the
job to be suspended.
· void resumeRequested() [signal]
This signal is emitted when "Resume" is clicked on a previous suspended
· void cancelRequested() [signal]
This signal forces the job to cancel its work-in-progress. There is no
need to unregister the job where this signal is emitted. In theory, the
method terminate() should be called afterwards, where we can unregister
the object path of this being-cancelled job.
On the example shown here:
you can see two registered jobs, one is Nautilus and the other is
Konqueror. For example, on the Konqueror row, you can see that we only can
see the processed amount of bytes.
It is important to note that there is no need of having all information
set (of course). The server should react to very different knowledge: for
example knowing total, processed and speed, only processed and speed, only
total and processed...
We get very big benefits by using this interface. Our implementation can ask
the user whether he/she wants jobs to be shown on separate or on the same
window, for example.
Another really great thing that can be seen here, is that it will be running
the server of the current being run desktop. That means, that if I am using
Konqueror into a Gnome session, and I start to download a file, the progress
dialog of Gnome will be shown, instead of the KIO one, making this
cross-desktop and GUI integrated into the current desktop.
Comments ? Ideas ? Suggestions ?
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: not available
Size: 197 bytes
Desc: This is a digitally signed message part.
Url : http://lists.freedesktop.org/archives/xdg/attachments/20080405/8a7f2a47/attachment.pgp
More information about the xdg