Class DBus::Binding::DBusConnection
In: ruby-dbus.c
lib/dbus/binding.rb
Parent: Object

DBusConnection implements a connection to a D-BUS daemon. D-BUS messages are sent and received using this connection.

The recommended way of obtaining a DBusConnection instance for normal usage is to use DBus::Binding#bus_get to obtain a connection to one of the well-known message buses.

Messages are sent and received when the DBusConnection#dispatch method is called, however, the recommended way to use this is to integrate into an existing main loop such as that of GLib by using DBusConnection#setup_with_g_main, as this hides all the low level internals of dispatching and watch/timeout monitoring from you.

Methods

Public Class methods

Opens a connection to the D-BUS daemon located at the given address. An address is a string in the format type:param1=value1,param2=value2. DBusServer#get_address returns an address in this format.

Example:

    unix:abstract=/tmp/dbus-X0XXgcf

Returns a DBusConnection instance.

[Source]

/*
 *  call-seq:
 *      new(address) => connection
 *
 *  Opens a connection to the D-BUS daemon located at the given +address+.
 *  An address is a string in the format <tt>type:param1=value1,param2=value2</tt>.
 *  DBusServer#get_address returns an address in this format.
 *
 *  Example:
 *      unix:abstract=/tmp/dbus-X0XXgcf
 *
 *  Returns a DBusConnection instance.
 */
static VALUE
cDBusConnection_open(VALUE klass, VALUE address)
{
  DBusConnection *conn;

  conn = NULL;
  RDBUS_TRY(conn = dbus_connection_open(StringValuePtr(address), &error));
  RDBUS_RAISE_IF(conn == NULL, "failed to open D-BUS connection");
  return CONN_NEW_TAKE_OWNERSHIP(conn);
}

Opens a connection to the D-BUS daemon located at the given address. An address is a string in the format type:param1=value1,param2=value2. DBusServer#get_address returns an address in this format.

Example:

    unix:abstract=/tmp/dbus-X0XXgcf

Returns a DBusConnection instance.

[Source]

/*
 *  call-seq:
 *      new(address) => connection
 *
 *  Opens a connection to the D-BUS daemon located at the given +address+.
 *  An address is a string in the format <tt>type:param1=value1,param2=value2</tt>.
 *  DBusServer#get_address returns an address in this format.
 *
 *  Example:
 *      unix:abstract=/tmp/dbus-X0XXgcf
 *
 *  Returns a DBusConnection instance.
 */
static VALUE
cDBusConnection_open(VALUE klass, VALUE address)
{
  DBusConnection *conn;

  conn = NULL;
  RDBUS_TRY(conn = dbus_connection_open(StringValuePtr(address), &error));
  RDBUS_RAISE_IF(conn == NULL, "failed to open D-BUS connection");
  return CONN_NEW_TAKE_OWNERSHIP(conn);
}

Public Instance methods

Adds a message filter on this connection.

The filter_proc block will be called for all incoming messages, before any handlers registered using DBusConnection#register_object_path or DBusConnection#register_fallback.

The same filter block can be added more than once, in which case it will be called more than once.

Returns true if the filter was added, false if there was not enough memory.

[Source]

/*
 *  call-seq:
 *      add_filter(filter_proc) => true | false
 *
 *  Adds a message filter on this connection.
 *
 *  The +filter_proc+ block will be called for all incoming messages,
 *  before any handlers registered using DBusConnection#register_object_path
 *  or DBusConnection#register_fallback.
 *
 *  The same filter block can be added more than once, in which case it
 *  will be called more than once.
 *
 *  Returns +true+ if the filter was added, +false+ if there was not enough
 *  memory.
 */
static VALUE
cDBusConnection_add_filter(VALUE self, VALUE filter_cb)
{
  VALUE *data;

  if (NIL_P(filter_cb))
    rb_raise(eDBusError, "Callback must be supplied");

  data = ALLOC_N(VALUE, 1);
  data[0] = filter_cb;

  if (dbus_connection_add_filter(CONN_GET(self), _on_filter_message,
                                 (void*)data, _free_filter_data))
  {
    rdbus_register_connection_callback(self, filter_cb);
    return Qtrue;
  }

  ruby_xfree(data);
  return Qfalse;
}

