## Generating code and docs

### Using gdbus-codegen

dbus-glib comes with dbus-binding-tool, which can produce somewhat nice client- and server-side wrappers for a D-Bus interface. With GDBus, gdbus-codegen is used and like its counterpart, it also takes D-Bus Introspection XML as input:

Example 24. Example D-Bus Introspection XML

    <node>
      <!-- org.gtk.GDBus.Example.ObjectManager.Animal:
           @short_description: Example docs generated by gdbus-codegen
           @since: 2.30

           This D-Bus interface is used to describe a simple animal.
        -->
      <interface name="org.gtk.GDBus.Example.ObjectManager.Animal">
        <!-- Mood: The mood of the animal.
             @since: 2.30

             Known values for this property include
             <literal>Happy</literal> and <literal>Sad</literal>. Use the
             org.gtk.GDBus.Example.ObjectManager.Animal.Poke() method to
             change this property.

             This property influences how often the animal jumps up and
             down, see the
             #org.gtk.GDBus.Example.ObjectManager.Animal::Jumped signal
             for more details.
        -->
        <property name="Mood" type="s" access="read"/>

        <!--
            Poke:
            @make_sad: Whether to make the animal sad.
            @make_happy: Whether to make the animal happy.
            @since: 2.30

            Method used to changing the mood of the animal. See also the
            #org.gtk.GDBus.Example.ObjectManager.Animal:Mood property.
          -->
        <method name="Poke">
          <arg direction="in" type="b" name="make_sad"/>
          <arg direction="in" type="b" name="make_happy"/>
        </method>

        <!--
            Jumped:
            @height: Height, in meters, that the animal jumped.
            @since: 2.30

            Emitted when the animal decides to jump.
          -->
        <signal name="Jumped">
          <arg type="d" name="height"/>
        </signal>
      </interface>

      <!-- org.gtk.GDBus.Example.ObjectManager.Cat:
           @short_description: More example docs generated by gdbus-codegen

           This D-Bus interface is used to describe a cat. Right now there
           are no properties, methods or signals associated with this
           interface so it is essentially a <ulink
           url="http://en.wikipedia.org/wiki/Marker_interface_pattern">Marker
           Interface</ulink>.

           Note that D-Bus objects implementing this interface also
           implement the #org.gtk.GDBus.Example.ObjectManager.Animal
           interface.
        -->
      <interface name="org.gtk.GDBus.Example.ObjectManager.Cat">
      </interface>
    </node>

If this XML is processed like this

    gdbus-codegen --interface-prefix org.gtk.GDBus.Example.ObjectManager. \
                  --generate-c-code generated-code	                      \
                  --c-namespace Example 				      \
                  --c-generate-object-manager			      \
                  --generate-docbook generated-docs                       \
                  gdbus-example-objectmanager.xml

then two files `generated-code.h` and `generated-code.c` are generated. Additionally, two XML files `generated-docs-org.gtk.GDBus.Example.ObjectManager.Animal` and `generated-docs-org.gtk.GDBus.Example.ObjectManager.Cat` with Docbook XML are generated. For an example of what the docs look like see the Animal D-Bus interface documentation. and the Cat D-Bus interface documentation.

While the contents of `generated-code.h` and `generated-code.c` are best described by the gdbus-codegen manual page, brief examples of how this generated code can be used can be found in Example 25, “Server-side application using generated code” and Example 26, “Client-side application using generated code”. Additionally, since the generated code has 100% gtk-doc coverage, see ExampleAnimal, ExampleCat, ExampleObject and ExampleObjectManagerClient pages for documentation.

