[Portland] Summarize current plan?

[Bryce Harrington]

On Sun, Mar 12, 2006 at 10:19:46AM -0600, Jeremy White wrote:
> Specifically, the entire dapi module is largely unmotivated,
> and I think a STATUS or README should be added to the
> dapi/ directory asap.  (I know that the high level README just points
> to the Wiki, but afaict, the Wiki has no doco on dapi
> itself).
> 
>   1.  What is the dapi?
>   2.  Am I meant to bundle it with my app, or
>   3.  How do I link to and invoke the API?
>   4.  What is here, and where is it going?


Hiya,

Here is a short README to try to address the above points.  If this
looks ok, could someone add it to CVS?

Bryce

== README ==

The Portland Project Desktop API (DAPI)
=======================================
DAPI is a general purpose desktop API that allows uniform access to
desktop functionality like sending email, turning screensavers on/off,
opening urls, and so forth.  These are done in different ways, depending
on the user's distro and desktop environment; DAPI gives software
developers a single, uniform way to perform them.

The main motivation for DAPI is to simplify ISV's lives.  We want to see
more commercial-class software available for the Linux desktop, but
recognize that the vast array of choices available to the Linux user
presents the ISV with the problem of how to support all these different
ways of doing things?  With DAPI, we plan to address this problem by
giving the ISV a convenience library that wrappers common functionality
they need, that is not yet standardized across desktop environments.

DAPI is implemented as a daemon that runs on the user's desktop and
allows applications to invoke desktop functions through an API.  


Usage
=====
There are two ways an ISV can employ DAPI:  Bundling it with your app,
or linking to a separately installed copy (such as provided with the
user's Linux distro).  Currently (March 2006), no distros ship DAPI, so
you will probably want to consider bundling it along with your app.

DAPI consists of two components: A daemon, and a library (libdapi.la)
that links to the application.  The library handles the IPC
(socket) communication with the daemon and implements the API.

There are several different "flavors" of daemons, each particular to a
given desktop environment (dapi_kde, dapi_generic, etc.), but they all
provide the same API.  This way, once you link the library in, you can
communicate with any daemon.

The doc/ directory contains a description of the implemented calls.
Also, the tests/ directory will serve as a set of basic examples on
using the library.  Other directories contain the daemon
implementations.


Future
======
DAPI is very much an early work in progress, and is still in 'prototype'
stage, so please expect that lots *will* change.  We hope to expand the
functionality to include much more of what ISV's need, so if something
appears to be missing, please let us know (patches welcome too!)

The two important things missing are not requiring the strict ordering
on the wire and transferring&caching data instead of doing separate call
for each of them like the button order call does now.  A lot of the stuff
is autogenerated in lib/gen/, so adding new calls or even doing things
like changing the transport mechanism shouldn't be that difficult.

The plan is for the desktop environments to provide their own daemon
implementations, with applications including only the generic daemon to
use if no other daemon is already running.

Email - portland at lists.freedesktop.org
    Subscribe:  http://lists.freedesktop.org/mailman/listinfo/portland
        Archives:   http://lists.freedesktop.org/archives/portland/

        Web - http://freedesktop.org/wiki/Portland