Returns the first message from the incoming message queue, while leaving it in the queue. While borrowed, nothing else can get at the message, so the message has to be returned with DBusConnection#return_message or stolen with DBusConnection#steal_borrowed_message.

It is not recommended that you use this method, use the standard dispatching mechanisms instead.

[Source]

/*
 *  call-seq:
 *      borrow_message => message
 *
 *  Returns the first message from the incoming message queue, while
 *  leaving it in the queue. While borrowed, nothing else can get at
 *  the message, so the message <i>has</i> to be returned with
 *  DBusConnection#return_message or stolen with DBusConnection#steal_borrowed_message.
 *
 *  It is not recommended that you use this method, use the standard
 *  dispatching mechanisms instead.
 */
static VALUE
cDBusConnection_borrow_message(VALUE self)
{
  DBusMessage *message;

  message = NULL;
  message = dbus_connection_borrow_message(CONN_GET(self));
  if (message == NULL)
    return Qnil;
  return MSG_NEW(message);
}

Disconnects this connection from the bus

[Source]

/*
 *  call-seq:
 *      disconnect => nil
 *
 *  Disconnects this connection from the bus
 */
static VALUE
cDBusConnection_disconnect(VALUE self)
{
  dbus_connection_disconnect(CONN_GET(self));
  return Qnil;
}

Processes buffered data, handles watches and queues zero or more incoming messages. Pops the first message on the incoming queue, processes it by calling into its handlers, and then unrefs it.

Returns a status indicating whether more messages are available for dispatching, more memory is needed, or all data has been processed.

It is not recommended that you use this directly, instead use the wrapper APIs in DBus::Object, DBus::ObjectTree or DBus::Service and integrate them with your mainloop.

[Source]

/*
 *  call-seq:
 *      dispatch => status
 *
 *  Processes buffered data, handles watches and queues zero or more
 *  incoming messages. Pops the first message on the incoming queue,
 *  processes it by calling into its handlers, and then unrefs it.
 *
 *  Returns a status indicating whether more messages are available for
 *  dispatching, more memory is needed, or all data has been processed.
 *
 *  It is not recommended that you use this directly, instead use the
 *  wrapper APIs in DBus::Object, DBus::ObjectTree or DBus::Service and
 *  integrate them with your mainloop.
 */
static VALUE
cDBusConnection_dispatch(VALUE self)
{
  return INT2FIX(dbus_connection_dispatch(CONN_GET(self)));
}

Blocks until the outgoing message queue is empty

[Source]

/*
 *  call-seq:
 *      flush => nil
 *
 *  Blocks until the outgoing message queue is empty
 */
static VALUE
cDBusConnection_flush(VALUE self)
{
  dbus_connection_flush(CONN_GET(self));
  return Qnil;
}

Returns the current status that would have been returned by DBusConnection#dispatch, without performing any message dispatching.

[Source]

/*
 *  call-seq:
 *      get_dispatch_status => status
 *
 *  Returns the current status that would have been returned by
 *  DBusConnection#dispatch, without performing any message dispatching.
 */
static VALUE
cDBusConnection_get_dispatch_status(VALUE self)
{
  return INT2FIX(dbus_connection_get_dispatch_status(CONN_GET(self)));
}

Returns true if this connection was authenticated

[Source]

/*
 *  call-seq:
 *      get_is_authenticated => true | false
 *
 *  Returns +true+ if this connection was authenticated
 */
static VALUE
cDBusConnection_get_is_authenticated(VALUE self)
{
  if (dbus_connection_get_is_authenticated(CONN_GET(self)))
    return Qtrue;
  return Qfalse;
}

Returns true if this connection is connected to the bus

[Source]

/*
 *  call-seq:
 *      get_is_connected => true | false
 *
 *  Returns +true+ if this connection is connected to the bus
 */
static VALUE
cDBusConnection_get_is_connected(VALUE self)
{
  if (dbus_connection_get_is_connected(CONN_GET(self)))
    return Qtrue;
  return Qfalse;
}

Returns the maximum message size in bytes that this connection may receive

