ApiChangesSciroccoBoraHerring

  1. API changes from Maemo 2.1 Scirocco to Maemo 3.0 Bora, and Herring
      1. still missing
    1. Introduction
    2. Hildon, Gtk, libosso (all in Herring)
      1. New Features (all in Herring)
      2. Removed Features (from Herring too)
    3. Telepathy and stuff
    4. Multimedia Changes (alsa stuff in Herring but not gstreamer update)
      1. New Features (in Herring but not tested)
    5. Games framework (not yet in Herring)
    6. Maemo AF Desktop Status Bar Plugins (in Herring)
    7. State Saving, Autosaving and Background Killing (in Herring)
    8. Connectivity (Bluetooth in Herring)
      1. Removed Features
    9. OSSO Help (in Herring)
    10. Control Panel Plugins (in Herring)
    11. Themeing
    12. Maemo AF Desktop Navigator Plugins (in Herring)
      1. New Features (in Herring)
      2. Removed Features (also from Herring)
    13. Maemo Certificate Manager (partially in Herring)
    14. X (in Herring)

API changes from Maemo 2.1 Scirocco to Maemo 3.0 Bora, and Herring

Attention, this is an unfinished draft

MoinMoinWiki Macro: TableOfContents

still missing

  • dbus: something about that?
    • same upstream version (0.61-osso13fix->0.61-osso18). According to changelogs, only bug fixes added.
  • Telepathy, Galago, ...
  • Libossomime?
  • do old status bar plugins work with the new status bar?
  • EAP gconf keys have been changed since SDK2.0
  • theming from (Johan?).
  • gstreamer

Introduction

This document describes the API related changes between Maemo 2.1 Scirocco and Maemo 3.0 Bora. The document is sectioned in such a way that the most important changes are in the first sections and changes to less used features are in the latter sections.

Hildon, Gtk, libosso (all in Herring)

Package name 2.0 2.1 3.0
hildon-libs-dev 0.12.20-1 N/A 0.14.2-1
hildon-base-lib-dev 0.9.4-1 N/A 0.10.2-1
hildon-fm-dev 0.28-2 N/A 1.9-1
libosso-dev 1.14-1 N/A 1.17-1
libgtk2.0-dev 2.6.10-1.osso21 N/A 2.6.10-2.osso13
libglib2.0-dev 2.8.6-1osso5 N/A 2.8.6-1osso7

All 2.1 applications should compile and run cleanly. There are no changes, only additions, to the public 2.1 API concerning basic Maemo features like widgets and application launching.

It is not binary compatible, however. At least hildon-fm and libhildonmenu break the compability.

New Features (all in Herring)

Hildon widget library contains a new set of widgets for selecting a color. There is a chooser widget, chooser dialog and a chooser button. There is also a new plugin widget API which the new color chooser widget set uses.

See https://stage.maemo.org/svn/maemo/projects/haf/tags/hildon-libs/0.14.2-1/doc/design/hildon-plugin-widget.txt for more information about the plugin widget

List of new headers in Hildon library: * hildon-widgets/hildon-color-chooser.h * hildon-widgets/hildon-color-chooser-button.h * NOTE: No GTK API documentation! * hildon-widgets/hildon-color-chooser-dialog.h * hildon-widgets/hildon-plugin-widget.h

Desktop files for applications contain two new fields, "comment" and "x-text-domain". The "comment"-field is a comment or a short description of the application and can be shown in e.g. tooltips or in thumb menu in addition to the application name. The "x-text-domain" is used to tell the text domain for translations. If the "x-text-domain" is not provided the "maemo-af-desktop" domain will be used. By setting this to the applications own domain it can provide the translations for the name in it's own package.

Libosso has some minor changes. The osso_time_set() now actually sends a notification about a time change (it does not change the time, however). Functions osso_display_state_on() and osso_display_blanking_pause() can return also OSSO_INVALID in case of invalid parameters.

Removed Features (from Herring too)

Function _hildon_file_system_model_load_children() is removed from the Hildon FM header "hildon-file-system-model.h". It was already commented as not for public use.

Telepathy and stuff

TODO

Multimedia Changes (alsa stuff in Herring but not gstreamer update)

