Module DBus::Binding
In: ruby-dbus.c
lib/dbus/binding.rb

The DBus::Binding module contains the internal binding classes that map directly to the D-BUS C API.

Methods

Classes and Modules

Class DBus::Binding::DBusConnection
Class DBus::Binding::DBusMessage
Class DBus::Binding::DBusMessageIter
Class DBus::Binding::DBusPendingCall
Class DBus::Binding::DBusServer

Public Instance methods

Asks the bus connected to the given connection to acquire a service. This can be useful for ensuring only one instance of your program is running.

[Source]

/*
 *  call-seq:
 *      bus_acquire_service(connection, service_name, [flags=0]) => retcode
 *
 *  Asks the bus connected to the given connection to acquire a service. This
 *  can be useful for ensuring only one instance of your program is running.
 */
static VALUE
mDBusBinding_bus_acquire_service(int argc, VALUE *argv)
{
  VALUE conn;
  VALUE name;
  VALUE flags; int service_flags;
  int ret;

  conn = name = flags = Qnil;
  service_flags = 0;
  rb_scan_args(argc, argv, "21", &conn, &name, &flags);
  if (flags != Qnil)
    service_flags = NUM2INT(flags);
  ret = 0;
  RDBUS_TRY(
    ret = dbus_bus_acquire_service(CONN_GET(conn),
                                   StringValuePtr(name),
                                   service_flags,
                                   &error)
  );
  return INT2FIX(ret);
}

Activates the given service. The flags parameter currently (D-BUS 0.22) does nothing.

[Source]

/*
 *  call-seq:
 *      bus_activate_service(connection, service_name, [flags=0]) => [true|false, result]
 * 
 *  Activates the given service. The flags parameter currently (D-BUS 0.22) does
 *  nothing.
 */
static VALUE
mDBusBinding_bus_activate_service(int argc, VALUE *argv)
{
  VALUE conn;
  VALUE name;
  VALUE flags;
  dbus_uint32_t service_flags;
  dbus_uint32_t result;
  VALUE ret;
  dbus_bool_t dbus_ret;

  conn = name = flags = Qnil;
  service_flags = 0;
  rb_scan_args(argc, argv, "21", &conn, &name, &flags);
  if (flags != Qnil)
    service_flags = NUM2INT(flags);

  result = 0;
  dbus_ret = FALSE;
  RDBUS_TRY(
    dbus_ret = dbus_bus_activate_service(CONN_GET(conn), StringValuePtr(name),
                                         service_flags, &result, &error)
  );

  ret = rb_ary_new();
  rb_ary_push(ret, dbus_ret ? Qtrue : Qfalse);
  rb_ary_push(ret, INT2NUM(result));
  return ret;
}

Adds a match rule on the given connection to match messages passing through the bus. A match rule is a string with key=value pairs seperated by commas.

Match keys:

type
matches the message type, which can be one of method_call, method_return, signal or error
interface
matches the interface field of a message
member
matches the member field of a message
path
matches the path field of a message
destination
matches the destination (recipient) of a message

In order to receive the messages matching rules added by this method, you will need to install a message filter on the connection using DBusConnection#add_filter

[Source]

/*
 *  call-seq:
 *      bus_add_match(connection, rule) => nil
 *  
 *  Adds a match rule on the given connection to match messages passing
 *  through the bus. A match rule is a string with <tt>key=value</tt> pairs
 *  seperated by commas.
 *
 *  Match keys:
 *  [+type+]        matches the message type, which can be one of +method_call+,
 *                  +method_return+, +signal+ or +error+
 *  [+interface+]   matches the interface field of a message
 *  [+member+]      matches the member field of a message
 *  [+path+]        matches the path field of a message
 *  [+destination+] matches the destination (recipient) of a message
 *
 *  In order to receive the messages matching rules added by this method, you
 *  will need to install a message filter on the connection using
 *  DBusConnection#add_filter
 */
static VALUE
mDBusBinding_bus_add_match(VALUE klass, VALUE conn, VALUE rule)
{
  RDBUS_TRY(dbus_bus_add_match(CONN_GET(conn), StringValuePtr(rule), &error));
  return Qnil;
}

Connects to a D-BUS daemon and registers the client with it. Existing bus connections are re-used.

[Source]

/*
 *  call-seq:
 *      bus_get(type=BUS_SESSION) => connection
 *  
 *  Connects to a D-BUS daemon and registers the client with it.
 *  Existing bus connections are re-used.
 */