[Source]

/*
 *  call-seq:
 *      get_max_message_size => size
 *
 *  Returns the maximum message size in bytes that this connection may
 *  receive
 */
static VALUE
cDBusConnection_get_max_message_size(VALUE self)
{
  return LONG2NUM(dbus_connection_get_max_message_size(CONN_GET(self)));
}

Returns the maximum number of bytes for all messages received on this connection, see DBusConnection#set_max_received_size for more details.

[Source]

/*
 *  call-seq:
 *      get_max_received_size => size
 *
 *  Returns the maximum number of bytes for all messages received on this
 *  connection, see DBusConnection#set_max_received_size for more details. 
 */
static VALUE
cDBusConnection_get_max_received_size(VALUE self)
{
  return LONG2NUM(dbus_connection_get_max_received_size(CONN_GET(self)));
}

Returns the approximate size in bytes of all messages in the outgoing message queue.

[Source]

/*
 *  call-seq:
 *      get_outgoing_size => size
 *
 *  Returns the approximate size in bytes of all messages in the outgoing
 *  message queue.
 */
static VALUE
cDBusConnection_get_outgoing_size(VALUE self)
{
  return LONG2NUM(dbus_connection_get_outgoing_size(CONN_GET(self)));
}
has_messages_to_send()

Returns a list of registered object path and fallback handlers for the given parent path.

[Source]

/*
 *  call-seq:
 *      list_registered(parent_path) => array
 *
 *  Returns a list of registered object path and fallback handlers for
 *  the given parent path.
 */
static VALUE
cDBusConnection_list_registered(VALUE self, VALUE parent_path)
{
  char **entries;
  VALUE ret;

  ret = rb_ary_new();
  entries = NULL;
  if (dbus_connection_list_registered(CONN_GET(self),
      StringValuePtr(parent_path), &entries) && entries != NULL)
  {
    int i = 0;
    while (entries[i] != NULL)
      rb_ary_push(ret, rb_str_new2(entries[i++]));
    dbus_free_string_array(entries);
  }
  return ret;
}

Pops the first message from the incoming message queue, removing it from the queue.

It is not recommended that you use this method, use the standard dispatching mechanisms instead.

[Source]

/*
 *  call-seq:
 *      pop_message => message
 *
 *  Pops the first message from the incoming message queue, removing it
 *  from the queue.
 *
 *  It is not recommended that you use this method, use the standard
 *  dispatching mechanisms instead.
 */
static VALUE
cDBusConnection_pop_message(VALUE self)
{
  DBusMessage *message;

  message = NULL;
  message = dbus_connection_pop_message(CONN_GET(self));
  if (message == NULL)
    return Qnil;
  return MSG_NEW(message);
}

Registers a fallback handler for a section of the object hierarchy.

The unregister_proc block will be called when the object path is being unregistered with a connection argument.

The message_proc block will be called for messages at or below the given object path, with the arguments +connection, message+.

Any exceptions thrown by your blocks will be silently ignored to ensure

  D-BUS integrity, so keep the handler blocks simple

[Source]

/*
 *  call-seq:
 *      register_fallback(path, unregister_proc, message_proc)
 *
 *  Registers a fallback handler for a section of the object hierarchy.
 *
 *  The +unregister_proc+ block will be called when the object path is being
 *  unregistered with a +connection+ argument.
 *
 *  The +message_proc+ block will be called for messages at or below the
 *  given object path, with the arguments +connection, message+.
 *
 *  = Any exceptions thrown by your blocks will be silently ignored to ensure
 *    D-BUS integrity, so keep the handler blocks simple
 */
static VALUE
cDBusConnection_register_fallback(VALUE self, VALUE path,
                                  VALUE unregister_cb, VALUE message_cb)
{
  DBusObjectPathVTable vtable;
  VALUE *user_data;

  if (NIL_P(unregister_cb) || NIL_P(message_cb))
    rb_raise(eDBusError, "Both unregister and message callbacks have to be supplied");

  vtable.unregister_function = _on_object_path_unregister;
  vtable.message_function = _on_object_path_message;

  user_data = ALLOC_N(VALUE, 2);
  user_data[0] = unregister_cb;
  user_data[1] = message_cb;

  if (dbus_connection_register_fallback(CONN_GET(self), StringValuePtr(path),
                                        &vtable, (void *)user_data))
  {
    rdbus_register_connection_callback(self, unregister_cb);
    rdbus_register_connection_callback(self, message_cb);
    return Qtrue;
  }

  ruby_xfree(user_data);
  return Qfalse;
}