Example 25. Server-side application using generated code

    #include "gdbus-example-objectmanager-generated.h"

    /* ---------------------------------------------------------------------------------------------------- */

    static GDBusObjectManagerServer *manager = NULL;

    static gboolean
    on_animal_poke (ExampleAnimal          *animal,
                    GDBusMethodInvocation  *invocation,
                    gboolean                make_sad,
                    gboolean                make_happy,
                    gpointer                user_data)
    {
      if ((make_sad && make_happy) || (!make_sad && !make_happy))
        {
          g_dbus_method_invocation_return_dbus_error (invocation,
                                                      "org.gtk.GDBus.Examples.ObjectManager.Error.Failed",
                                                      "Exactly one of make_sad or make_happy must be TRUE");
          goto out;
        }

      if (make_sad)
        {
          if (g_strcmp0 (example_animal_get_mood (animal), "Sad") == 0)
            {
              g_dbus_method_invocation_return_dbus_error (invocation,
                                                          "org.gtk.GDBus.Examples.ObjectManager.Error.SadAnimalIsSad",
                                                          "Sad animal is already sad");
              goto out;
            }

          example_animal_set_mood (animal, "Sad");
          example_animal_complete_poke (animal, invocation);
          goto out;
        }

      if (make_happy)
        {
          if (g_strcmp0 (example_animal_get_mood (animal), "Happy") == 0)
            {
              g_dbus_method_invocation_return_dbus_error (invocation,
                                                          "org.gtk.GDBus.Examples.ObjectManager.Error.HappyAnimalIsHappy",
                                                          "Happy animal is already happy");
              goto out;
            }

          example_animal_set_mood (animal, "Happy");
          example_animal_complete_poke (animal, invocation);
          goto out;
        }

      g_assert_not_reached ();

     out:
      return TRUE; /* to indicate that the method was handled */
    }

    static void
    on_bus_acquired (GDBusConnection *connection,
                     const gchar     *name,
                     gpointer         user_data)
    {
      ExampleObjectSkeleton *object;
      guint n;

      g_print ("Acquired a message bus connection\n");

      /* Create a new org.freedesktop.DBus.ObjectManager rooted at /example/Animals */
      manager = g_dbus_object_manager_server_new ("/example/Animals");

      for (n = 0; n < 10; n++)
        {
          gchar *s;
          ExampleAnimal *animal;

          /* Create a new D-Bus object at the path /example/Animals/N where N is 000..009 */
          s = g_strdup_printf ("/example/Animals/%03d", n);
          object = example_object_skeleton_new (s);
          g_free (s);

          /* Make the newly created object export the interface
           * org.gtk.GDBus.Example.ObjectManager.Animal (note
           * that @object takes its own reference to @animal).
           */
          animal = example_animal_skeleton_new ();
          example_animal_set_mood (animal, "Happy");
          example_object_skeleton_set_animal (object, animal);
          g_object_unref (animal);

          /* Cats are odd animals - so some of our objects implement the
           * org.gtk.GDBus.Example.ObjectManager.Cat interface in addition
           * to the .Animal interface
           */
          if (n % 2 == 1)
            {
              ExampleCat *cat;
              cat = example_cat_skeleton_new ();
              example_object_skeleton_set_cat (object, cat);
              g_object_unref (cat);
            }

          /* Handle Poke() D-Bus method invocations on the .Animal interface */
          g_signal_connect (animal,
                            "handle-poke",
                            G_CALLBACK (on_animal_poke),
                            NULL); /* user_data */

          /* Export the object (@manager takes its own reference to @object) */
          g_dbus_object_manager_server_export (manager, G_DBUS_OBJECT_SKELETON (object));
          g_object_unref (object);
        }

      /* Export all objects */
      g_dbus_object_manager_server_set_connection (manager, connection);
    }

    static void
    on_name_acquired (GDBusConnection *connection,
                      const gchar     *name,
                      gpointer         user_data)
    {
      g_print ("Acquired the name %s\n", name);
    }

    static void
    on_name_lost (GDBusConnection *connection,
                  const gchar     *name,
                  gpointer         user_data)
    {
      g_print ("Lost the name %s\n", name);
    }

    gint
    main (gint argc, gchar *argv[])
    {
      GMainLoop *loop;
      guint id;

      g_type_init ();

      loop = g_main_loop_new (NULL, FALSE);

      id = g_bus_own_name (G_BUS_TYPE_SESSION,
                           "org.gtk.GDBus.Examples.ObjectManager",
                           G_BUS_NAME_OWNER_FLAGS_ALLOW_REPLACEMENT |
                           G_BUS_NAME_OWNER_FLAGS_REPLACE,
                           on_bus_acquired,
                           on_name_acquired,
                           on_name_lost,
                           loop,
                           NULL);

      g_main_loop_run (loop);

      g_bus_unown_name (id);
      g_main_loop_unref (loop);

      return 0;
    }

