Editing Documentation/Maemo 5 Developer Guide/DBus/Implementing and Using D-Bus Signals

== D-Bus Signal properties ==

However, signals are not the solution to all problems. If a recipient is not processing its D-Bus messages quickly enough (or there just are too many), a signal might get lost on its way to the recipient. Other complications can also occur, as with any RPC mechanism. For these reasons, if the application requires extra reliability, you need to think how to arrange it. One possibility is to occasionally check the state that the application is interested in, assuming it can be checked over the D-Bus. This, however, should not be done too often; the recommended interval is once a minute or less often than that, and only when the application is already active for other reasons. This model leads to a reduction in battery life, so its use should be carefully weighed.

Most D-Bus language bindings attempts to map D-Bus signals into something more natural in the target language. Since GLib already supports the notion of signals (as GLib signals), this mapping is quite natural. So in practice, the client registers for GLib signals, and then handles the signals in callback functions (a special wrapper function must be used to register for the wrapped signals: <code>dbus_g_proxy_connect_signal</code>).

Next, the <code>Value</code> object is extended so that it contains two threshold values (minimum and maximum), and the object emits signals, whenever a set operation falls outside the thresholds.

In order to make the signals available to introspection data, the interface XML file is modified accordingly: [http://vcs.maemo.org/svn/maemoexamples/trunk/glib-dbus-signals/value-dbus-interface.xml glib-dbus-signals/value-dbus-interface.xml]

<source lang="xml">

<node>

<interface name="org.maemo.Value">

<!- ... Listing cut for brevity ... ->

<!- Signal (D-Bus) definitions ->

<!- NOTE: The current version of dbus-bindings-tool doesn't

    actually enforce the signal arguments _at_all_. Signals need

    to be declared in order to be passed through the bus itself,

    but otherwise no checks are done! For example, you could

    leave the signal arguments unspecified completely, and the

    code would still work. ->

<!- Signals to tell interested clients about state change.

    We send a string parameter with them. They never can have

    arguments with direction=in. ->

<signal name="changed_value1">

<arg type="s" name="change_source_name" direction="out"/>

</signal>

<signal name="changed_value2">

<arg type="s" name="change_source_name" direction="out"/>

</signal>

<!- Signals to tell interested clients that values are outside

    the internally configured range (thresholds). ->

<signal name="outofrange_value1">

<arg type="s" name="outofrange_source_name" direction="out"/>

</signal>

<signal name="outofrange_value2">

<arg type="s" name="outofrange_source_name" direction="out"/>

</signal>

</interface>

</node>

</source>

The signal definitions are required if the <code>dbus-bindings-tool</code> is used; however, the argument specification for each signal is not required by the tool. In fact, the tool ignores all argument specifications, and as can be seen below, a lot of "manual coding" has to be made in order to implement and use the signals (on both the client and server side).

The signal names are defined in a header file so that they can easily be changed later, and the header file is used in both the server and the client. The following is the section with the signal names: [http://vcs.maemo.org/svn/maemoexamples/trunk/glib-dbus-signals/common-defs.h glib-dbus-signals/common-defs.h]

<source lang="c">

/* Symbolic constants for the signal names to use with GLib.

  These need to map into the D-Bus signal names. */

#define SIGNAL_CHANGED_VALUE1    "changed_value1"

#define SIGNAL_CHANGED_VALUE2    "changed_value2"

#define SIGNAL_OUTOFRANGE_VALUE1 "outofrange_value1"

#define SIGNAL_OUTOFRANGE_VALUE2 "outofrange_value2"

</source>

Before a <code>GObject</code> can emit a GLib signal, the signal itself needs to be defined and created. The best way to do this is to use the class constructor code (because the signal types need to be created only once): [http://vcs.maemo.org/svn/maemoexamples/trunk/glib-dbus-signals/server.c glib-dbus-signals/server.c]

<source lang="c">

/**

  * Define enumerations for the different signals that we can generate

  * (so that we can refer to them within the signals-array [below]

  * using symbolic names). These are not the same as the signal name

  * strings.

  *

  * NOTE: E_SIGNAL_COUNT is NOT a signal enum. We use it as a

  *      convenient constant giving the number of signals defined so

  *      far. It needs to be listed last.

  */

typedef enum {

  E_SIGNAL_CHANGED_VALUE1,

  E_SIGNAL_CHANGED_VALUE2,

  E_SIGNAL_OUTOFRANGE_VALUE1,

  E_SIGNAL_OUTOFRANGE_VALUE2,

  E_SIGNAL_COUNT

} ValueSignalNumber;

  /*... Listing cut for brevity ...*/

typedef struct {

  /* The parent class state. */

  GObjectClass parent;

  /* The minimum number under which values cause signals to be

    emitted. */

  gint thresholdMin;

  /* The maximum number over which values cause signals to be

    emitted. */

  gint thresholdMax;

  /* Signals created for this class. */

  guint signals[E_SIGNAL_COUNT];

} ValueObjectClass;

  /*... Listing cut for brevity ...*/

/**

  * Per class initializer

  *

  * Sets up the thresholds (-100 .. 100), creates the signals that we

  * can emit from any object of this class and finally registers the

  * type into the GLib/D-Bus wrapper so that it may add its own magic.

  */

static void value_object_class_init(ValueObjectClass* klass) {

  /* Because all signals have the same prototype (each gets one

    string as a parameter), we create them in a loop below. The only

    difference between them is the index into the klass->signals

    array, and the signal name.

    Because the index goes from 0 to E_SIGNAL_COUNT-1, we just specify

    the signal names into an array and iterate over it.

    Note that the order here must correspond to the order of the

    enumerations before. */

  const gchar* signalNames[E_SIGNAL_COUNT] = {

    SIGNAL_CHANGED_VALUE1,

    SIGNAL_CHANGED_VALUE2,

    SIGNAL_OUTOFRANGE_VALUE1,

    SIGNAL_OUTOFRANGE_VALUE2 };

  /* Loop variable */

  int i;

  dbg("Called");

  g_assert(klass != NULL);

  /* Setup sane minimums and maximums for the thresholds. There is no

    way to change these afterwards (currently), so you can consider

    them as constants. */

  klass->thresholdMin = -100;

  klass->thresholdMax = 100;

  dbg("Creating signals");

  /* Create the signals in one loop, because they all are similar

    (except for the names). */

  for (i = 0; i < E_SIGNAL_COUNT; i++) {

    guint signalId;

    /* Most of the time you encounter the following code without

      comments. This is why all the parameters are documented

      directly below. */

    signalId =

      g_signal_new(signalNames[i], /* str name of the signal */

                  /* GType to which signal is bound to */

                  G_OBJECT_CLASS_TYPE(klass),

                  /* Combination of GSignalFlags which tell the

                      signal dispatch machinery how and when to

                      dispatch this signal. The most common is the

                      G_SIGNAL_RUN_LAST specification. */

                  G_SIGNAL_RUN_LAST,

                  /* Offset into the class structure for the type

                      function pointer. Because we are implementing a

                      simple class/type, we leave this at zero. */

                  0,

                  /* GSignalAccumulator to use. We do not need one. */

                  NULL,

                  /* User-data to pass to the accumulator. */

                  NULL,

                  /* Function to use to marshal the signal data into

                      the parameters of the signal call. Luckily for

                      us, GLib (GCClosure) already defines just the

                      function that we want for a signal handler that

                      we do not expect any return values (void) and

                      one that accepts one string as parameter

                      (besides the instance pointer and pointer to

                      user-data).

                      If no such function exists, you need

                      to create a new one (by using glib-genmarshal

                      tool). */

                  g_cclosure_marshal_VOID__STRING,

                  /* Return GType of the return value. The handler

                      does not return anything, so we use G_TYPE_NONE

                      to mark that. */

                  G_TYPE_NONE,

                  /* Number of parameter GTypes to follow. */

                  1,

                  /* GType(s) of the parameters. We only have one. */

                  G_TYPE_STRING);

    /* Store the signal Id into the class state, so that we can use

      it later. */

    klass->signals[i] = signalId;

    /* Proceed with the next signal creation. */

  }

  /* All signals created. */

  dbg("Binding to GLib/D-Bus");

  /*... Listing cut for brevity ...*/

}

</source>

Emitting the signals is quite easy, but in order to reduce code amount, a utility function is created to launch a given signal based on its enumeration: [http://vcs.maemo.org/svn/maemoexamples/trunk/glib-dbus-signals/server.c glib-dbus-signals/server.c]

<source lang="c">

/**

  * Utility helper to emit a signal given with internal enumeration and

  * the passed string as the signal data.

  *

  * Used in the setter functions below.

  */

static void value_object_emitSignal(ValueObject* obj,

                                    ValueSignalNumber num,

                                    const gchar* message) {

  /* In order to access the signal identifiers, we need to get a hold

    of the class structure first. */

  ValueObjectClass* klass = VALUE_OBJECT_GET_CLASS(obj);

  /* Check that the given num is valid (abort if not).

    Given that this file is the module actually using this utility,

    you can consider this check superfluous (but useful for

    development work). */

  g_assert((num < E_SIGNAL_COUNT) && (num >= 0));

  dbg("Emitting signal id %d, with message '%s'", num, message);

  /* This is the simplest way of emitting signals. */

  g_signal_emit(/* Instance of the object that is generating this

                  signal. This is passed as the first parameter

                  to the signal handler (eventually). But obviously

                  when speaking about D-Bus, a signal caught on the

                  other side of D-Bus is first processed by

                  the GLib-wrappers (the object proxy) and only then

                  processed by the signal handler. */

                obj,

                /* Signal id for the signal to generate. These are

                  stored inside the class state structure. */

                klass->signals[num],

                /* Detail of signal. Because we are not using detailed

                  signals, we leave this at zero (default). */

                0,

                /* Data to marshal into the signal. In our case it is

                  just one string. */

                message);

  /* g_signal_emit returns void, so we cannot check for success. */

  /* Done emitting signal. */

}

</source>

To avoid having to check the threshold values in multiple places in the source code, the threshold value is also implemented as a separate function. Emitting the "threshold exceeded" signal is still up to the caller. [http://vcs.maemo.org/svn/maemoexamples/trunk/glib-dbus-signals/server.c glib-dbus-signals/server.c]

<source lang="c">

/**

  * Utility to check the given integer against the thresholds.

  * Returns TRUE if thresholds are not exceeded, FALSE otherwise.

  *

  * Used in the setter functions below.

  */

static gboolean value_object_thresholdsOk(ValueObject* obj,

                                          gint value) {

  /* Thresholds are in class state data, get access to it */

  ValueObjectClass* klass = VALUE_OBJECT_GET_CLASS(obj);

  return ((value >= klass->thresholdMin) &&

          (value <= klass->thresholdMax));

}

</source>

Both utility functions are then used from within the respective set functions, one of which is presented below: [http://vcs.maemo.org/svn/maemoexamples/trunk/glib-dbus-signals/server.c glib-dbus-signals/server.c]

<source lang="c">

/**

  * Function that gets called when someone tries to execute "setvalue1"

  * over the D-Bus. (Actually the marshalling code from the stubs gets

  * executed first, but eventually they execute this function.)

  */

gboolean value_object_setvalue1(ValueObject* obj, gint valueIn,

                                                  GError** error) {

  dbg("Called (valueIn=%d)", valueIn);

  g_assert(obj != NULL);

  /* Compare the current value against old one. If they're the same,

    we do not need to do anything (except return success). */

  if (obj->value1 != valueIn) {

    /* Change the value. */

    obj->value1 = valueIn;

    /* Emit the "changed_value1" signal. */

    value_object_emitSignal(obj, E_SIGNAL_CHANGED_VALUE1, "value1");

    /* If new value falls outside the thresholds, emit

      "outofrange_value1" signal as well. */

    if (!value_object_thresholdsOk(obj, valueIn)) {

      value_object_emitSignal(obj, E_SIGNAL_OUTOFRANGE_VALUE1,

                                  "value1");

    }

  }

  /* Return success to GLib/D-Bus wrappers. In this case we do not need

    to touch the supplied error pointer-pointer. */

  return TRUE;

}

</source>

The role of the <code>value1</code> string parameter that is sent along both of the signals above can raise a question. Sending the signal origin name with the signal allows you to reuse the same callback function in the client. This kind of "source naming" is rarely useful but it allows for writing a slightly shorter client program.

The implementation of <code>setvalue2</code> is almost identical, but deals with the <code>gdouble</code> parameter.

Next, the server is built and started on the background (in preparation for testing with <code>dbus-send</code>):

<pre>

[sbox-DIABLO_X86: ~/glib-dbus-signals] > make server

dbus-binding-tool --prefix=value_object --mode=glib-server \

  value-dbus-interface.xml > value-server-stub.h

cc -I/usr/include/dbus-1.0 -I/usr/lib/dbus-1.0/include \

-I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include -g -Wall \

-DG_DISABLE_DEPRECATED -DNO_DAEMON -DPROGNAME=\"server\" \

-c server.c -o server.o

cc server.o -o server -ldbus-glib-1 -ldbus-1 -lgobject-2.0 -lglib-2.0

[sbox-DIABLO_X86: ~/glib-dbus-signals] > run-standalone.sh ./server &amp;

[1] 15293

server:main Connecting to the Session D-Bus.

server:main Registering the well-known name (org.maemo.Platdev_ex)

server:main RequestName returned 1.

server:main Creating one Value object.

server:value_object_class_init: Called

server:value_object_class_init: Creating signals

server:value_object_class_init: Binding to GLib/D-Bus

server:value_object_class_init: Done

server:value_object_init: Called

server:main Registering it on the D-Bus.

server:main Ready to serve requests (daemonizing).

server: Not daemonizing (built with NO_DAEMON-build define)

[sbox-DIABLO_X86: ~/glib-dbus-signals] >

The next step is to test the <code>setvalue1</code> method:

/GlobalValue org.maemo.Value.setvalue1 int32:10

method return sender=:1.38 -> dest=:1.41

method return sender=:1.38 -> dest=:1.42

After this, the next step is to test the <code>setvalue2</code> (with <code>double</code>s). At this point, the threshold triggering can behave in an unexpected manner:

<pre>

[sbox-DIABLO_X86: ~/glib-dbus-signals] > run-standalone.sh dbus-send \

</pre>

Because the threshold testing logic truncates the <code>gdouble</code> before testing against the (integer) thresholds, a value of 100.5 is detected as 100 and it still fits within the thresholds.

Instead of printing out the emitted signal names, the enumeration values of the emitted signals are printed. This could be rectified with a small enumeration to string table, but it was omitted from the program for simplicity.

Other than seeing the server messages about emitting the signals, there is no trace of them being sent or received. This is because <code>dbus-send</code> does not listen for signals. A separate tool (<code>dbus-monitor</code>) can be used for tracing signals.

In order to receive D-Bus signals in the client, you need to perform several tasks per signal. This is because <code>dbus-bindings-tool</code> does not generate any code for signals. The aim is to make the GLib wrappers emit GLib signals whenever an interesting D-Bus signal arrives. This also means that registering the interest for a particular D-Bus signal is necessary.

When implementing the callbacks for the signals, the prototype must be implemented correctly. Because the signals are sent with one attached string value, the callbacks receive at least the string parameter. Besides the signal attached arguments, the callback receives the proxy object, through which the signal was received, and optional user-specified data (which is not used in this example, so it is always <code>NULL</code>). [http://vcs.maemo.org/svn/maemoexamples/trunk/glib-dbus-signals/client.c glib-dbus-signals/client.c]

<source lang="c">

* values, and act accordingly (in this case by retrieving

*/

  /* Because method calls over D-Bus can fail, we need to check

  GError* error = NULL;

  g_print(PROGNAME ":value-changed (%s)\n", valueName);

  if (strcmp(valueName, "value1") == 0) {

    /* Execute the RPC to get value1. */

      g_print(PROGNAME ":value-changed Value1 now %d\n", v);

      /* You could interrogate the GError further to find out exactly

        what the error was, but in our case, we just ignore the

        error with the hope that some day (preferably soon), the

      handleError("Failed to retrieve value1", error->message, FALSE);

    org_maemo_Value_getvalue2(proxy, &v, &error);

    if (error == NULL) {

      g_print(PROGNAME ":value-changed Value2 now %.3f\n", v);

      handleError("Failed to retrieve value2", error->message, FALSE);

  /* Free up error object if one was allocated. */

The callback first determines what was the source value that caused the signal to be generated. For this, it uses the string argument of the signal. It then retrieves the current value using the respective RPC methods (<code>getvalue1</code> or <code>getvalue2</code>) and prints out the value.

If any errors occur during the method calls, the errors are printed out, but the program continues to run. If an error does occur, the <code>GError</code> object needs to be freed (performed with <code>g_clear_error</code>). The program does not terminate on RPC errors, because the condition might be temporary (the <code>Value</code> object server might be restarted later).

The code for the <code>outOfRangeSignalHandler</code> callback has been omitted, because it does not contain anything beyond what <code>valueChangedSignalHandler</code> demonstrates.

Registering for the signals is a two-step process. First, it is necessary to register the interest in the D-Bus signals, and then install the callbacks for the respective GLib signals. This is done within main: [http://vcs.maemo.org/svn/maemoexamples/trunk/glib-dbus-signals/client.c glib-dbus-signals/client.c]

* The test program itself.

* 3) Connect to the Session D-Bus

* 5) Register signals that we're interested from the Value object

* 6) Register signal handlers for them

* 7) Start a timer that launches timerCallback once per second.

* 8) Run main-loop (forever)

*/

  /*... Listing cut for brevity ...*/

    dbus_g_proxy_new_for_name(bus,

                              VALUE_SERVICE_INTERFACE /* interface */);

    handleError("Couldn't create the proxy object",

                "Unknown(dbus_g_proxy_new_for_name)", TRUE);

  /* Register the signatures for the signal handlers.

    the signal itself. The parameter list is terminated with

    G_TYPE_INVALID (i.e., the GType for string objects. */

  g_print(PROGNAME ":main Registering signal handler signatures.\n");

  { /* Create a local scope for variables. */

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

The client starts with the timer callback being executed once per second (as before). Each iteration, it calls the <code>setvalue1</code> and <code>setvalue2</code> RPC methods with increasing values. The number for <code>value2</code> is intentionally set below the minimum threshold, so that it causes an <code>outofrange_value2</code> signal to be emitted. For each set, the <code>changed_value</code> signals are also emitted. Whenever the client receives either of the value change signals, it performs a <code>getvalue</code> RPC method call to retrieve the current value and print it out.

Sometimes seeing which signals are actually carried on the buses can be useful, especially when adding signal handlers for signals that are emitted from undocumented interfaces. The <code>dbus-monitor</code> tool attaches to the D-Bus daemon, and asks it to watch for signals and report them back to the tool, so that it can decode the signals automatically, as they appear on the bus.

While the server and client are still running, the next step is to start the <code>dbus-monitor</code> (in a separate session this time) to see whether the signals are transmitted correctly. It should be noted that signals appear on the bus even if there are no clients currently interested in them. In this case, signals are emitted by the server, based on client-issued RPC methods, so if the client is terminated, the signals cease.

Nokia-N810-xx-xx:~# run-standalone.sh dbus-monitor --system

signal sender=:1.3 -> dest=(null destination) path=/com/nokia/mce/signal;  

interface=com.nokia.mce.signal; member=display_status_ind

string "dimmed"

signal sender=:1.3 -> dest=(null destination) path=/com/nokia/mce/signal;  

interface=com.nokia.mce.signal; member=system_inactivity_ind

boolean true

signal sender=:1.3 -> dest=(null destination) path=/com/nokia/mce/signal;  

interface=com.nokia.mce.signal; member=save_unsaved_data_ind

signal sender=:1.3 -> dest=(null destination) path=/com/nokia/mce/signal;  

interface=com.nokia.mce.signal; member=display_status_ind

string "off"

signal sender=:1.3 -> dest=(null destination) path=/com/nokia/mce/signal;  

interface=com.nokia.mce.signal; member=system_inactivity_ind

boolean false

signal sender=:1.3 -> dest=(null destination) path=/com/nokia/mce/signal;  

interface=com.nokia.mce.signal; member=display_status_ind

string "on"

signal sender=:1.3 -> dest=(null destination) path=/com/nokia/mce/signal;  

interface=com.nokia.mce.signal; member=tklock_mode_ind

string "unlocked"