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.
Latest revision | Your text | ||
Line 1: | Line 1: | ||
+ | = Overview = | ||
+ | |||
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. | 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. | 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- | + | 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 osso_context_t 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 TRUE 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, NULL should be used for the default context. <br /> |
- | < | + | <br />''osso_context_t * osso_initialize(const gchar *application, const gchar* version, gboolean activation, GMainContext *context)''<br /><br /> When the application is closing, osso_deinitialize function should be called to close the message bus connection and free all memory allocated by the library. <br /><br />''void osso_deinitialize(osso_context_t *osso)''<br /><br /> |
- | osso_context_t * osso_initialize(const gchar *application, const gchar* version, gboolean activation, GMainContext *context) | + | |
- | </ | + | |
- | + | 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 NULL. | |
- | < | + | <tt><span>'''<span><font color="#000080"><nowiki>#define</nowiki></font></span>'''</span> OSSO_EXAMPLE_NAME <span><font color="#FF0000">"example_libosso"</font></span> |
- | + | <span>'''<span><font color="#000080"><nowiki>#define</nowiki></font></span>'''</span> OSSO_EXAMPLE_SERVICE <span><font color="#FF0000">"org.maemo."</font></span>OSSO_EXAMPLE_NAME | |
- | </ | + | <span>''<span><font color="#9A1900">/* ... */</font></span>''</span> |
+ | osso_context_t <span><font color="#990000"><nowiki>*</nowiki></font></span>osso_context<span><font color="#990000"><nowiki>;</nowiki></font></span> | ||
+ | <span>''<span><font color="#9A1900">/* ... */</font></span>''</span> | ||
+ | <span>''<span><font color="#9A1900">/* Initialize maemo application */</font></span>''</span> | ||
+ | osso_context <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">osso_initialize</font></span>'''</span><span><font color="#990000">(</font></span>OSSO_EXAMPLE_SERVICE<span><font color="#990000">,</font></span> <span><font color="#FF0000">"0.0.1"</font></span><span><font color="#990000">,</font></span> TRUE<span><font color="#990000">,</font></span> NULL<span><font color="#990000">);</font></span> | ||
+ | <span>''<span><font color="#9A1900">/* Check that initialization was ok */</font></span>''</span> | ||
+ | <span>'''<span><font color="#0000FF">if</font></span>'''</span> <span><font color="#990000">(</font></span>osso_context <span><font color="#990000"><nowiki>==</nowiki></font></span> NULL<span><font color="#990000">)</font></span> <span><font color="#FF0000">{</font></span> | ||
+ | <span>'''<span><font color="#0000FF">return</font></span>'''</span> OSSO_ERROR<span><font color="#990000"><nowiki>;</nowiki></font></span> | ||
+ | <span><font color="#FF0000">}</font></span> | ||
+ | <span>''<span><font color="#9A1900">/* ... */</font></span>''</span> | ||
+ | <span>''<span><font color="#9A1900">/* Deinitialize OSSO */</font></span>''</span> | ||
+ | <span>'''<span><font color="#000000">osso_deinitialize</font></span>'''</span><span><font color="#990000">(</font></span>osso_context<span><font color="#990000">);</font></span> | ||
+ | </tt> | ||
- | + | = 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 AppData structure contains the initialized osso_context: | |
- | + | <tt><span>'''<span><font color="#000080"><nowiki>#include</nowiki></font></span>'''</span> <span><font color="#FF0000"><hildon/hildon-program.h></font></span> | |
+ | <span>'''<span><font color="#000080"><nowiki>#include</nowiki></font></span>'''</span> <span><font color="#FF0000"><hildon/hildon-banner.h></font></span> | ||
+ | <span>'''<span><font color="#000080"><nowiki>#include</nowiki></font></span>'''</span> <span><font color="#FF0000"><gtk/gtk.h></font></span> | ||
+ | <span>'''<span><font color="#000080"><nowiki>#include</nowiki></font></span>'''</span> <span><font color="#FF0000"><libosso.h></font></span> | ||
+ | <span>'''<span><font color="#000080"><nowiki>#define</nowiki></font></span>'''</span> OSSO_EXAMPLE_NAME <span><font color="#FF0000">"example_libosso"</font></span> | ||
+ | <span>'''<span><font color="#000080"><nowiki>#define</nowiki></font></span>'''</span> OSSO_EXAMPLE_SERVICE <span><font color="#FF0000">"org.maemo."</font></span>OSSO_EXAMPLE_NAME | ||
+ | <span>'''<span><font color="#000080"><nowiki>#define</nowiki></font></span>'''</span> OSSO_EXAMPLE_OBJECT <span><font color="#FF0000">"/org/maemo/"</font></span>OSSO_EXAMPLE_NAME | ||
+ | <span>'''<span><font color="#000080"><nowiki>#define</nowiki></font></span>'''</span> OSSO_EXAMPLE_IFACE <span><font color="#FF0000">"org.maemo."</font></span>OSSO_EXAMPLE_NAME | ||
+ | <span>''<span><font color="#9A1900">/* ... */</font></span>''</span> | ||
+ | <span>''<span><font color="#9A1900">/* Application UI data struct */</font></span>''</span> | ||
+ | <span>'''<span><font color="#0000FF">typedef</font></span>'''</span> <span>'''<span><font color="#0000FF">struct</font></span>'''</span> <span><font color="#009900">_AppData</font></span> AppData<span><font color="#990000"><nowiki>;</nowiki></font></span> | ||
+ | <span>'''<span><font color="#0000FF">struct</font></span>'''</span> <span><font color="#009900">_AppData</font></span> <span><font color="#FF0000">{</font></span> | ||
+ | HildonProgram <span><font color="#990000"><nowiki>*</nowiki></font></span>program<span><font color="#990000"><nowiki>;</nowiki></font></span> | ||
+ | HildonWindow <span><font color="#990000"><nowiki>*</nowiki></font></span>window<span><font color="#990000"><nowiki>;</nowiki></font></span> | ||
+ | osso_context_t <span><font color="#990000"><nowiki>*</nowiki></font></span>osso_context<span><font color="#990000"><nowiki>;</nowiki></font></span> | ||
+ | <span><font color="#FF0000">}</font></span><span><font color="#990000"><nowiki>;</nowiki></font></span> | ||
+ | <span>''<span><font color="#9A1900">/* ... */</font></span>''</span> | ||
+ | <span>''<span><font color="#9A1900">/* Callback for normal D-BUS messages */</font></span>''</span> | ||
+ | gint <span>'''<span><font color="#000000">dbus_req_handler</font></span>'''</span><span><font color="#990000">(</font></span><span>'''<span><font color="#0000FF">const</font></span>'''</span> gchar <span><font color="#990000"><nowiki>*</nowiki></font></span> interface<span><font color="#990000">,</font></span> <span>'''<span><font color="#0000FF">const</font></span>'''</span> gchar <span><font color="#990000"><nowiki>*</nowiki></font></span> method<span><font color="#990000">,</font></span> | ||
+ | GArray <span><font color="#990000"><nowiki>*</nowiki></font></span> arguments<span><font color="#990000">,</font></span> gpointer data<span><font color="#990000">,</font></span> | ||
+ | osso_rpc_t <span><font color="#990000"><nowiki>*</nowiki></font></span> retval<span><font color="#990000">)</font></span> | ||
+ | <span><font color="#FF0000">{</font></span> | ||
+ | AppData <span><font color="#990000"><nowiki>*</nowiki></font></span>appdata<span><font color="#990000"><nowiki>;</nowiki></font></span> | ||
+ | appdata <span><font color="#990000"><nowiki>=</nowiki></font></span> <span><font color="#990000">(</font></span>AppData <span><font color="#990000"><nowiki>*)</nowiki></font></span> data<span><font color="#990000"><nowiki>;</nowiki></font></span> | ||
+ | <span>'''<span><font color="#000000">osso_system_note_infoprint</font></span>'''</span><span><font color="#990000">(</font></span>appdata<span><font color="#990000">-></font></span>osso_context<span><font color="#990000">,</font></span> method<span><font color="#990000">,</font></span> retval<span><font color="#990000">);</font></span> | ||
+ | <span>'''<span><font color="#000000">osso_rpc_free_val</font></span>'''</span><span><font color="#990000">(</font></span>retval<span><font color="#990000">);</font></span> | ||
+ | <span>'''<span><font color="#0000FF">return</font></span>'''</span> OSSO_OK<span><font color="#990000"><nowiki>;</nowiki></font></span> | ||
+ | <span><font color="#FF0000">}</font></span> | ||
+ | </tt> | ||
- | + | To attach this callback function to receive all the normal D-BUS messages to the application, use the osso_rpc_set_default_cb_f function as follows: | |
- | < | + | <tt><span><font color="#009900">int</font></span> <span>'''<span><font color="#000000">main</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#009900">int</font></span> argc<span><font color="#990000">,</font></span> <span><font color="#009900">char</font></span> <span><font color="#990000"><nowiki>*</nowiki></font></span>argv<span><font color="#990000">[])</font></span> |
- | + | <span><font color="#FF0000">{</font></span> | |
- | # | + | osso_return_t result<span><font color="#990000"><nowiki>;</nowiki></font></span> |
- | # | + | |
- | # | + | <span>''<span><font color="#9A1900">/* ... */</font></span>''</span> |
- | # | + | <span>''<span><font color="#9A1900">/* Add handler for session bus D-BUS messages */</font></span>''</span> |
- | # | + | result <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">osso_rpc_set_cb_f</font></span>'''</span><span><font color="#990000">(</font></span>appdata<span><font color="#990000">-></font></span>osso_context<span><font color="#990000">,</font></span> |
- | # | + | OSSO_EXAMPLE_SERVICE<span><font color="#990000">,</font></span> |
- | # | + | OSSO_EXAMPLE_OBJECT<span><font color="#990000">,</font></span> |
- | / | + | OSSO_EXAMPLE_IFACE<span><font color="#990000">,</font></span> |
- | / | + | dbus_req_handler<span><font color="#990000">,</font></span> appdata<span><font color="#990000">);</font></span> |
- | + | ||
- | + | <span>'''<span><font color="#0000FF">if</font></span>'''</span> <span><font color="#990000">(</font></span>result <span><font color="#990000"><nowiki>!=</nowiki></font></span> OSSO_OK<span><font color="#990000">)</font></span> <span><font color="#FF0000">{</font></span> | |
- | + | <span>'''<span><font color="#000000">g_print</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#FF0000">"Error setting D-BUS callback (%d)</font></span><span><font color="#CC33CC">\n</font></span><span><font color="#FF0000">"</font></span><span><font color="#990000">,</font></span> result<span><font color="#990000">);</font></span> | |
- | + | <span>'''<span><font color="#0000FF">return</font></span>'''</span> OSSO_ERROR<span><font color="#990000"><nowiki>;</nowiki></font></span> | |
- | + | <span><font color="#FF0000">}</font></span> | |
- | + | <span>''<span><font color="#9A1900">/* ... */</font></span>''</span> | |
- | /* ... */ | + | |
- | /* | + | <span>''<span><font color="#9A1900">/* Deinitialize OSSO */</font></span>''</span> |
- | + | <span>'''<span><font color="#000000">osso_deinitialize</font></span>'''</span><span><font color="#990000">(</font></span>osso_context<span><font color="#990000">);</font></span> | |
- | + | <span><font color="#FF0000">}</font></span> | |
- | + | </tt> | |
- | + | ||
- | + | ||
- | + | ||
- | + | ||
- | + | ||
- | + | ||
- | } | + | |
- | </ | + | |
- | + | 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]<nowiki>), can send the ``HelloWorld'' that this application was designed to handle, as follows: </nowiki> | |
- | < | + | <tt><span>''<span><font color="#9A1900">/* ... */</font></span>''</span> |
- | + | <span>'''<span><font color="#000080"><nowiki>#define</nowiki></font></span>'''</span> OSSO_EXAMPLE_NAME <span><font color="#FF0000">"example_libosso"</font></span> | |
- | + | <span>'''<span><font color="#000080"><nowiki>#define</nowiki></font></span>'''</span> OSSO_EXAMPLE_SERVICE <span><font color="#FF0000">"org.maemo."</font></span>OSSO_EXAMPLE_NAME | |
- | + | <span>'''<span><font color="#000080"><nowiki>#define</nowiki></font></span>'''</span> OSSO_EXAMPLE_OBJECT <span><font color="#FF0000">"/org/maemo/"</font></span>OSSO_EXAMPLE_NAME | |
+ | <span>'''<span><font color="#000080"><nowiki>#define</nowiki></font></span>'''</span> OSSO_EXAMPLE_IFACE <span><font color="#FF0000">"org.maemo."</font></span>OSSO_EXAMPLE_NAME | ||
+ | <span>'''<span><font color="#000080"><nowiki>#define</nowiki></font></span>'''</span> OSSO_EXAMPLE_MESSAGE <span><font color="#FF0000">"HelloWorld"</font></span> | ||
+ | <span>''<span><font color="#9A1900">/* ... */</font></span>''</span> | ||
+ | ret <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">osso_rpc_run</font></span>'''</span><span><font color="#990000">(</font></span>osso_context<span><font color="#990000">,</font></span> | ||
+ | OSSO_EXAMPLE_SERVICE<span><font color="#990000">,</font></span> | ||
+ | OSSO_EXAMPLE_OBJECT<span><font color="#990000">,</font></span> | ||
+ | OSSO_EXAMPLE_IFACE<span><font color="#990000">,</font></span> | ||
+ | OSSO_EXAMPLE_MESSAGE<span><font color="#990000">,</font></span> <span><font color="#990000">&</font></span>retval<span><font color="#990000">,</font></span> DBUS_TYPE_INVALID<span><font color="#990000">);</font></span> | ||
+ | <span>''<span><font color="#9A1900">/* ... */</font></span>''</span></tt> | ||
- | + | <nowiki> When example_libosso_test is started, it sends an ``example_message'' D-BUS message to org.maemo.example_libosso service, attached to the example_libosso application (See more about D-BUS service files from an earlier section). Now when example_libosso receives the message, it shows a banner. </nowiki> | |
- | + | ||
- | + | ||
- | + | ||
- | + | ||
- | + | ||
- | + | ||
- | + | 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 = | |
- | + | ||
- | + | ||
- | + | ||
- | + | <nowiki> 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. </nowiki> | |
- | < | + | A callback function is defined like below, taking <code>osso_hw_state_t</code> and gpointer 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>]). |
- | / | + | |
- | + | ||
- | + | ||
- | + | ||
- | + | ||
- | + | ||
- | / | + | |
- | + | ||
- | + | ||
- | + | ||
- | + | ||
- | + | ||
- | / | + | |
- | </ | + | |
- | + | <tt><span>''<span><font color="#9A1900">/* Callback for hardware D-BUS events */</font></span>''</span> | |
- | + | <span><font color="#009900">void</font></span> <span>'''<span><font color="#000000">hw_event_handler</font></span>'''</span><span><font color="#990000">(</font></span>osso_hw_state_t <span><font color="#990000"><nowiki>*</nowiki></font></span>state<span><font color="#990000">,</font></span> gpointer data<span><font color="#990000">)</font></span> | |
- | + | <span><font color="#FF0000">{</font></span> | |
- | + | AppData <span><font color="#990000"><nowiki>*</nowiki></font></span>appdata<span><font color="#990000"><nowiki>;</nowiki></font></span> | |
- | = | + | appdata <span><font color="#990000"><nowiki>=</nowiki></font></span> <span><font color="#990000">(</font></span>AppData <span><font color="#990000"><nowiki>*)</nowiki></font></span> data<span><font color="#990000"><nowiki>;</nowiki></font></span> |
- | + | <span>'''<span><font color="#0000FF">if</font></span>'''</span> <span><font color="#990000">(</font></span>state<span><font color="#990000">-></font></span>shutdown_ind<span><font color="#990000">)</font></span> | |
- | + | <span><font color="#FF0000">{</font></span> | |
- | + | <span>'''<span><font color="#000000">hildon_banner_show_information</font></span>'''</span><span><font color="#990000">(</font></span><span>'''<span><font color="#000000">GTK_WIDGET</font></span>'''</span><span><font color="#990000">(</font></span>appdata<span><font color="#990000">-></font></span>window<span><font color="#990000">),</font></span> NULL<span><font color="#990000">,</font></span> | |
- | + | <span><font color="#FF0000">"Shutdown event!"</font></span><span><font color="#990000">);</font></span> | |
- | + | <span><font color="#FF0000">}</font></span> | |
- | < | + | <span>'''<span><font color="#0000FF">if</font></span>'''</span> <span><font color="#990000">(</font></span>state<span><font color="#990000">-></font></span>memory_low_ind<span><font color="#990000">)</font></span> |
- | / | + | <span><font color="#FF0000">{</font></span> |
- | + | <span>'''<span><font color="#000000">hildon_banner_show_information</font></span>'''</span><span><font color="#990000">(</font></span><span>'''<span><font color="#000000">GTK_WIDGET</font></span>'''</span><span><font color="#990000">(</font></span>appdata<span><font color="#990000">-></font></span>window<span><font color="#990000">),</font></span> NULL<span><font color="#990000">,</font></span> | |
- | + | <span><font color="#FF0000">"Memory low event!"</font></span><span><font color="#990000">);</font></span> | |
- | + | <span><font color="#FF0000">}</font></span> | |
- | + | <span>'''<span><font color="#0000FF">if</font></span>'''</span> <span><font color="#990000">(</font></span>state<span><font color="#990000">-></font></span>save_unsaved_data_ind<span><font color="#990000">)</font></span> | |
- | + | <span><font color="#FF0000">{</font></span> | |
- | + | <span>'''<span><font color="#000000">hildon_banner_show_information</font></span>'''</span><span><font color="#990000">(</font></span><span>'''<span><font color="#000000">GTK_WIDGET</font></span>'''</span><span><font color="#990000">(</font></span>appdata<span><font color="#990000">-></font></span>window<span><font color="#990000">),</font></span> NULL<span><font color="#990000">,</font></span> | |
- | + | <span><font color="#FF0000">"Must save unsaved data event!"</font></span><span><font color="#990000">);</font></span> | |
- | + | <span><font color="#FF0000">}</font></span> | |
- | + | <span>'''<span><font color="#0000FF">if</font></span>'''</span> <span><font color="#990000">(</font></span>state<span><font color="#990000">-></font></span>system_inactivity_ind<span><font color="#990000">)</font></span> | |
- | + | <span><font color="#FF0000">{</font></span> | |
- | + | <span>'''<span><font color="#000000">hildon_banner_show_information</font></span>'''</span><span><font color="#990000">(</font></span><span>'''<span><font color="#000000">GTK_WIDGET</font></span>'''</span><span><font color="#990000">(</font></span>appdata<span><font color="#990000">-></font></span>window<span><font color="#990000">),</font></span> NULL<span><font color="#990000">,</font></span> | |
- | + | <span><font color="#FF0000">"Minimize application inactivity event!"</font></span><span><font color="#990000">);</font></span> | |
- | + | <span><font color="#FF0000">}</font></span> | |
- | + | <span><font color="#FF0000">}</font></span></tt> | |
- | + | ||
- | + | ||
- | + | ||
- | + | ||
- | + | ||
- | + | ||
- | + | ||
- | + | ||
- | + | ||
- | + | ||
- | } | + | |
- | </ | + | |
To attach this handler, e.g. in application <code>main()</code>, use <code>osso_hw_set_event_cb()</code>. | To attach this handler, e.g. in application <code>main()</code>, use <code>osso_hw_set_event_cb()</code>. | ||
- | < | + | <tt> <span>''<span><font color="#9A1900">/* ... */</font></span>''</span> |
- | + | ||
+ | <span>''<span><font color="#9A1900">/* Add handler for hardware D-BUS messages */</font></span>''</span> | ||
+ | result <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">osso_hw_set_event_cb</font></span>'''</span><span><font color="#990000">(</font></span> appdata<span><font color="#990000">-></font></span>osso_context<span><font color="#990000">,</font></span> | ||
+ | NULL<span><font color="#990000">,</font></span> hw_event_handler<span><font color="#990000">,</font></span> <span><font color="#990000">(</font></span>gpointer<span><font color="#990000">)</font></span> appdata <span><font color="#990000">);</font></span> | ||
+ | |||
+ | <span>'''<span><font color="#0000FF">if</font></span>'''</span> <span><font color="#990000">(</font></span>result <span><font color="#990000"><nowiki>!=</nowiki></font></span> OSSO_OK<span><font color="#990000">)</font></span> | ||
+ | <span><font color="#FF0000">{</font></span> | ||
+ | <span>'''<span><font color="#000000">g_print</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#FF0000">"Error setting HW state callback (%d)</font></span><span><font color="#CC33CC">\n</font></span><span><font color="#FF0000">"</font></span><span><font color="#990000">,</font></span> result<span><font color="#990000">);</font></span> | ||
+ | <span>'''<span><font color="#0000FF">return</font></span>'''</span> OSSO_ERROR<span><font color="#990000"><nowiki>;</nowiki></font></span> | ||
+ | <span><font color="#FF0000">}</font></span> | ||
+ | |||
+ | <span>''<span><font color="#9A1900">/* ... */</font></span>''</span></tt> | ||
- | + | '''N.B.''' These hardware events are not sent to the SDK, so testing them is only possible in 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]): | 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]): | ||
- | < | + | <tt><span>''<span><font color="#9A1900">/* Callback for exit D-BUS event */</font></span>''</span> |
- | /* Callback for exit D- | + | <span><font color="#009900">void</font></span> <span>'''<span><font color="#000000">exit_event_handler</font></span>'''</span><span><font color="#990000">(</font></span>gboolean die_now<span><font color="#990000">,</font></span> gpointer data<span><font color="#990000">)</font></span> |
- | void exit_event_handler(gboolean die_now, gpointer data) | + | <span><font color="#FF0000">{</font></span> |
- | { | + | AppData <span><font color="#990000"><nowiki>*</nowiki></font></span>appdata<span><font color="#990000"><nowiki>;</nowiki></font></span> |
- | + | appdata <span><font color="#990000"><nowiki>=</nowiki></font></span> <span><font color="#990000">(</font></span>AppData <span><font color="#990000"><nowiki>*)</nowiki></font></span> data<span><font color="#990000"><nowiki>;</nowiki></font></span> | |
- | + | <span>'''<span><font color="#000000">g_print</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#FF0000">"exit_event_handler called</font></span><span><font color="#CC33CC">\n</font></span><span><font color="#FF0000">"</font></span><span><font color="#990000">);</font></span> | |
- | + | <span>''<span><font color="#9A1900">/* Do whatever application needs to do before exiting */</font></span>''</span> | |
- | + | <span>'''<span><font color="#000000">hildon_banner_show_information</font></span>'''</span><span><font color="#990000">(</font></span><span>'''<span><font color="#000000">GTK_WIDGET</font></span>'''</span><span><font color="#990000">(</font></span>appdata<span><font color="#990000">-></font></span>window<span><font color="#990000">),</font></span> NULL<span><font color="#990000">,</font></span> | |
- | + | <span><font color="#FF0000">"Exiting..."</font></span><span><font color="#990000">);</font></span> | |
- | + | <span><font color="#FF0000">}</font></span></tt> | |
- | } | + | |
- | </ | + | |
The callback is set (e.g. in application main) as follows. | The callback is set (e.g. in application main) as follows. | ||
- | < | + | <tt><span><font color="#009900">int</font></span> <span>'''<span><font color="#000000">main</font></span>'''</span><span><font color="#990000">(</font></span> <span><font color="#009900">int</font></span> argc<span><font color="#990000">,</font></span> <span><font color="#009900">char</font></span><span><font color="#990000"><nowiki>*</nowiki></font></span> argv<span><font color="#990000">[]</font></span> <span><font color="#990000">)</font></span> |
- | int main( int argc, char* argv[] ) | + | <span><font color="#FF0000">{</font></span> |
- | { | + | <span>''<span><font color="#9A1900">/* ... */</font></span>''</span> |
- | /* ... */ | + | <span>''<span><font color="#9A1900">/* Add handler for Exit D-BUS messages */</font></span>''</span> |
- | + | result <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">osso_application_set_exit_cb</font></span>'''</span><span><font color="#990000">(</font></span>appdata<span><font color="#990000">-></font></span>osso_context<span><font color="#990000">,</font></span> | |
- | + | exit_event_handler<span><font color="#990000">,</font></span> | |
- | + | <span><font color="#990000">(</font></span>gpointer<span><font color="#990000">)</font></span> appdata<span><font color="#990000">);</font></span> | |
- | + | <span>'''<span><font color="#0000FF">if</font></span>'''</span> <span><font color="#990000">(</font></span>result <span><font color="#990000"><nowiki>!=</nowiki></font></span> OSSO_OK<span><font color="#990000">)</font></span> <span><font color="#FF0000">{</font></span> | |
- | + | <span>'''<span><font color="#000000">g_print</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#FF0000">"Error setting exit callback (%d)</font></span><span><font color="#CC33CC">\n</font></span><span><font color="#FF0000">"</font></span><span><font color="#990000">,</font></span> result<span><font color="#990000">);</font></span> | |
- | + | <span>'''<span><font color="#0000FF">return</font></span>'''</span> OSSO_ERROR<span><font color="#990000"><nowiki>;</nowiki></font></span> | |
- | + | <span><font color="#FF0000">}</font></span> | |
- | + | <span>''<span><font color="#9A1900">/* ... */</font></span>''</span> | |
- | /* ... */ | + | <span><font color="#FF0000">}</font></span></tt> |
- | } | + | |
- | </ | + | |
Now whenever the system needs to close an application for any reason, the close is performed gracefully. | 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. | 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. | ||
Line 221: | Line 201: | ||
Information on how to implement state saving can be found in LibOSSO API document. | Information on how to implement state saving can be found in LibOSSO API document. | ||
- | |||
- | |||
- | |||
- | |||
[[Category:Development]] | [[Category:Development]] | ||
[[Category:Documentation]] | [[Category:Documentation]] | ||
[[Category:Fremantle]] | [[Category:Fremantle]] |
Learn more about Contributing to the wiki.