Refactor and clean up platform api

Registered by Thomas Voß

Refactor and clean up platform api to adhere to conventions and guidelines, and include new features if necessary.

Blueprint information

Status:
Started
Approver:
Loïc Minier
Priority:
High
Drafter:
Thomas Voß
Direction:
Approved
Assignee:
Ricardo Mendoza
Definition:
Approved
Series goal:
Accepted for saucy
Implementation:
Good progress
Milestone target:
milestone icon ubuntu-13.05
Started by
Thomas Voß

Related branches

Sprints

Whiteboard

Refactor and clean up platform api to adhere to conventions and guidelines, and include new features if necessary.

* Iteration of the client API adhering to the stated conventions and guidelines, most notable:
  * Adhere to glib coding convention, but keep it plain C (as opposed to GObject).
  * Do we want ref/unref?
  * Avoid boxed types
* Stable API/ABI definitions (with version)
* Define the set of functionality modelled by the platform API, proposal:
  * Application model including lifecycle and UI/Input access

Notes from UDS-1303:

Low level common API between form-factors
Access to system services
Access to surfaces (EGL native window tile) -- currently implemented with SurfaceFlinger, but will switch to MIR
Access to input
Sensors
    Accelerometers
    Ambient light sensors
    GPS
    Proximity sensors

Common service to handle the sensors for other GNU/Linux OSes?

Some APIs will be external like libjpeg or libpng, others will clearly be in the Ubuntu Platform API e.g. surfaces or input
Good way to split could be whether the API accesses a running service or not

There might be APIs like MIR that we want to expose because they are very public APIs like XOrg is used in many projects

Will have to support backwards compatibility as well

Should we break down the API and runtimes in smaller pieces or have a single big library?
With one big library, we might waste memory and it might be harder to keep backwards-compatibility

Current Platform API was designed to e.g. replace Surface Flinger with MIR
Michael and Thomas think that apps shouldn't know about MIR at all

How do we define and evolve the API?
Should be on developer.u.c
Meetings? review board?

Preference for review board

Mailing-list? would want a new ubuntu-platform@ list

How do we share the APIs with the world?
There's a case for application developers, want to reach out to them to design APIs which are suitable for reference use cases (e.g. to allow development of a Skype-like app, we need this and that API)
There's another case for reaching out to other platforms to share maintenance of the lower layers -- implementation -- e.g. communicate and promote Geoclue improvements to GNOME, Firefox OS, BB folks etc.

Proposal for renaming and adjustments to the directory layout:
* include
  * [d] ubuntu:
    * status.h: Status & error codes that are used by all components
    * unit.h: Unit enumeration to be used by APIs that need to express physical quantities
    * [d]: application: All interfaces meant to be consumed by ordinary applications:
      * archive.h: Defines the interface to an archive that allows apps to store their state persistently across runs.
      * id.h: Defines types and functions to handle an application's unique id.
      * lifecycle_delegate.h: Contains function prototypes and structures to wire up apps to the lifecycle state machine
      * options.h: Defines types and functions to parse platform API specific command line parameters
      * [d] location: Types, functions and constants for accessing the location service
      * [d] sensors: Types, functions and constants for accessing the sensors service
      * [d] ui: Types, functions and constants for access the graphics subsystem
        * [d] input: Types, functions and constants to handle input events
          * [d] key: Types, functions and constants to handle key events
          * [d] motion: Types, functions and constants to handle motion events

(Naming) convention (should follow glib's naming convention):
  * Types are CamelCased
  * All types should be opaque to enable maximum ABI stability
  * Types should be accompanied by reference counting functions: *_ref/*_unref
  * Function names use underscores, e.g., my_awesome_function()
  * Namespacing of functions and types follows the directory structure presented before:
    * Directories above the current are collapsed to the first character for types and function names, with ubuntu being abbreviated to u_/U by default, e.g.: UbuntuApplicationLocationService should be typedef'd to UALocationService and the respective functions defined on it should be named ua_location_service_start_session().

(?)

Work Items

Work items for ubuntu-13.04-month-6:
[thomas-voss] Diagram showing how the platform API is connected with our platform: DONE
[thomas-voss] Make sure the doxygen output is published together with the api: INPROGRESS
[lool] Request ubuntu-platform@ mailing-list: DONE
[ricmm] Adjust naming scheme to draft proposal: DONE
[ricmm] Clean up directory structure: DONE
[ricmm] Move implementation bits for Android side around to account for naming/directory changes: DONE
[ricmm] Adjust QtUbuntu QPA to account for naming/directory changes: DONE
Provide a dummy implementation to enable working on the desktop: TODO
Adjust application manager interface to account for HUD requirements: TODO
Provide a BAMF-based implementation of the application manager interface: TODO
Ensure multiple API and ABI versions are parallel installable: TODO

Dependency tree

* Blueprints in grey have been implemented.