Package name 2.0 2.1 3.0
osso-mediaengine N/A 1.2.12-1(w37)
libgstreamer-plugins-base0.10-dev N/A N/A 0.10.9-osso
libgstreamer0.10-dev 0.10.5-osso1 N/A 0.10.9-osso2
osso-esd 0.17-1 N/A 0.51-1
libasound2-dev - N/A 1.0.10-osso5

The multimedia framework has some updates. GStreamer has been upgraded from upstream version 0.10.5 to 0.10.9 (see the changelogs below) and a few GStreamer plugins has been added (see the list below).

Limited ALSA support has been added for better compability with 3rd party applications. ESD is still supported and used e.g. by Hildon widgets.

GStreamer changelogs: * http://gstreamer.freedesktop.org/releases/gstreamer/0.10.6.html * http://gstreamer.freedesktop.org/releases/gstreamer/0.10.7.html * http://gstreamer.freedesktop.org/releases/gstreamer/0.10.8.html * http://gstreamer.freedesktop.org/releases/gstreamer/0.10.9.html

New Features (in Herring but not tested)

The ALSA PCM plugin is described in https://garage.maemo.org/projects/dsp-alsa/. The ALSA support in Maemo includes the ALSA libraries but not ALSA plugins for the GStreamer since applications should still use the DSP PCM or DSP decoder plugins for playback.

Games framework (not yet in Herring)

Package name SDK2.0 SDK2.1rc8 SDK2.1 SDK3.0alpha
maemo-games-startup-dev 0.1.5 0.1.5 N/A 0.1.5
libsdl1.2-dev 1.2.8-10 1.2.8-10 N/A 1.2.8-13
libsdl-net1.2-dev 1.2.5-osso1 1.2.5-osso1 N/A 1.2.5-osso1

The game framework has not changed much. The maemo games startup package is still the same. SDL library uses now ALSA as the audio backend instead of the ESD.

Maemo AF Desktop Status Bar Plugins (in Herring)

TODO: does new SB support old plugins?

The Status Bar API has been altered slightly after 2.1. In 3.0 the Status Bar supports three different kind of plugins: permanent, conditional and temporal. Permanent plugins are shown all the time. Conditional and temporal plugins are shown only when a condition is fulfilled. Also, now the user is able to select plugins and change plugins' positions from Control Panel.

The plugin API contains a new optional function [plugin_name]_set_conditional() which can (will?) be used by Status Bar to set the status of the plugin. There is also a new signal hildon_status_bar_update_conditional with a boolean parameter that the plugin can send to Status Bar to update the conditional status.

There is also a new function for the temporary and conditional plugins: hildon_status_bar_item_set_button(). These plugins can leave the button widget as NULL in the initialization and set it later with the new function.

Format of the 3.0 status bar plugins' .desktop file:

[Desktop Entry]
Name=<logical name identifier>
Icon=<logical icon identifier>
Category=<permanent/conditional/temporal>, 
          the default value is permanent if the key value read fails.
X-status-bar-plugin=lib<plugin name>.so
Mandatory=<true/false>,
          if not set, the default value is false

TODO: StatusBarAPIchange Statubar plugin API

== Maemo AF Desktop Home Plugins (in Herring)==

Package name 2.0 2.1 3.0
hildon-home-dev 2.6.31-1 N/A 2.9.22.1-1

The Home plugin C API has not changed at all, but the Home now supports resizing of the plugins. The plugin can choose whether is is resizeable in X or Y direction and what is the minimum width and height of the plugin.

This new information is described in the plugin's .desktop file which has the following new format:

[Desktop Entry]
Name=<logical_name>
Comment=<engineering english name of applet>
Type=HildonHomeApplet
X-home-applet=lib<appletname>.so
X-home-applet-resizable=[XY]
X-home-applet-minwidth=width
X-home-applet-minheight=height

minwidth/minheight tells the minimum resize size allowed and resizable defines which dimensions are allowed to resize.

If the new fields are missing then the Home treats the plugin as non-resizable, i.e. old Home plugins should work with the new API flawlessly.

State Saving, Autosaving and Background Killing (in Herring)

Package name 2.0 2.1 3.0
libosso-dev 1.14-1 N/A 1.17-1
hildon-libs-dev 0.12.20-1 N/A 0.14.2-1

The state saving, autosaving and background killing API have not changed. Only addition is a nice detailed doxygen documentation about state saving and autosaving in libosso.h. A link to this new information should be provided in Maemo.org documentation.

