Class: DBus::Binding::DBusConnection

Inherits:
Object
  • Object
show all
Defined in:
ext/ruby-dbus-connection.c,
lib/dbus/binding.rb,
ext/ruby-dbus-connection.c

Overview

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.

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.new(address) ⇒ Object

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.



91
92
93
94
95
96
97
98
99
100
 
# File 'ext/ruby-dbus-connection.c', line 91

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);
}

.new(address) ⇒ Object

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.



91
92
93
94
95
96
97
98
99
100
 
# File 'ext/ruby-dbus-connection.c', line 91

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);
}

Instance Method Details

#add_filter(filter_proc) ⇒ Object

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.



656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
 
# File 'ext/ruby-dbus-connection.c', line 656

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;
}

#borrow_message ⇒ Object

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.



182
183
184
185
186
187
188
189
190
191
192
 
# File 'ext/ruby-dbus-connection.c', line 182

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);
}

#disconnect ⇒ nil

Disconnects this connection from the bus

Returns:

  • (nil) 


122
123
124
125
126
127
 
# File 'ext/ruby-dbus-connection.c', line 122

static VALUE
cDBusConnection_disconnect(VALUE self)
{
  dbus_connection_disconnect(CONN_GET(self));
  return Qnil;
}

#dispatch ⇒ Object

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.



283
284
285
286
287
 
# File 'ext/ruby-dbus-connection.c', line 283

static VALUE
cDBusConnection_dispatch(VALUE self)
{
  return INT2FIX(dbus_connection_dispatch(CONN_GET(self)));
}

#flush ⇒ nil

Blocks until the outgoing message queue is empty

Returns:

  • (nil) 


163
164
165
166
167
168
 
# File 'ext/ruby-dbus-connection.c', line 163

static VALUE
cDBusConnection_flush(VALUE self)
{
  dbus_connection_flush(CONN_GET(self));
  return Qnil;
}

#get_data(slot, data) ⇒ Object

:nodoc:



36
37
 
# File 'lib/dbus/binding.rb', line 36

def get_data(slot, data) # :nodoc:
end

#get_dispatch_status ⇒ Object

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



262
263
264
265
266
 
# File 'ext/ruby-dbus-connection.c', line 262

static VALUE
cDBusConnection_get_dispatch_status(VALUE self)
{
  return INT2FIX(dbus_connection_get_dispatch_status(CONN_GET(self)));
}

#get_is_authenticated ⇒ Object

Returns true if this connection was authenticated



149
150
151
152
153
154
155
 
# File 'ext/ruby-dbus-connection.c', line 149

static VALUE
cDBusConnection_get_is_authenticated(VALUE self)
{
  if (dbus_connection_get_is_authenticated(CONN_GET(self)))
    return Qtrue;
  return Qfalse;
}

#get_is_connected ⇒ Object

Returns true if this connection is connected to the bus



135
136
137
138
139
140
141
 
# File 'ext/ruby-dbus-connection.c', line 135

static VALUE
cDBusConnection_get_is_connected(VALUE self)
{
  if (dbus_connection_get_is_connected(CONN_GET(self)))
    return Qtrue;
  return Qfalse;
}

#get_max_message_size ⇒ Object

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



373
374
375
376
377
 
# File 'ext/ruby-dbus-connection.c', line 373

static VALUE
cDBusConnection_get_max_message_size(VALUE self)
{
  return LONG2NUM(dbus_connection_get_max_message_size(CONN_GET(self)));
}

#get_max_received_size ⇒ Object

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



400
401
402
403
404
 
# File 'ext/ruby-dbus-connection.c', line 400

static VALUE
cDBusConnection_get_max_received_size(VALUE self)
{
  return LONG2NUM(dbus_connection_get_max_received_size(CONN_GET(self)));
}

#get_outgoing_size ⇒ Object

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



430
431
432
433
434
 
# File 'ext/ruby-dbus-connection.c', line 430

static VALUE
cDBusConnection_get_outgoing_size(VALUE self)
{
  return LONG2NUM(dbus_connection_get_outgoing_size(CONN_GET(self)));
}

#has_messages_to_send ⇒ Object 



714
715
716
717
718
719
720
 
# File 'ext/ruby-dbus-connection.c', line 714

