[maemo-commits] [maemo-commits] r17308 - projects/haf/trunk/libosso/src

[From: subversion at stage.maemo.org]

Author: kihamala
Date: 2009-01-28 16:05:59 +0200 (Wed, 28 Jan 2009)
New Revision: 17308

Modified:
   projects/haf/trunk/libosso/src/libosso.h
Log:
added API documentation


Modified: projects/haf/trunk/libosso/src/libosso.h
===================================================================
--- projects/haf/trunk/libosso/src/libosso.h	2009-01-28 13:38:28 UTC (rev 17307)
+++ projects/haf/trunk/libosso/src/libosso.h	2009-01-28 14:05:59 UTC (rev 17308)
@@ -89,7 +89,37 @@
 				 const gchar* version,
 				 gboolean activation,
 				 GMainContext *context);
+
 /**
+ * This function initializes the library, using the D-Bus connections passed
+ * as arguments. Notice that dbus_connection_setup_with_g_main is not called
+ * for the D-Bus connections, allowing for the use of a custom main loop.
+ * Using a private (non-shared) connection is also possible.
+ * #osso_initialize_with_connections should be called
+ * only once by the application.
+ * @param application The name of the application.
+ * This name forms the last part of the default (D-Bus) service name of the
+ * application. Note that the D-Bus service name will be
+ * 'com.nokia.application', where 'application' is the value you gave as the
+ * parameter. Note also that this argument must be identical to the
+ * X-Osso-Service value in the desktop file, or the D-Bus daemon will kill
+ * your application. If you do not want to use the default 'com.nokia' prefix,
+ * you must pass the whole D-Bus service name, e.g. 'org.maemo.my_app'.
+ * The only valid characters that the name may contain are letters a-z and
+ * the underscore '_'.
+ * @param version The version string of the application. It must be 
+ * comparable with strcmp().
+ * @param system_conn D-Bus system bus connection.
+ * @param session_conn D-Bus session bus connection.
+ * @return A context to use in later calls to this library. NULL is
+ * returned if an error happened.
+ */
+osso_context_t *osso_initialize_with_connections(const gchar *application,
+                        const gchar *version,
+                        DBusConnection *system_conn,
+                        DBusConnection *session_conn);
+
+/**
  * This function closes the message bus connections and frees all memory
  * allocated by the Libosso context. This function renders the context to 
  * unusable state. #osso_initialize has to be called again to get a valid