Connectivity (Bluetooth in Herring)

Package name 2.0 2.1 3.0
osso-bttools-dev 0.34.4 N/A 0.40.3
libgwobex-dev 0.47.4 N/A 0.53
osso-gwconnect-dev N/A N/A 1.0
bluez-utils N/A N/A 3.5osso2
conbtdialogs-dev - - 1.4.1

TODO: Internet connectivity

The bluez-utils package has been upgraded to a new stable upstream version (from 2.25 to 3.5) which provides new DBUS calls to hcid.

The bluez-utils Changelog.

Removed Features

osso-bttools package provided a btname command line tool and a DBUS API for setting the BT name and BT pairing. It is now deprecated.

OSSO Help (in Herring)

Package name 2.0 2.1 3.0
libosso-help-dev 1.5.11-1 N/A 2.0.6-1

The OSSO help library has two headers: osso-helplib-private.h and osso-helplib.h. The latter one is public and has not been changed. The private version has two new functions, browser_focus_forward_backward() and browser_has_focus(). The private header file comments the content as follows:

... these are exported but intended to be used by members of the Help clan (HelpUI, !HelpTest, HelpGS) only. Therefore, incompatible changes will be mercilessly implemented, if necessary.

No changes in the Help XML document syntax etc.

Control Panel Plugins (in Herring)

Package name 2.0 SDK2.1 3.0
hildon-control-panel-dev 1.2.5-1 N/A 2.2.5-1

The Control Panel plugins are now divided into categories and the layout is constructed based on those. The named categories are: general, connectivity, personalisation and extras.

The Control Panel plugin's .desktop file with the new "categories" field:

[Desktop Entry]
Name=<logical applet name identifier>
Comment=Control Panel Applet
Type=HildonControlPanelPlugin
Icon=<logical icon name identifier>
Categories=<general/connectivity/personalisation/extras>, from which 
            the extras is the default value, in case the key value 
            read fails. 
X-control-panel-plugin=lib<applet name>.so

Old Control Panel plugins should work flawlessly and they should show up in the Extras category.

Themeing

TODO

Maemo AF Desktop Navigator Plugins (in Herring)

Package name 2.0 2.1 3.0
hildon-navigator-dev 2.6.31-1 N/A 2.9.22.1-1

The Navigator plugin API has suffered only some cosmetic changes. Mainly it seems that the includedir field in pkgconfig file was wrong and now has been corrected (the proper include directory is hildon-navigator-dev instead of hildon-navigator).

New Features (in Herring)

The pkgconfig file for Navigator has now also plugindesktopentrydir field for the plugins to acquire installation directory for the .desktop files.

There is a new widget: !HildonThumbMenuItem. It is meant for implementing a thumbable menu. It is a part of the libhildonmenu package to allow plugins to use it.

TODO: maemo-af-desktop/tn_thumbable_menu/ TODO: TaskNavigatorAPIchange

Removed Features (also from Herring)

The header file "hildon-navigator-interface.h" has been removed from the dev package. It seems that it was not meant for the Navigator plugins and was broken in anyway.

Maemo Certificate Manager (partially in Herring)

Package name 2.0 2.1 3.0
libosso-certman-dev 1.5.13-1 N/A 2.0.2-1
libcst-dev 1.6.34maemo1 N/A 1.7.1

The API that is meant to be public, libosso-certman-dev, has not changed.

The libcst-dev (not in herring) contains some small modifications in the headers. Although this API is described in the Maemo.org it is not meant to be used by the 3rd party developers as the primary Certificate Manager API.

Functions CST_is_purpose() and CST_set_default() has better documented return value, the function CST_open() has clarification about mandatory GLIB initialization. A new function CST_all_CA() has been introduced. And a bug documented in Maemo.org has been fixed: the CST_PURPOSE_ALL define has been increased from 0xffff to 0xffffffff.

X (in Herring)

X has been updated from the old xlibs tree, to current X.Org. All libxproto-foo-dev has been renamed to x11proto-foo-dev; most libxfoo-dev has been unchanged. pkg-config should now be used to search for X, i.e.: $(pkg-config cflags libs x11 xi) instead of searching for libX11 and libXi, or searching for certain includes under /usr/X11R6/include. The libraries and includes now live in /usr/lib and /usr/include/X11, respectively.