libsocialweb
===

A personal social data server.

Core
~~~~

libsocialweb (referred to as lsw in this document) comprises of a core daemon
process that can load in multiple modules.

The lsw core sits on the dbus at the well known name org.gnome.libsocialweb.
The core object sits on the bus at /org/gnome/libsocialweb and implemented
the org.gnome.libsocialweb interface.

This interface has the following methods:

org.gnome.libsocialweb (TODO: Rename to .Core)

GetServices -> returns the set of available services

TODO: Add ServiceAdded signal since we now monitor for services)

TODO: Add GetServicesByStaticCapability

HideItem - LEGACY - DEPRECATED DO NOT USE -> Use Banish interface on service
OpenView - LEGACY - DEPRECATED DO NOT USE -> Use Query interface on service


Services
~~~~~~~~

The service names returned by GetServices can then be mapped to service
objects sitting on the dbus. These services have the object path:

/org/gnome/libsocialweb/Service/<service name>

The service objects are provided by the loaded backends. Each service must
implement the org.gnome.libsocialweb.Service interface.

This has the following methods:

CredentialsUpdated - Used by web service configuration to indicate to the
service that is must update it's credentials. Not needed to usual client use.

GetDynamicCapabilities -> returns the set of variable capabilities for the
service - these are capabilities that can vary over time based on whether the
service is configured, available or use control

GetStaticCapabilities -> returns the set of fixed capabilities for the service -
these represent what type of functionality the service supports when fully
configured and available.


Signals:

CapabilitiesChanged -> fired with the new set of dynamic capabilities
UserChanged - ???

Available capabilities:
========= ============

can-verify-credentials - static - means that credentials-invalid and
credentials-valid dynamic caps are available

can-update-status - static - this service has the StatusUpdate interface
                  - dynamic - this service is able to accept status updates on
                              the StatusUpdate interface

can-request-avatar - static - this service has the Avatar interface
                   - dynamic - this service is able to accept avatar requests
                               on the Avatar interface

can-geotag - static - this service has the StatusUpdate interface and
                      potentially supports sending latitude/longitude in the
                      status update
           - dynamic - this service is able to accept the geotag'ed status
                       updates

is-configured - dynamic - all necessary configuration steps for the service
                          have been completed. The service may still have
                          invalid credentials or unable to work so the other
                          dynamic caps must be checked.

credentials-invalid - dynamic - the provided credentials are invalid
credentials-valid - dynamic - the provided credentials have been checked and
                              are correct


TODO: rename can-update-status static to has-status-update-interface
      rename can-request-avatar static to has-request-avatar-interface
      rename can-geotag static to can-status-update-with-geotag
      add has-query-interface static

StatusUpdate interface
============ =========

This interface should only be used if the static caps indicate that it is
present and the dynamic caps indicate it is available.

Methods:

UpdateStatus - updates the status for the service with the given message and
               optional string hash of parameters. Use latitude and longitude
               parameters if the can-geotag dynamic cap is set

Signals:

StatusUpdated - fired if the call to update the status has finished with a
                boolean parameter to indicate success

Avatar interface
====== =========

This interface should only be used if the static caps indicate that it is
present and the dynamic caps indicate it is available.

Methods:

RequestAvatar - asks the service to download the user's own avatar

Signals:

AvatarRetrieved - fired when the avatar has been successfully downloaded, the
                  paramater is the local filename for the avatar


PhotoUpload interface
=========== =========

TODO

Query interface
===== =========

TODO


Defined Keys
==

id

Globally unique identifier for this item.  If the service provides a ID but it
isn't globally unique then it should be made so somehow, for example by using
the item's URL instead of numeric ID.

url

The URL of the item for viewing online.

date

The date the item was created in HTTP "Date" format, i.e. "Sun, 06 Nov 1994 08:49:37 GMT".

content

The textual content of the item.  For blog posts this will be a summary, for
Twitter posts this will be the post, for Flickr this will be the description.

author

The name of the author of the item.

authorid

The service ID of the author of the item.

authoricon

Path to a local copy of the item's author's avatar.

title

The title of the item.

thumbnail

Path to a local copy of the item's graphical representation.

cached

Set if the item was retrieved from the local cache.

Bonus extra keys
==

location

Free-form location string.

latitude, longitude

Accurate location, in decimal coordinates.