Example 26. Client-side application using generated code

    #include "gdbus-example-objectmanager-generated.h"

    /* ---------------------------------------------------------------------------------------------------- */

    static void
    print_objects (GDBusObjectManager *manager)
    {
      GList *objects;
      GList *l;

      g_print ("Object manager at %s\n", g_dbus_object_manager_get_object_path (manager));
      objects = g_dbus_object_manager_get_objects (manager);
      for (l = objects; l != NULL; l = l->next)
        {
          ExampleObject *object = EXAMPLE_OBJECT (l->data);
          GList *interfaces;
          GList *ll;
          g_print (" - Object at %s\n", g_dbus_object_get_object_path (G_DBUS_OBJECT (object)));

          interfaces = g_dbus_object_get_interfaces (G_DBUS_OBJECT (object));
          for (ll = interfaces; ll != NULL; ll = ll->next)
            {
              GDBusInterface *interface = G_DBUS_INTERFACE (ll->data);
              g_print ("   - Interface %s\n", g_dbus_interface_get_info (interface)->name);

              /* Note that @interface is really a GDBusProxy instance - and additionally also
               * an ExampleAnimal or ExampleCat instance - either of these can be used to
               * invoke methods on the remote object. For example, the generated function
               *
               *  void example_animal_call_poke_sync (ExampleAnimal  *proxy,
               *                                      gboolean        make_sad,
               *                                      gboolean        make_happy,
               *                                      GCancellable   *cancellable,
               *                                      GError        **error);
               *
               * can be used to call the Poke() D-Bus method on the .Animal interface.
               * Additionally, the generated function
               *
               *  const gchar *example_animal_get_mood (ExampleAnimal *object);
               *
               * can be used to get the value of the :Mood property.
               */
            }
          g_list_free_full (interfaces, g_object_unref);
        }
      g_list_free_full (objects, g_object_unref);
    }

    static void
    on_object_added (GDBusObjectManager *manager,
                     GDBusObject        *object,
                     gpointer            user_data)
    {
      gchar *owner;
      owner = g_dbus_object_manager_client_get_name_owner (G_DBUS_OBJECT_MANAGER_CLIENT (manager));
      g_print ("Added object at %s (owner %s)\n", g_dbus_object_get_object_path (object), owner);
      g_free (owner);
    }

    static void
    on_object_removed (GDBusObjectManager *manager,
                       GDBusObject        *object,
                       gpointer            user_data)
    {
      gchar *owner;
      owner = g_dbus_object_manager_client_get_name_owner (G_DBUS_OBJECT_MANAGER_CLIENT (manager));
      g_print ("Removed object at %s (owner %s)\n", g_dbus_object_get_object_path (object), owner);
      g_free (owner);
    }

    static void
    on_notify_name_owner (GObject    *object,
                          GParamSpec *pspec,
                          gpointer    user_data)
    {
      GDBusObjectManagerClient *manager = G_DBUS_OBJECT_MANAGER_CLIENT (object);
      gchar *name_owner;

      name_owner = g_dbus_object_manager_client_get_name_owner (manager);
      g_print ("name-owner: %s\n", name_owner);
      g_free (name_owner);
    }

    static void
    on_interface_proxy_properties_changed (GDBusObjectManagerClient *manager,
                                           GDBusObjectProxy         *object_proxy,
                                           GDBusProxy               *interface_proxy,
                                           GVariant                 *changed_properties,
                                           const gchar *const       *invalidated_properties,
                                           gpointer                  user_data)
    {
      GVariantIter iter;
      const gchar *key;
      GVariant *value;
      gchar *s;

      g_print ("Properties Changed on %s:\n", g_dbus_object_get_object_path (G_DBUS_OBJECT (object_proxy)));
      g_variant_iter_init (&iter, changed_properties);
      while (g_variant_iter_next (&iter, "{&sv}", &key, &value))
        {
          s = g_variant_print (value, TRUE);
          g_print ("  %s -> %s\n", key, s);
          g_variant_unref (value);
          g_free (s);
        }
    }

    gint
    main (gint argc, gchar *argv[])
    {
      GDBusObjectManager *manager;
      GMainLoop *loop;
      GError *error;
      gchar *name_owner;

      manager = NULL;
      loop = NULL;

      g_type_init ();

      loop = g_main_loop_new (NULL, FALSE);

      error = NULL;
      manager = example_object_manager_client_new_for_bus_sync (G_BUS_TYPE_SESSION,
                                                                G_DBUS_OBJECT_MANAGER_CLIENT_FLAGS_NONE,
                                                                "org.gtk.GDBus.Examples.ObjectManager",
                                                                "/example/Animals",
                                                                NULL, /* GCancellable */
                                                                &error);
      if (manager == NULL)
        {
          g_printerr ("Error getting object manager client: %s", error->message);
          g_error_free (error);
          goto out;
        }

      name_owner = g_dbus_object_manager_client_get_name_owner (G_DBUS_OBJECT_MANAGER_CLIENT (manager));
      g_print ("name-owner: %s\n", name_owner);
      g_free (name_owner);

      print_objects (manager);

      g_signal_connect (manager,
                        "notify::name-owner",
                        G_CALLBACK (on_notify_name_owner),
                        NULL);
      g_signal_connect (manager,
                        "object-added",
                        G_CALLBACK (on_object_added),
                        NULL);
      g_signal_connect (manager,
                        "object-removed",
                        G_CALLBACK (on_object_removed),
                        NULL);
      g_signal_connect (manager,
                        "interface-proxy-properties-changed",
                        G_CALLBACK (on_interface_proxy_properties_changed),
                        NULL);

      g_main_loop_run (loop);

     out:
      if (manager != NULL)
        g_object_unref (manager);
      if (loop != NULL)
        g_main_loop_unref (loop);

      return 0;
    }