D-Bus Utilities: GIO Reference Manual

## D-Bus Utilities D-Bus Utilities — Various utilities related to D-Bus |

## Functions

gchar * | g_dbus_generate_guid ()
gboolean | g_dbus_is_guid ()
gboolean | g_dbus_is_name ()
gboolean | g_dbus_is_unique_name ()
gboolean | g_dbus_is_member_name ()
gboolean | g_dbus_is_interface_name ()
gboolean | g_dbus_is_error_name ()
GVariant * | g_dbus_gvalue_to_gvariant ()
void | g_dbus_gvariant_to_gvalue ()
gchar * | g_dbus_escape_object_path_bytestring ()
gchar * | g_dbus_escape_object_path ()
guint8 * | g_dbus_unescape_object_path ()

## Includes

    #include <gio/gio.h>

## Description

Various utility routines related to D-Bus.

## Functions

### g_dbus_generate_guid ()

    gchar *
    g_dbus_generate_guid (void);

Generate a D-Bus GUID that can be used with e.g. `g_dbus_connection_new()`.

See the D-Bus specification regarding what strings are valid D-Bus GUIDs. The specification refers to these as ‘UUIDs’ whereas GLib (for historical reasons) refers to them as ‘GUIDs’. The terms are interchangeable.

Note that D-Bus GUIDs do not follow RFC 4122.

#### Returns

A valid D-Bus GUID. Free with `g_free()`.

Since: 2.26

### g_dbus_is_guid ()

    gboolean
    g_dbus_is_guid (const gchar *string);

Checks if `string` is a D-Bus GUID.

See the documentation for `g_dbus_generate_guid()` for more information about the format of a GUID.

#### Parameters

string | The string to check. |

#### Returns

`TRUE` if `string` is a GUID, `FALSE` otherwise.

Since: 2.26

### g_dbus_is_name ()

    gboolean
    g_dbus_is_name (const gchar *string);

Checks if `string` is a valid D-Bus bus name (either unique or well-known).

#### Parameters

string | The string to check. |

#### Returns

`TRUE` if valid, `FALSE` otherwise.

Since: 2.26

### g_dbus_is_unique_name ()

    gboolean
    g_dbus_is_unique_name (const gchar *string);

Checks if `string` is a valid D-Bus unique bus name.

#### Parameters

string | The string to check. |

#### Returns

`TRUE` if valid, `FALSE` otherwise.

Since: 2.26

### g_dbus_is_member_name ()

    gboolean
    g_dbus_is_member_name (const gchar *string);

Checks if `string` is a valid D-Bus member (e.g. signal or method) name.

#### Parameters

string | The string to check. |

#### Returns

`TRUE` if valid, `FALSE` otherwise.

Since: 2.26

### g_dbus_is_interface_name ()

    gboolean
    g_dbus_is_interface_name (const gchar *string);

Checks if `string` is a valid D-Bus interface name.

#### Parameters

string | The string to check. |

#### Returns

`TRUE` if valid, `FALSE` otherwise.

Since: 2.26

### g_dbus_is_error_name ()

    gboolean
    g_dbus_is_error_name (const gchar *string);

Check whether `string` is a valid D-Bus error name.

This function returns the same result as `g_dbus_is_interface_name()`, because D-Bus error names are defined to have exactly the same syntax as interface names.

#### Parameters

string | The string to check. |

#### Returns

`TRUE` if valid, `FALSE` otherwise.

Since: 2.70

### g_dbus_gvalue_to_gvariant ()

    GVariant *
    g_dbus_gvalue_to_gvariant (const GValue *gvalue,
                               const GVariantType *type);

Converts a GValue to a GVariant of the type indicated by the `type` parameter.

The conversion is using the following rules:

- G_TYPE_STRING: 's', 'o', 'g' or 'ay'

- G_TYPE_STRV: 'as', 'ao' or 'aay'

- G_TYPE_BOOLEAN: 'b'