Registers a handler for the given path in the object hierarchy.

The unregister_proc block will be called when the object path is being unregistered with a connection argument.

The message_proc block will be called for messages sent to the exact path specified, with the arguments +connection, message+.

Any exceptions thrown by your blocks will be silently ignored to ensure

  D-BUS integrity, so keep the handler blocks simple

[Source]

/*
 *  call-seq:
 *      register_object_path(path, unregister_proc, message_proc)
 *
 *  Registers a handler for the given path in the object hierarchy.
 *
 *  The +unregister_proc+ block will be called when the object path is being
 *  unregistered with a +connection+ argument.
 *  
 *  The +message_proc+ block will be called for messages sent to the exact
 *  path specified, with the arguments +connection, message+.
 *
 *  = Any exceptions thrown by your blocks will be silently ignored to ensure
 *    D-BUS integrity, so keep the handler blocks simple
 */
static VALUE
cDBusConnection_register_object_path(VALUE self, VALUE path,
                                     VALUE unregister_cb, VALUE message_cb)
{
  DBusObjectPathVTable vtable;
  VALUE *user_data;

  if (NIL_P(unregister_cb) || NIL_P(message_cb))
    rb_raise(eDBusError, "Both unregister and message callbacks have to be supplied");

  vtable.unregister_function = _on_object_path_unregister;
  vtable.message_function = _on_object_path_message;

  user_data = ALLOC_N(VALUE, 2);
  user_data[0] = unregister_cb;
  user_data[1] = message_cb;

  if (dbus_connection_register_object_path(CONN_GET(self), StringValuePtr(path),
                                           &vtable, (void *)user_data))
  {
    rdbus_register_connection_callback(self, unregister_cb);
    rdbus_register_connection_callback(self, message_cb);
    return Qtrue;
  }

  ruby_xfree(user_data);
  return Qfalse;
}

Returns a previously borrowed message to the queue

It is not recommended that you use this method, use the standard dispatching mechanisms instead.

[Source]

/*
 *  call-seq:
 *      return_message(message) => nil
 *
 *  Returns a previously borrowed message to the queue
 *
 *  It is not recommended that you use this method, use the standard
 *  dispatching mechanisms instead.
 */
static VALUE
cDBusConnection_return_message(VALUE self, VALUE message)
{
  dbus_connection_return_message(
    CONN_GET(self),
    MSG_GET(message)
  );
  return Qnil;
}

Enqueues the given message for sending on the outgoing queue. Sending happens asynchronously unless you force the issue by calling DBusConnection#flush.

Returns false if the message could not be enqueued due to lack of memory, true otherwise.

[Source]

/*
 *  call-seq:
 *      send(message) => true | false
 *
 *  Enqueues the given message for sending on the outgoing queue. Sending
 *  happens asynchronously unless you force the issue by calling DBusConnection#flush.
 *
 *  Returns +false+ if the message could not be enqueued due to lack of
 *  memory, +true+ otherwise.
 */
static VALUE
cDBusConnection_send(VALUE self, VALUE message)
{
  if (dbus_connection_send(CONN_GET(self), MSG_GET(message), NULL))
    return Qtrue;
  return Qfalse;
}

Enqueues the given message for sending on the outgoing queue. The timeout specified can also be -1, in which case a sane default value is used.

If successfully queued, a [true, DBusPendingCall] tuple is returned. Otherwise, a [false, nil] tuple is returned.

This method returns immediately.

[Source]

/*
 *  call-seq:
 *      send_with_reply(message, timeout_milliseconds) => [true|false, DBusPendingCall|nil]
 *
 *  Enqueues the given message for sending on the outgoing queue. The timeout
 *  specified can also be <tt>-1</tt>, in which case a sane default value is
 *  used.
 *
 *  If successfully queued, a <tt>[true, DBusPendingCall]</tt> tuple is returned.
 *  Otherwise, a <tt>[false, nil]</tt> tuple is returned.
 *
 *  This method returns immediately.
 */
