JobViewServer specification proposal

Sat Apr 5 03:06:16 PDT 2008

Hi all,

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.

General approach
================

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
==================================

· org.freedesktop.JobViewServer
    · object_path requestView(string appName,
                              string appIconName,
                              int capabilities)

      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
      form '/JobViewServer/JobView_k'.

      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:
      http://media.ereslibre.es/2008/04/kuiserver.png.

· org.freedesktop.JobView
    · 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
    http://media.ereslibre.es/2008/04/kuiserver2.png.

    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:
      http://media.ereslibre.es/2008/04/kuiserver3.png.

    · void setSpeed(uint64 bytesPerSecond)

      For I/O operations we can set the bytes per second of the operation.

      The result can be seen here:
      http://media.ereslibre.es/2008/04/kuiserver4.png.

    · void setInfoMessage(string message)

      Sets the information message for this job. For example, "Copying",
      "Moving"...

      I took a screenshot of our implementation that you can see here:
      http://media.ereslibre.es/2008/04/kuiserver5.png.

    · bool setDescriptionField(uint number,
                               string name,
                               string value)

      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
    'Pause').

    · 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 
      job.

    · 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:
    http://media.ereslibre.es/2008/04/kuiserver6.png
    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...

Big benefits
============

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
Type: application/pgp-signature
Size: 197 bytes
Desc: This is a digitally signed message part.
Url : http://lists.freedesktop.org/archives/xdg/attachments/20080405/8a7f2a47/attachment.pgp 