static VALUE
mDBusBinding_bus_get(int argc, VALUE *argv)
{
  VALUE type;
  DBusConnection *conn;
  DBusBusType bus_type;

  type = Qnil;
  bus_type = DBUS_BUS_SESSION;
  rb_scan_args(argc, argv, "01", &type);
  if (type != Qnil)
    bus_type = (DBusBusType)NUM2INT(type);
  switch (bus_type) {
    case DBUS_BUS_SESSION:
    case DBUS_BUS_SYSTEM:
    case DBUS_BUS_ACTIVATION:
      /* fall-through */
      break;
    default:
      rb_raise(eDBusError, "unsupported D-BUS bus type %d", bus_type);
  }

  conn = NULL;
  RDBUS_TRY(conn = dbus_bus_get(bus_type, &error));
  RDBUS_RAISE_IF(conn == NULL, "failed to open D-BUS connection");
  return CONN_NEW(conn);
}

Gets the base service name of the given connection. This value can be used for the destination field of a DBusMessage.

[Source]

/*
 *  call-seq:
 *      bus_get_base_service(connection) => name
 *
 *  Gets the base service name of the given connection. This value can be used 
 *  for the +destination+ field of a DBusMessage.
 */
static VALUE
mDBusBinding_bus_get_base_service(VALUE klass, VALUE conn)
{
  return rb_str_new2(dbus_bus_get_base_service(CONN_GET(conn)));
}

Gets the UNIX user ID for for the given service on this bus.

[Source]

/*
 *  call-seq:
 *      bus_get_unix_user(connection, service_name) => uid
 *
 *  Gets the UNIX user ID for for the given service on this bus.
 */
static VALUE
mDBusBinding_bus_get_unix_user(VALUE klass, VALUE conn, VALUE name)
{
  VALUE uid;

  uid = -1;
  RDBUS_TRY(
    uid = LONG2NUM(dbus_bus_get_unix_user(CONN_GET(conn),
                                          StringValuePtr(name), &error))
  );
  return uid;
}

Registers a connection with the bus

[Source]

/*
 *  call-seq:
 *      bus_register(connection) => true|false
 *
 *  Registers a connection with the bus
 */
static VALUE
mDBusBinding_bus_register(VALUE klass, VALUE conn)
{
  dbus_bool_t ret;

  ret = FALSE;
  RDBUS_TRY(
    ret = dbus_bus_register(CONN_GET(conn), &error)
  );

  if (ret)
    return Qtrue;
  return Qfalse;
}

Removes a match rule previously added with DBus::Binding#bus_add_match

[Source]

/*
 *  call-seq:
 *      bus_remove_match(connection, rule) => nil
 *
 *  Removes a match rule previously added with DBus::Binding#bus_add_match
 */
static VALUE
mDBusBinding_bus_remove_match(VALUE klass, VALUE conn, VALUE rule)
{
  RDBUS_TRY(dbus_bus_remove_match(CONN_GET(conn), StringValuePtr(rule), &error));
  return Qnil;
}

Checks whether the given service exists on the bus, true is returned if it does, false otherwise.

[Source]

/*
 *  call-seq:
 *      bus_service_exists(connection, service_name) => true | false
 *
 *  Checks whether the given service exists on the bus, +true+ is returned
 *  if it does, +false+ otherwise.
 */
static VALUE
mDBusBinding_bus_service_exists(VALUE klass, VALUE conn, VALUE name)
{
  dbus_bool_t ret;

  ret = FALSE;
  RDBUS_TRY(
    ret = dbus_bus_service_exists(CONN_GET(conn), StringValuePtr(name),
                                  &error)
  );
  if (ret)
    return Qtrue;
  return Qfalse;
}

Sets the base service name of the given connection.

[Source]

/*
 *  call-seq:
 *      bus_set_base_service(connection, base_service) => true|false
 *
 *  Sets the base service name of the given connection.
 *
 */
static VALUE
mDBusBinding_bus_set_base_service(VALUE klass, VALUE conn, VALUE name)
{
  if (!dbus_bus_set_base_service(CONN_GET(conn), StringValuePtr(name)))
    return Qfalse;
  return Qtrue;
}

Initializes Glib GThreads for usage by D-BUS.

This is only necessary for applications that will be using GThreads.

[Source]

/*
 *  Initializes Glib GThreads for usage by D-BUS. 
 *
 *  This is only necessary for applications that will be using GThreads.
 */
static VALUE
mDBusBinding_init_gthreads(VALUE klass)
{
  dbus_g_thread_init();
  return Qnil;
}

[Validate]