BlueZ Part 5: Understanding DBUS – Get property – (4)

Delving Deeper into D-Bus Standard Interfaces:

In our previous blog post, we journeyed through the foundational elements of D-Bus services, exploring the nuances of service, object path, and interfaces. Now, it’s time to dive deeper into the heart of D-Bus: the standard interfaces.

You might have noticed that we glossed over some significant aspects of the D-Bus specification, such as the message protocol, authentication protocol, marshaling, and transports. While these components are crucial to the comprehensive understanding of D-Bus, our current focus is on mastering D-Bus from an application consumer’s perspective.

Why this approach, you ask? Simply put, our immediate goal is to effectively utilize D-Bus for developing with BlueZ, the official Linux Bluetooth protocol stack. By understanding how to consume D-Bus services, we can seamlessly integrate and leverage its capabilities in our applications. Once we’ve solidified this knowledge, we will circle back to delve into the broader, intricate details of D-Bus, including its underlying protocols and mechanisms.

In this blog post, we’ll dissect the internals of D-Bus standard interfaces, providing you with a clear, detailed understanding of how to interact with D-Bus in your projects. Whether you’re a seasoned developer or a newcomer to D-Bus, this exploration will equip you with the insights needed to harness the power of D-Bus in your applications.

So, let’s get started and unravel the complexities of D-Bus standard interfaces, one layer at a time!

Understanding D-Bus Standard Interfaces: Enhancing Interoperability and Efficiency

When the D-Bus daemon is running, it provides a set of standard interfaces with functions and signals that are available system-wide. These interfaces are essential for the seamless operation of various services, such as BlueZ, the official Linux Bluetooth protocol stack. By leveraging these standard interfaces, services like BlueZ can avoid the redundancy of implementing common features from scratch.

The Power of Standard Interfaces

Standard interfaces in D-Bus play a crucial role in simplifying the development process. For instance, common tasks like getting or setting a property are handled by these standard interfaces, eliminating the need for each service to implement its own version of these functions. This uniformity not only reduces development time but also ensures consistency across different applications and services.

One of the significant advantages of D-Bus is its ability to dynamically manage objects and interfaces. Consider a scenario where a new Bluetooth device appears or connects to your host adapter. In such cases, new object paths are dynamically added, along with the interfaces and objects provided by these interfaces. This dynamic nature allows applications consuming BlueZ to be aware of new devices as they appear.

Asynchronous Notifications and Callbacks

D-Bus excels in providing asynchronous notifications through callbacks. When a new interface is added or removed, D-Bus can notify interested applications, enabling them to react promptly to changes in the system. This is particularly useful for applications that need to stay updated about new devices or changes in device status.

For example, when a new Bluetooth device connects, BlueZ can notify applications about the new device through a D-Bus signal. Applications can then handle this event asynchronously, updating their state or performing necessary actions without blocking other operations.

Exploring D-Bus Standard Interfaces

Let’s delve into some of the key standard interfaces defined in the D-Bus specification:

1. org.freedesktop.DBus.Properties:
   • Get: Retrieves the value of a property.
   • Set: Sets the value of a property.
   • GetAll: Retrieves all properties and their values.
   • These methods provide a uniform way to access and modify properties across different services.
2. org.freedesktop.DBus.Introspectable:
   • Introspect: Returns an XML description of the object’s interfaces and methods.
   • This method is essential for understanding the capabilities and structure of objects at runtime.
3. org.freedesktop.DBus.Peer:
   • Ping: A simple method to check if a connection is still alive.
   • GetMachineId: Retrieves the unique identifier for the machine.
   • These methods facilitate basic interactions and diagnostics between D-Bus peers.
4. org.freedesktop.DBus.ObjectManager:
   • GetManagedObjects: Retrieves all managed objects and their interfaces.
   • This method is crucial for applications that need to discover and manage multiple objects dynamically.

Practical Example: BlueZ and D-Bus

Let’s consider a practical example to illustrate the importance of these standard interfaces. Suppose you’re developing an application that interacts with BlueZ to manage Bluetooth devices. By utilizing the org.freedesktop.DBus.ObjectManager interface, your application can retrieve all managed Bluetooth devices and their properties. This allows your application to dynamically discover new devices as they connect or disconnect.