static VALUE
cDBusConnection_has_messages_to_send(VALUE self)
{
  if (dbus_connection_has_messages_to_send(CONN_GET(self)))
    return Qtrue;
  return Qfalse;
}

#list_registered(parent_path) ⇒ Array

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

Returns:

  • (Array) 


685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
 
# File 'ext/ruby-dbus-connection.c', line 685

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;
}

#pop_message ⇒ Object

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.



243
244
245
246
247
248
249
250
251
252
253
 
# File 'ext/ruby-dbus-connection.c', line 243

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);
}

#register_fallback(path, unregister_proc, message_proc) ⇒ Object

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



567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
 
# File 'ext/ruby-dbus-connection.c', line 567

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;
}

#register_object_path(path, unregister_proc, message_proc) ⇒ Object

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



523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
 
# File 'ext/ruby-dbus-connection.c', line 523

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;
}

#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.

Returns:

  • (nil) 


203
204
205
206
207
208
209
210
211
 
# File 'ext/ruby-dbus-connection.c', line 203

static VALUE
cDBusConnection_return_message(VALUE self, VALUE message)
{
  dbus_connection_return_message(
    CONN_GET(self),
    MSG_GET(message)
  );
  return Qnil;
}

#send(message) ⇒ Object

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.



299
300
301
302
303
304
305
 
# File 'ext/ruby-dbus-connection.c', line 299

static VALUE
cDBusConnection_send(VALUE self, VALUE message)
{
  if (dbus_connection_send(CONN_GET(self), MSG_GET(message), NULL))
    return Qtrue;
  return Qfalse;
}

#send_with_reply(message, timeout_milliseconds) ⇒ Array, DBusPendingCall|nil

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.

Returns ].

Returns:



320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
 
# File 'ext/ruby-dbus-connection.c', line 320

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;
}

#send_with_reply_and_block(message, timeout_milliseconds) ⇒ Object

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.



351
352
353
354
355
356
357
358
359
360
361
362
363
364
 
# File 'ext/ruby-dbus-connection.c', line 351

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);
}

#set_data(slot, data) ⇒ Object

:nodoc:



34
35
 
# File 'lib/dbus/binding.rb', line 34

def set_data(slot, data) # :nodoc:
end

#set_max_message_size(value) ⇒ nil

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

Returns:

  • (nil) 


386
387
388
389
390
391
 
# File 'ext/ruby-dbus-connection.c', line 386

static VALUE
cDBusConnection_set_max_message_size(VALUE self, VALUE size)
{
  dbus_connection_set_max_message_size(CONN_GET(self), NUM2LONG(size));
  return Qnil;
}

#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.

Returns:

  • (nil) 


416
417
418
419
420
421
 
# File 'ext/ruby-dbus-connection.c', line 416

static VALUE
cDBusConnection_set_max_received_size(VALUE self, VALUE size)
{
  dbus_connection_set_max_received_size(CONN_GET(self), NUM2LONG(size));
  return Qnil;
}

#set_timeout_functions(add_func, remove_func, data) ⇒ Object

:nodoc:



30
31
 
# File 'lib/dbus/binding.rb', line 30

def set_timeout_functions(add_func, remove_func, data) # :nodoc:
end

#set_wakeup_main_function(add_func, remove_func, data) ⇒ Object

:nodoc:



32
33
 
# File 'lib/dbus/binding.rb', line 32

def set_wakeup_main_function(add_func, remove_func, data) # :nodoc:
end

#set_watch_functions(add_func, remove_func, data) ⇒ Object

– TODO ++



28
29
 
# File 'lib/dbus/binding.rb', line 28

def set_watch_functions(add_func, remove_func, data) # :nodoc:
end

#setup_with_g_main ⇒ nil

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

Returns:

  • (nil) 


109
110
111
112
113
114
 
# File 'ext/ruby-dbus-connection.c', line 109

static VALUE
cDBusConnection_setup_with_g_main(VALUE self)
{
  dbus_connection_setup_with_g_main(CONN_GET(self), NULL);
  return Qnil;
}

#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.

Returns:

  • (nil) 


223
224
225
226
227
228
229
230
231
 
# File 'ext/ruby-dbus-connection.c', line 223

static VALUE
cDBusConnection_steal_borrowed_message(VALUE self, VALUE message)
{
  dbus_connection_steal_borrowed_message(
    CONN_GET(self),
    MSG_GET(message)
  );
  return Qnil;
}