static VALUE
cDBusConnection_send_with_reply(VALUE self, VALUE msg, VALUE timeout)
{
  VALUE ary;
  VALUE ret;
  DBusPendingCall *call;

  ary = Qnil;
  ret = Qfalse;
  call = NULL;
  if (dbus_connection_send_with_reply(CONN_GET(self), MSG_GET(msg), &call,
                                      NUM2INT(timeout)))
    ret = Qtrue;
  ary = rb_ary_new2(2);
  rb_ary_push(ary, ret);
  if (call != NULL) {
    rb_ary_push(ary, CALL_NEW(call));
  } else {
    rb_ary_push(ary, Qnil);
  }
  return ary;
}

Enqueues the given message for sending on the outgoing queue, and blocks for the given timeout until a reply is received, or the timeout expires, whichever comes first.

[Source]

/*
 *  call-seq:
 *      send_with_reply_and_block(message, timeout_milliseconds) => message
 *
 *  Enqueues the given message for sending on the outgoing queue, and blocks
 *  for the given timeout until a reply is received, or the timeout expires,
 *  whichever comes first.
 */
static VALUE
cDBusConnection_send_with_reply_and_block(VALUE self, VALUE msg, VALUE timeout)
{
  DBusMessage *return_msg;

  return_msg = NULL;
  RDBUS_TRY(
    return_msg = dbus_connection_send_with_reply_and_block(
      CONN_GET(self), MSG_GET(msg), NUM2INT(timeout), &error)
  )
  if (return_msg == NULL)
    return Qnil;
  return MSG_NEW(return_msg);
}

Sets the maximum message size in bytes that this connection may receive

[Source]

/*
 *  call-seq:
 *      set_max_message_size(value) => nil
 *
 *  Sets the maximum message size in bytes that this connection may
 *  receive
 */
static VALUE
cDBusConnection_set_max_message_size(VALUE self, VALUE size)
{
  dbus_connection_set_max_message_size(CONN_GET(self), NUM2LONG(size));
  return Qnil;
}

Sets the maximum number of bytes for all messages received on this connection. Messages count toward the maximum until they are garbage collected. When the maximum is reached, the connection will not read more data until some messages are garbage collected.

[Source]

/*
 *  call-seq:
 *      set_max_received_size(size) => nil
 *
 *  Sets the maximum number of bytes for all messages received on this
 *  connection. Messages count toward the maximum until they are garbage
 *  collected. When the maximum is reached, the connection will not read
 *  more data until some messages are garbage collected.
 */
static VALUE
cDBusConnection_set_max_received_size(VALUE self, VALUE size)
{
  dbus_connection_set_max_received_size(CONN_GET(self), NUM2LONG(size));
  return Qnil;
}

Sets up the watch and timeout functionality of the connection to integrate with the GLIB main loop.

[Source]

/*
 *  call-seq:
 *      setup_with_g_main => nil
 *
 *  Sets up the watch and timeout functionality of the connection to
 *  integrate with the GLIB main loop.
 */
static VALUE
cDBusConnection_setup_with_g_main(VALUE self)
{
  dbus_connection_setup_with_g_main(CONN_GET(self), NULL);
  return Qnil;
}

Steals a previously borrowed message (in other words, take ownership of it and remove it from the queue).

It is not recommended that you use this method, use the standard dispatching mechanisms instead.

[Source]

/*
 *  call-seq:
 *      steal_borrowed_message(message) => nil
 *
 *  Steals a previously borrowed message (in other words, take ownership
 *  of it and remove it from the queue).
 *
 *  It is not recommended that you use this method, use the standard
 *  dispatching mechanisms instead.
 */
static VALUE
cDBusConnection_steal_borrowed_message(VALUE self, VALUE message)
{
  dbus_connection_steal_borrowed_message(
    CONN_GET(self),
    MSG_GET(message)
  );
  return Qnil;
}

[Validate]