[xdg-draft] JobViewServer

[Kevin Krammer]

On Wednesday 20 February 2008, Rafael Fernández López wrote:
> Hi all,
>
> Kevin and me have been working on a specification for freedesktop of the
> JobViewServer (known on KDE as kuiserver).

Great!

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

Nitpick: D-Bus ;)

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

Do I assume correctly that this interface is the one a job talks to, i.e. call 
direction is job -> view?

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

Based on the above assumption:
"terminate" sounds like a command, I'd rather call it "terminated".
Maybe even split in "finished" (success) and "terminated" (failure)

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

IMHO you should specify a D-Bus error which will be "thrown" if the method is 
called on a view not created with the respective capability.

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

Maybe also make this dependent on some unit?
Like "x files per second" e.g. for a tool which renames audio files based 
their metadata.

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

If there is more than one reason why the call could fail, it should 
rather "throw" D-Bus errors so the caller can handle them accordingly.

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

I'd rather suggest adding a clearDescriptionField(uint32) method.

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

What about a variant map which at least includes the capabilities but which 
could already include things like total amount and descriptions, saving setup 
roundtrips?

Cheers,
Kevin

-- 
Kevin Krammer, KDE developer, xdg-utils developer
KDE user support, developer mentoring
-------------- 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/ecbd172d/attachment.sig>