Editing Documentation/Maemo 5 Developer Guide/Application Development/LibOSSO library

Warning: You are not logged in. Your IP address will be recorded in this page's edit history.

The edit can be undone. Please check the comparison below to verify that this is what you want to do, and then save the changes below to finish undoing the edit.

Learn more about Contributing to the wiki.

LibOSSO is the basic library, containing required and helpful functions for Maemo applications. The [http://maemo.org/api_refs/5.0/5.0-final/libosso/ full API documentation of LibOSSO is available] in Doxygen format.

== Maemo initialization ==

All Maemo applications must be initialized correctly, or they do not work as expected. One symptom of missing initialization is that application starts from Task Navigator, but closes automatically after few seconds.

Initializing application is performed with <code>osso_initialize()</code> function. With this function, the application connects to D-Bus session bus and system bus. <code>osso_initialize()</code> function should only be called once in the application, and the structure of type <code>osso_context_t</code> type that is returned should be stored for later use. First parameter of the function is the application D-Bus name, used also in application D-Bus service file. Second parameter is the application version as a string. Third is the activation type, with <code>TRUE</code> the library assumes that the application binary has been launched by the D-Bus daemon, and thus connects to the D-Bus activation bus. Fourth parameter is the GLib main-loop context to connect to, <code>NULL</code> should be used for the default context.

<source lang="c">
osso_context_t * osso_initialize(const gchar *application, const gchar* version, gboolean activation, GMainContext *context)
</source>

When the application is closing, <code>osso_deinitialize</code> function should be called to close the message bus connection and free all memory allocated by the library.

<source lang="c">
void osso_deinitialize(osso_context_t *osso)
</source>

Below is an example ([https://vcs.maemo.org/svn/maemoexamples/tags/maemo_5.0/maemo-examples/example_libosso.c example_libosso.c]) of this; if the initialization does not succeed, the function returns <code>NULL</code>.

<source lang="c">
#define OSSO_EXAMPLE_NAME    "example_libosso"
#define OSSO_EXAMPLE_SERVICE "org.maemo."OSSO_EXAMPLE_NAME
/* ... */
    osso_context_t *osso_context;
    /* ... */
    /* Initialize maemo application */
    osso_context = osso_initialize(OSSO_EXAMPLE_SERVICE, "0.0.1", TRUE, NULL);
    /* Check that initialization was ok */
    if (osso_context == NULL) {
        return OSSO_ERROR;
    }
    /* ... */
    /* Deinitialize OSSO */
    osso_deinitialize(osso_context);
</source>

== Remote process messages ==

System wide messages in Maemo platform are handled with D-Bus system messaging, which is a Remote Process Communication (RPC) method. LibOSSO has own wrappers to normal D-Bus functions to make usage simpler and to maintain backward compatibility. By using D-Bus, applications can send messages from one process to another.

Callback function receiving the messages can be as follows ([https://vcs.maemo.org/svn/maemoexamples/tags/maemo_5.0/maemo-examples/example_libosso.c example_libosso.c]), where <code>AppData</code> structure contains the initialized <code>osso_context</code>:

<source lang="c">
#include <hildon/hildon-program.h>
#include <hildon/hildon-banner.h>
#include <gtk/gtk.h>
#include <libosso.h>
#define OSSO_EXAMPLE_NAME    "example_libosso"
#define OSSO_EXAMPLE_SERVICE "org.maemo."OSSO_EXAMPLE_NAME
#define OSSO_EXAMPLE_OBJECT  "/org/maemo/"OSSO_EXAMPLE_NAME
#define OSSO_EXAMPLE_IFACE   "org.maemo."OSSO_EXAMPLE_NAME
/* ... */
/* Application UI data struct */
typedef struct _AppData AppData;
struct _AppData {
    HildonProgram *program;
    HildonWindow *window;
    osso_context_t *osso_context;
};
/* ... */
/* Callback for normal D-Bus messages */
gint dbus_req_handler(const gchar * interface, const gchar * method,
                      GArray * arguments, gpointer data,
                      osso_rpc_t * retval)
{
    AppData *appdata;
    appdata = (AppData *) data;
    osso_system_note_infoprint(appdata->osso_context, method, retval);
    osso_rpc_free_val(retval);
    return OSSO_OK;
}
</source>

To attach this callback function to receive all the normal D-Bus messages to the application, use the <code>osso_rpc_set_default_cb_f</code> function as follows:

<source lang="c">
int main(int argc, char *argv[])
{
    osso_return_t result;

/* ... */
    /* Add handler for session bus D-Bus messages */
    result = osso_rpc_set_cb_f(appdata->osso_context,
                               OSSO_EXAMPLE_SERVICE,
                               OSSO_EXAMPLE_OBJECT,
                               OSSO_EXAMPLE_IFACE,
                               dbus_req_handler, appdata);

if (result != OSSO_OK) {
        g_print("Error setting D-Bus callback (%d)\n", result);
        return OSSO_ERROR;
    }
    /* ... */

/* Deinitialize OSSO */
    osso_deinitialize(osso_context);
}
</source>

Now the application is ready to receive D-Bus messages. Whenever it receives one, the dbus_req_handler function is called to process the message. Another test application ([https://vcs.maemo.org/svn/maemoexamples/tags/maemo_5.0/maemo-examples/example_message.c example_message.c]), can send the ''HelloWorld'' that this application was designed to handle, as follows:

<source lang="c">
/* ... */
#define OSSO_EXAMPLE_NAME    "example_libosso"
#define OSSO_EXAMPLE_SERVICE "org.maemo."OSSO_EXAMPLE_NAME
#define OSSO_EXAMPLE_OBJECT  "/org/maemo/"OSSO_EXAMPLE_NAME
#define OSSO_EXAMPLE_IFACE   "org.maemo."OSSO_EXAMPLE_NAME
#define OSSO_EXAMPLE_MESSAGE "HelloWorld"
/* ... */
ret = osso_rpc_run(osso_context,
                   OSSO_EXAMPLE_SERVICE,
                   OSSO_EXAMPLE_OBJECT,
                   OSSO_EXAMPLE_IFACE,
                   OSSO_EXAMPLE_MESSAGE, &retval, DBUS_TYPE_INVALID);
/* ... */
</source>

When example_libosso_test is started, it sends an <code>example_message</code> D-Bus message to <code>org.maemo.example_libosso</code> service, attached to the example_libosso application (See more about D-Bus service files from an earlier section). Now when <code>example_libosso</code> receives the message, it shows a banner.

One nice thing about D-Bus is that the receiving application does not even need to be started: D-Bus can automatically start the application based on its service file, and then pass the message to it!

==Hardware state messages ==

Maemo applications can connect to listen the system D-Bus messages, like ''battery low'' and ''shutdown''. When these messages are received, the application may want to ask the user to save files that are open, or react however wanted.

A callback function is defined like below, taking <code>osso_hw_state_t</code> and <code>gpointer</code> as parameters. The changed state can be gotten from state variable ([https://vcs.maemo.org/svn/maemoexamples/tags/maemo_5.0/maemo-examples/example_libosso.c <code>example_libosso.c</code>]).

<source lang="c">
/* Callback for hardware D-Bus events */
void hw_event_handler(osso_hw_state_t *state, gpointer data)
{
    AppData *appdata;
    appdata = (AppData *) data;
    if (state->shutdown_ind)
    {
        hildon_banner_show_information(GTK_WIDGET(appdata->window), NULL,
                                       "Shutdown event!");
    }
    if (state->memory_low_ind)
    {
        hildon_banner_show_information(GTK_WIDGET(appdata->window), NULL,
                                       "Memory low event!");
    }
    if (state->save_unsaved_data_ind)
    {
        hildon_banner_show_information(GTK_WIDGET(appdata->window), NULL,
                                       "Must save unsaved data event!");
    }
    if (state->system_inactivity_ind)
    {
        hildon_banner_show_information(GTK_WIDGET(appdata->window), NULL,
                                       "Minimize application inactivity event!");
    }
}
</source>

To attach this handler, e.g. in application <code>main()</code>, use <code>osso_hw_set_event_cb()</code>.

<source lang="c">
    /* ... */

/* Add handler for hardware D-Bus messages */
    result = osso_hw_set_event_cb( appdata->osso_context,
        NULL, hw_event_handler, (gpointer) appdata );

if (result != OSSO_OK)
    {
        g_print("Error setting HW state callback (%d)\n", result);
        return OSSO_ERROR;
    }

/* ... */
</source>

{{ambox
|text=These hardware events are not sent to the SDK, so testing them is only possible on a Maemo device.}}

== System Exit message ==

A system message is sent when applications are required to close themselves. Its callback is: ([https://vcs.maemo.org/svn/maemoexamples/tags/maemo_5.0/maemo-examples/example_libosso.c example_libosso.c]):

<source lang="c">
/* Callback for exit D-Bus event */
void exit_event_handler(gboolean die_now, gpointer data)
{
    AppData *appdata;
    appdata = (AppData *) data;
    g_print("exit_event_handler called\n");
    /* Do whatever application needs to do before exiting */
    hildon_banner_show_information(GTK_WIDGET(appdata->window), NULL,
                                   "Exiting...");
}
</source>

The callback is set (e.g. in application main) as follows.

<source lang="c">
int main( int argc, char* argv[] )
{
/* ... */
    /* Add handler for Exit D-BUS messages */
    result = osso_application_set_exit_cb(appdata->osso_context,
                                          exit_event_handler,
                                          (gpointer) appdata);
    if (result != OSSO_OK) {
        g_print("Error setting exit callback (%d)\n", result);
        return OSSO_ERROR;
    }
/* ... */
}
</source>

Now whenever the system needs to close an application for any reason, the close is performed gracefully.

== Application state saving and auto save ==

State saving is a special feature of the Maemo platform. It means that applications save their running state from RAM to permanent memory, such as flash memory, and then end the running application process. This state saving happens when switching out from the application and the device memory is running low. When the user then returns to a backgrounded application, the application restarts, the application state is read from flash memory, and the user does not even know that the application was not running all the time.

Auto saving is an addition to state saving for editor-like applications containing user data. This data/document is automatically saved at the same time with state save. The main difference is that the application state is usually just a small amount of variables describing the state where the application was, whereas the auto-saved file can be any file the user was editing. Auto saving guarantees that user files are not lost when e.g. the battery runs out.

Information on how to implement state saving can be found in LibOSSO API document.

[[Category:Development]]
[[Category:Documentation]]
[[Category:Fremantle]]

Please note that all contributions to maemo.org wiki may be edited, altered, or removed by other contributors. If you do not want your writing to be edited mercilessly, then do not submit it here.
You are also promising us that you wrote this yourself, or copied it from a public domain or similar free resource (see maemo.org wiki:Copyrights for details). Do not submit copyrighted work without permission!

Summary:

Cancel | Editing help (opens in new window)

Templates used on this page:

Template:Ambox (view source) (semi-protected)

Retrieved from "http://wiki.maemo.org/Documentation/Maemo_5_Developer_Guide/Application_Development/LibOSSO_library"

Personal tools

Navigation

Views

Editing Documentation/Maemo 5 Developer Guide/Application Development/LibOSSO library

@@ Line 99: / Line 99: @@
 </source>
-Now the application is ready to receive D-Bus messages. Whenever it receives one, the <code>dbus_req_handler()</code> function is called to process the message. Another test application ([https://vcs.maemo.org/svn/maemoexamples/tags/maemo_5.0/maemo-examples/example_message.c example_message.c]), can send the ''HelloWorld'' that this application was designed to handle, as follows:
+Now the application is ready to receive D-Bus messages. Whenever it receives one, the dbus_req_handler function is called to process the message. Another test application ([https://vcs.maemo.org/svn/maemoexamples/tags/maemo_5.0/maemo-examples/example_message.c example_message.c]), can send the ''HelloWorld'' that this application was designed to handle, as follows:
 <source lang="c">
@@ Line 221: / Line 221: @@
 Information on how to implement state saving can be found in LibOSSO API document.
-== Further reading ==
-* [[Documentation/Maemo 5 Developer Guide/DBus/DBus Basics|Introduction to D-Bus]]
 [[Category:Development]]
 [[Category:Documentation]]
 [[Category:Fremantle]]