Maemo Diablo Reference Manual for maemo 4.1 Using Generic Platform Components December 22, 2008 Contents 1 Using Generic Platform Components 3 1.1 Introduction .............................. 3 1.2 File System - GnomeVFS ....................... 4 1.3 Message Bus System - D-Bus .................... 12 1.3.1 D-Bus Basics .......................... 12 1.3.2 LibOSSO ............................ 24 1.3.3 Using GLib Wrappers for D-Bus .............. 44 1.3.4 Implementing and Using D-Bus Signals .......... 66 1.3.5 Asynchronous GLib/D-Bus ................. 81 1.3.6 D-Bus Server Design Issues ................. 91 1.4 Application Preferences - GConf .................. 98 1.4.1 Using GConf ......................... 98 1.4.2 Using GConf to Read and Write Preferences ....... 100 1.4.3 Asynchronous GConf .................... 107 1.5 Alarm Framework .......................... 114 1.5.1 Alarm Events ......................... 115 1.5.2 Managing Alarm Events ................... 119 1.5.3 Checking for Errors ...................... 120 1.5.4 Localized Strings ....................... 121 1.6 Usage of Back-up Application .................... 123 1.6.1 Custom Back-up Locations ................. 123 1.6.2 After Restore Run Scripts .................. 124 1.7 Using Maemo Address Book API .................. 125 1.7.1 Using Library ......................... 125 1.7.2 Accessing Evolution Data Server (EDS) .......... 127 1.7.3 Creating User Interface ................... 132 1.7.4 Using Autoconf ........................ 136 1.8 Clipboard Usage ........................... 137 1.8.1 GtkClipboard API Changes ................. 137 1.8.2 GtkTextBuffer API Changes ................. 137 1.9 Global Search Usage ......................... 138 1.9.1 Global Search Plug-ins .................... 139 1.10 Writing "Send Via" Functionality .................. 141 1.11 Using HAL ............................... 142 1.11.1 Background .......................... 143 1.11.2 C API .............................. 145 1.12 Certificate Storage Guide ....................... 147 1.12.1 Digital Certificates ...................... 147 1 1.12.2 Certificates in Maemo Platform ............... 149 1.12.3 Creating Own Certificates with OpenSSL ......... 149 1.12.4 Maemo Certificate Databases ................ 150 1.12.5 Creating Databases ...................... 150 1.12.6 Importing Certificates and Keys .............. 151 1.12.7 Sample Program for Searching and Listing Certificates . 153 1.12.8 Deleting Certificates ..................... 154 1.12.9 Validating Certificate Files .................. 155 1.12.10 Exporting Certificates .................... 155 1.13 Extending Hildon Input Methods .................. 155 1.13.1 Overview ........................... 155 1.13.2 Plug-in Features ....................... 156 1.13.3 Interaction with Main User Interface ............ 164 1.13.4 Component Dependencies .................. 167 1.13.5 Language Codes ....................... 167 2 Chapter 1 Using Generic Platform Components 1.1 Introduction The following code examples are used in this chapter: hildon_helloworld-8.c • libdbus-example • libosso-example-sync • libosso-example-async • libosso-flashlight • glib-dbus-sync • glib-dbus-signals • glib-dbus-async • hildon_helloworld-9.c • gconf-listener • example_alarm.c • example_abook.c • MaemoPad • Certificate Manager Examples • hildon-input-method-plugins-example • The underlying system services in the maemo platform differ slightly from those used in desktop Linux distributions. This chapter gives an overview of the most important system services. 3 1.2 File System - GnomeVFS Maemo includes a powerful file system framework, GnomeVFS. This frame- work enables applications to use a vast number of different file access protocols without having to know anything about the underlying details. Some examples of the supported protocols are: local file system, HTTP, FTP and OBEX over Bluetooth. In practice, this means that all GnomeVFS file access methods are transpar- ently available for both developer and end user just by using the framework for file operations. The API for file handling is also much more flexible than the standard platform offerings. It features, for example, asynchronous reading and writing, MIME type support and file monitoring. All user-file access should be done with GnomeVFS in maemo applications, because file access can be remote. In fact, many applications that come with the operating system on the Internet tablets do make use of GnomeVFS. Access to files not visible to the user should be done directly for performance reasons. A good hands-on starting point is taking a look at the GnomeVFS example in maemo-examples package. Detailed API information can be found in the GnomeVFS API reference[3]. GnomeVFS Example In maemo, GnomeVFS also provides some filename case insensitivity sup- port, so that the end users do not have to care about the UNIX filename con- ventions, which are case-sensitive. The GnomeVFS interface attempts to provide a POSIX-like interface, so that when one would use open() with POSIX, gnome_vfs_open can be used instead. Instead of write(), there is gnome_vfs_write, etc. (for most functions). The GnomeVFS function names are sometimes a bit more verbose, but other- wise they attempt to implement the basic API. Some POSIX functions, such as mmap(), are impossible to implement in the user space, but normally this is not a big problem. Also some functions will fail to work properly over network connections and outside the local filesystem, since they might not always make sense there. Shortly there will follow a simple example of using the GnomeVFS interface functions. In order to save and load data, at least the following functions are needed: gnome_vfs_init(): initializes the GnomeVFS library. Needs to be done • once at an early stage at program startup. gnome_vfs_shutdown(): frees up resources inside the library and closes • it down. gnome_vfs_open(): opens the given URI (explained below) and returns • a file handle for that if successful. gnome_vfs_get_file_info(): get information about a file (similar to, but • with broader scope than fstat). gnome_vfs_read(): read data from an opened file. • gnome_vfs_write(): write data into an opened file. • 4 In order to differentiate between different protocols, GnomeVFS uses Uni- form Resource Location syntax when accessing resources. For example in file:///tmp/somefile.txt, the file:// is the protocol to use, and the rest is the loca- tion within that protocol space for the resource or file to manipulate. Protocols can be stacked inside a single URI, and the URI also supports username and password combinations (these are best demonstrated in the GnomeVFS API documentation). The following simple demonstration will be using local files. A simple application will be extended in the following ways: Implement the "Open" command by using GnomeVFS with full error • checking. The memory will be allocated and freed with g_malloc0() and g_free(), • when loading the contents of the file that the user has selected. Data loaded through "Open" will replace the text in the GtkLabel that is • in the center area of the HildonWindow. The label will be switched to support Pango simple text markup, which looks a lot like simple HTML. Notification about loading success and failures will be communicated to • the user by using a widget called HildonBanner, which will float a small notification dialog (with an optional icon) in the top-right corner for a while, without blocking the application. N.B. Saving into a file is not implemented in this code, as it is a lab exercise • (and it is simpler than opening). File loading failures can be simulated by attempting to load an empty file. • Since empty files are not wanted, the code will turn this into an error as well. If there is no empty file available, one can easily be created with the touch command (under MyDocs, so that the open dialog can find it). It is also possible to attempt to load a file larger than 100 KiB, since the code limits the file size (artificially), and will refuse to load large files. The goto statement should normally be avoided. Team coding guidelines • should be checked to see, whether this is an allowed practice. Note how it is used in this example to cut down the possibility of leaked resources (and typing). Another option for this would be using variable finalizers, but not many people know how to use them, or even that they exist. They are gcc extensions into the C language, and you can find more about them by reading gcc info pages (look for variable attributes). Simple GnomeVFS functions are used here. They are all synchronous, • which means that if loading the file takes a long time, the application will remain unresponsive during that time. For small files residing in local storage, this is a risk that is taken knowingly. Synchronous API should not be used when loading files over network, since there are more uncertainties in those cases. I/O in most cases will be slightly slower than using a controlled approach • with POSIX I/O API (controlled meaning that one should know what to use and how). This is a price that has to be paid in order to enable easy switching to other protocols later. 5 N.B. Since GnomeVFS is a separate library from GLib, you will have to add the flags and library options that it requires. The pkg-config package name for the library is gnome-vfs-2.0. /** * hildon_helloworld -8.c * * This maemo code example is licensed under a MIT-style license , * that can be found in the file called "License" in the same * directory as this file. * Copyright (c) 2007-2008 Nokia