- G_TYPE_UCHAR: 'y'

- G_TYPE_INT: 'i', 'n'

- G_TYPE_UINT: 'u', 'q'

- G_TYPE_INT64 'x'

- G_TYPE_UINT64: 't'

- G_TYPE_DOUBLE: 'd'

- G_TYPE_VARIANT: Any GVariantType

This can fail if e.g. `gvalue` is of type G_TYPE_STRING and `type` is 'i'. It will also fail for any GType (including e.g. G_TYPE_OBJECT and G_TYPE_BOXED derived-types) not in the table above.

Note that if `gvalue` is of type G_TYPE_VARIANT and its value is `NULL`, the empty GVariant instance (never `NULL`) for `type` is returned (e.g. 0 for scalar types, the empty string for string types, '/' for object path types, the empty array for any array type and so on).

See the `g_dbus_gvariant_to_gvalue()` function for how to convert a GVariant to a GValue.

#### Parameters

gvalue | A GValue to convert to a GVariant |
type | A GVariantType |

#### Returns

A GVariant (never floating) of GVariantType `type` holding the data from `gvalue` or an empty GVariant in case of failure. Free with `g_variant_unref()`.

[transfer full]

Since: 2.30

### g_dbus_gvariant_to_gvalue ()

    void
    g_dbus_gvariant_to_gvalue (GVariant *value,
                               GValue *out_gvalue);

Converts a GVariant to a GValue. If `value` is floating, it is consumed.

The rules specified in the `g_dbus_gvalue_to_gvariant()` function are used - this function is essentially its reverse form. So, a GVariant containing any basic or string array type will be converted to a GValue containing a basic value or string array. Any other GVariant (handle, variant, tuple, dict entry) will be converted to a GValue containing that GVariant.

The conversion never fails - a valid GValue is always returned in `out_gvalue` .

#### Parameters

value | A GVariant. |
out_gvalue | Return location pointing to a zero-filled (uninitialized) GValue. | [out]

Since: 2.30

### g_dbus_escape_object_path_bytestring ()

    gchar *
    g_dbus_escape_object_path_bytestring (const guint8 *bytes);

Escapes `bytes` for use in a D-Bus object path component. `bytes` is an array of zero or more nonzero bytes in an unspecified encoding, followed by a single zero byte.

The escaping method consists of replacing all non-alphanumeric characters (see `g_ascii_isalnum()`) with their hexadecimal value preceded by an underscore (`_`). For example: `foo.bar.baz` will become `foo_2ebar_2ebaz`.

This method is appropriate to use when the input is nearly a valid object path component but is not when your input is far from being a valid object path component. Other escaping algorithms are also valid to use with D-Bus object paths.

This can be reversed with `g_dbus_unescape_object_path()`.

#### Parameters

bytes | the string of bytes to escape. | [array zero-terminated=1][element-type guint8]

#### Returns

an escaped version of `bytes` . Free with `g_free()`.

Since: 2.68

### g_dbus_escape_object_path ()

    gchar *
    g_dbus_escape_object_path (const gchar *s);

This is a language binding friendly version of `g_dbus_escape_object_path_bytestring()`.

#### Parameters

s | the string to escape |

#### Returns

an escaped version of `s` . Free with `g_free()`.

Since: 2.68

### g_dbus_unescape_object_path ()

    guint8 *
    g_dbus_unescape_object_path (const gchar *s);

Unescapes an string that was previously escaped with `g_dbus_escape_object_path()`. If the string is in a format that could not have been returned by `g_dbus_escape_object_path()`, this function returns `NULL`.

Encoding alphanumeric characters which do not need to be encoded is not allowed (e.g `_63` is not valid, the string should contain `c` instead).

#### Parameters

s | the string to unescape |

#### Returns

an unescaped version of `s` , or `NULL` if `s` is not a string returned from `g_dbus_escape_object_path()`. Free with `g_free()`.

[array zero-terminated=1][element-type guint8][nullable]

Since: 2.68