When a new Bluetooth device appears, BlueZ can emit a signal using the org.freedesktop.DBus.Properties.PropertiesChanged method. Your application can listen for this signal and update its user interface or perform other actions in response to the new device. This asynchronous communication ensures that your application remains responsive and efficient.

org.freedesktop.DBus.Properties:

In our previous blog, we used busctl to read the power status of the bluetooth adapter,

$ busctl get-property org.bluez /org/bluez/hci0 org.bluez.Adapter1 Powered
b true

we well now do the same using org.freedesktop.DBus.Properties.Get. Before writing the application to call Get method, we must know the Input and Output DBUS type signature. Without which we will not be able to call Get with appropriate method.

$ busctl introspect org.bluez /org/bluez/hci0 org.freedesktop.DBus.Properties 
NAME                            TYPE      SIGNATURE RESULT/VALUE FLAGS
.Get                            method    ss        v            -
.GetAll                         method    s         a{sv}        -
.Set                            method    ssv       -            -
.PropertiesChanged              signal    sa{sv}as  -

This will show the signature of the Get method. Typically, the Get method has the following signature:

Get(in s interface_name, in s property_name) -> (v value)

Let’s break down this signature:

Input Parameters

1. interface_name (s):
   • Type: String (s)
   • Description: The name of the interface that contains the property you want to get. In the context of BlueZ, this would be "org.bluez.Adapter1".
2. property_name (s):
   • Type: String (s)
   • Description: The name of the property you want to retrieve. For instance, "Powered" in this example.

Output Parameters

1. value (v):
   • Type: Variant (v)
   • Description: The value of the requested property. The Variant type in D-Bus is a flexible container that can hold any type of value. In the context of the Powered property, the actual type contained in the variant is a boolean (b).

Example in C:

#include <gio/gio.h>
#include <stdio.h>

int main(void)
{
    GDBusConnection *connection;
    GError *error = NULL;
    GVariant *result;
    GVariant *value;
    gboolean powered;

    connection = g_bus_get_sync(G_BUS_TYPE_SYSTEM, NULL, &error);
    if (error != NULL) {
        g_printerr("Error connecting to system bus: %s\n", error->message);
        g_error_free(error);
        return 1;
    }

    result = g_dbus_connection_call_sync(
            connection,
            "org.bluez",                   /* Bus name of the BlueZ service */
            "/org/bluez/hci0",             /* Object path of the adapter */
            "org.freedesktop.DBus.Properties", /* Interface name */
            "Get",                         /* Method name */
            g_variant_new("(ss)", "org.bluez.Adapter1", "Powered"), /* Parameters */
            G_VARIANT_TYPE("(v)"),         /* Expected return type */
            G_DBUS_CALL_FLAGS_NONE,
            -1,                            /* Default timeout */
            NULL,                          /* GCancellable */
            &error
            );
    if (error != NULL) {
        g_printerr("Error calling Get method: %s\n", error->message);
        g_error_free(error);
        g_object_unref(connection);
        return 1;
    }

    g_variant_get(result, "(v)", &value);
    g_variant_get(value, "b", &powered);

    g_print("Powered: %s\n", powered ? "true" : "false");

    g_variant_unref(value);
    g_variant_unref(result);
    g_object_unref(connection);

    return 0;
}

You can compile it using

gcc -o bin/get_powered ./get_powered.c `pkg-config --cflags --libs gio-2.0 glib-2.0`

So we read the powered property using DBUS interface using gdbus. We used the synchronous API for quick understanding, which we will repeat using async API.

Conclusion: Unlocking the Power of D-Bus with BlueZ

We’ve successfully explored how to use the D-Bus Get method via the gdbus interface, retrieving the Powered property of a BlueZ adapter with a straightforward C example. This hands-on experience demystifies the D-Bus type system and lays the groundwork for more advanced operations.

Next, we’ll venture into using the Set method to change the power status and the GetAll method to retrieve all properties at once. These techniques will further deepen our understanding of D-Bus and enhance our ability to manipulate BlueZ settings programmatically. Stay tuned as we continue to experiment with BlueZ, uncovering more insights and practical examples along the way. Follow us to keep up with our discoveries and learn more about harnessing the power of these technologies in your projects!