Class: DBus::Binding::DBusMessage

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

Overview

Represents a message sent over or received from another application over the bus.

A message has a type (DBusMessage#get_type) field indicating the nature of the message, and this can be used to decide which additional fields will contain useful data.

In addition, a message can have application-specific values added to it, these are called values or arguments. The order and type of the appended values define the message type signature (see DBusMessage#get_signature).

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.new(type) ⇒ self

Creates a new DBusMessage of the specified type, which may be one of the DBus MESSAGE_TYPE constants.

Returns:

  • (self) 


77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
 
# File 'ext/ruby-dbus-message.c', line 77

static VALUE
cDBusMessage_new(VALUE klass, VALUE type)
{
  DBusMessage *message;
  int message_type;
    
  message_type = NUM2INT(type);
  switch (message_type) {
    case DBUS_MESSAGE_TYPE_INVALID:
    case DBUS_MESSAGE_TYPE_METHOD_CALL:
    case DBUS_MESSAGE_TYPE_METHOD_RETURN:
    case DBUS_MESSAGE_TYPE_ERROR:
    case DBUS_MESSAGE_TYPE_SIGNAL:
      /* fall-through */
      break;
    default:
      rb_raise(eDBusError, "unsupported DBusMessageType %d", message_type);
  }
  message = NULL;
  message = dbus_message_new(message_type);
  RDBUS_RAISE_IF(message == NULL, "failed to create DBusMessage");
  return MSG_NEW_TAKE_OWNERSHIP(message);
}

.new_error(request_message, error_name, error_message) ⇒ Object

Creates a new DBusMessage of type MESSAGE_TYPE_ERROR.

Messages of this type are sent when a request fails for some reason. The error name has to be in a valid D-BUS error name format, meaning it has to contain at least one period.



190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
 
# File 'ext/ruby-dbus-message.c', line 190

static VALUE
cDBusMessage_new_error(VALUE klass, VALUE reply_to, VALUE error_name,
                        VALUE error_message)
{
  DBusMessage *message;
  
  message = NULL;
  message = dbus_message_new_error(
    MSG_GET(reply_to), 
    StringValuePtr(error_name),
    StringValuePtr(error_message)
  );
  RDBUS_RAISE_IF(!message, "failed to create DBusMessage");
  return MSG_NEW_TAKE_OWNERSHIP(message);
}

.new_method_call(service, path, interface, method_name) ⇒ self

Creates a new DBusMessage representing a method call request on a remote object.

  • service must contain the service to send the message to

  • path must contain object path the message should be sent to

  • interface must indicate the interface the method will be invoked on

  • method_name must contain the name of a method defined in the given interface

Returns:

  • (self) 


115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
 
# File 'ext/ruby-dbus-message.c', line 115

static VALUE
cDBusMessage_new_method_call(VALUE klass, VALUE service, VALUE path,
                              VALUE interface, VALUE method)
{
  DBusMessage *message;
  
  message = NULL;
  message = dbus_message_new_method_call(
    StringValuePtr(service),
    StringValuePtr(path),
    StringValuePtr(interface),
    StringValuePtr(method)
  );
  RDBUS_RAISE_IF(message == NULL, "failed to create DBusMessage");
  return MSG_NEW_TAKE_OWNERSHIP(message);
}

.new_method_return(invocation_message) ⇒ self

Creates a new DBusMessage representing a reply to a method call.

The original method invocation request message must be provided in invocation_message.

Returns:

  • (self) 


141
142
143
144
145
146
147
148
149
150
 
# File 'ext/ruby-dbus-message.c', line 141

static VALUE
cDBusMessage_new_method_return(VALUE klass, VALUE method_call_msg)
{
  DBusMessage *message;

  message = NULL;
  message = dbus_message_new_method_return(MSG_GET(method_call_msg));
  RDBUS_RAISE_IF(!message, "failed to create DBusMessage");
  return MSG_NEW_TAKE_OWNERSHIP(message);
}

.new_signal(path, interface, signal_name) ⇒ self

Creates a new DBusMessage representing a signal emission.

The given path must be the path to the object emitting the signal, interface the interface the signal is being emitted from, and signal_name the name of the signal.

The signal name can subsequently be retrieved from the member field of the message.

Returns:

  • (self) 


165
166
167
168
169
170
171
172
173
174
175
176
177
178
 
# File 'ext/ruby-dbus-message.c', line 165

static VALUE
cDBusMessage_new_signal(VALUE klass, VALUE path, VALUE interface, VALUE name)
{
  DBusMessage *message;
  
  message = NULL;
  message = dbus_message_new_signal(
    StringValuePtr(path),
    StringValuePtr(interface),
    StringValuePtr(name)
  );
  RDBUS_RAISE_IF(!message, "failed to create DBusMessage");
  return MSG_NEW_TAKE_OWNERSHIP(message);
}

Instance Method Details

#<<(value) ⇒ Object

Appends the given value to the message. If you want to append more than one value, use DBusMessage#append instead, it will be more efficient.



76
77
78
79
80
 
# File 'lib/dbus/binding.rb', line 76

def <<(value)
  iter = get_append_iter
  iter.append(value)
  nil
end

#[](offset) ⇒ Object

Returns the message argument value at the given offset



63
64
65
 
# File 'lib/dbus/binding.rb', line 63

def [](offset)
  entries[offset]
end

#append(ary) ⇒ Object

Appends each item in the given Array to the message



68
69
70
71
72
 
# File 'lib/dbus/binding.rb', line 68

def append(ary)
  iter = get_append_iter
  ary.each{|value| iter.append(value)}
  nil
end

#each {|value| ... } ⇒ Object

Yields each message argument value that was appended to the message to the given block, in sequence

Yields:

  • (value)

Raises:



45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
 
# File 'lib/dbus/binding.rb', line 45

def each
  raise DBusError, "block expected" unless block_given?
  iter = get_iter
  begin
    value = iter.value
  rescue
    return nil
  end
  yield value
  have_value = iter.next
  while have_value
    yield iter.value
    have_value = iter.next
  end
  nil
end

#get_append_iter ⇒ Object

Returns a DBusMessageIter iterator instance for appending values to this message. The position of the iterator is at the end of any existing values.



634
635
636
637
638
 
# File 'ext/ruby-dbus-message.c', line 634

static VALUE
cDBusMessage_get_append_iter(VALUE self)
{
  return ITER_NEW(MSG_GET(self), TRUE);
}

#get_auto_activation ⇒ Object

Returns true if the message will cause the addressed service to be auto-activated.



600
601
602
603
604
605
606
 
# File 'ext/ruby-dbus-message.c', line 600

static VALUE
cDBusMessage_get_auto_activation(VALUE self)
{
  if (!dbus_message_get_auto_activation(MSG_GET(self)))
    return Qfalse;
  return Qtrue;
}

#get_destination ⇒ Object

Gets the destination service of this message.



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

static VALUE
cDBusMessage_get_destination(VALUE self)
{
  MESSAGE_STR_GETTER_BODY(destination);
}

#get_error_name ⇒ Object

Gets the error name (for an error message).



362
363
364
365
366
 
# File 'ext/ruby-dbus-message.c', line 362

static VALUE
cDBusMessage_get_error_name(VALUE self)
{
  MESSAGE_STR_GETTER_BODY(error_name);
}

#get_path ⇒ Object

Gets the interface this message is being sent to.



337
338
339
340
341
 
# File 'ext/ruby-dbus-message.c', line 337

static VALUE
cDBusMessage_get_interface(VALUE self)
{
  MESSAGE_STR_GETTER_BODY(interface);
}

#get_iter ⇒ Object

Returns a DBusMessageIter iterator instance for this message. The iterator can be used to iterate over the values (arguments) appended to the message.

To append values to the message, use DBusMessage#get_append_iter instead, as its position will already be at the end, and by using it you will avoid D-BUS error messages.



620
621
622
623
624
 
# File 'ext/ruby-dbus-message.c', line 620

static VALUE
cDBusMessage_get_iter(VALUE self)
{
  return ITER_NEW(MSG_GET(self), FALSE);
}

#get_member ⇒ Object

Gets the interface member being invoked (for a method call), or emitted (for a signal).



350
351
352
353
354
 
# File 'ext/ruby-dbus-message.c', line 350

static VALUE
cDBusMessage_get_member(VALUE self)
{
  MESSAGE_STR_GETTER_BODY(member);
}

#get_no_reply ⇒ Object

Returns true if the message sender is not expecting a reply message.



433
434
435
436
437
438
439
 
# File 'ext/ruby-dbus-message.c', line 433

static VALUE
cDBusMessage_get_no_reply(VALUE self)
{
  if (!dbus_message_get_no_reply(MSG_GET(self)))
    return Qfalse;
  return Qtrue;
}

#get_path ⇒ Object

Gets the object path this message is being sent to (for a method call), or being emitted from (for a signal).



325
326
327
328
329
 
# File 'ext/ruby-dbus-message.c', line 325

static VALUE
cDBusMessage_get_path(VALUE self)
{
  MESSAGE_STR_GETTER_BODY(path);
}

#get_path_decomposed ⇒ Object

Returns an array containing the path segments of the message path



83
84
85
 
# File 'lib/dbus/binding.rb', line 83

def get_path_decomposed
  get_path.split("/")
end

#get_reply_serial ⇒ Object

Returns the serial number (see DbusMessage#get_serial) of the message that this message is a reply to.



551
552
553
554
555
 
# File 'ext/ruby-dbus-message.c', line 551

static VALUE
cDBusMessage_get_reply_serial(VALUE self)
{
  return INT2NUM(dbus_message_get_reply_serial(MSG_GET(self)));
}

#get_sender ⇒ Object

Gets the sending service of this message.



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

static VALUE
cDBusMessage_get_sender(VALUE self)
{
  MESSAGE_STR_GETTER_BODY(sender);
}

#get_serial ⇒ Object

Returns the client serial number of the message. This can’t be set.



538
539
540
541
542
 
# File 'ext/ruby-dbus-message.c', line 538

static VALUE
cDBusMessage_get_serial(VALUE self)
{
  return INT2NUM(dbus_message_get_serial(MSG_GET(self)));
}

#get_signature ⇒ Object

Gets the type signature.

A type signature is the type of the message argument values in the message payload. The signature is a string consisting of TYPE_xxx type codes:



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

static VALUE
cDBusMessage_get_signature(VALUE self)
{
  MESSAGE_STR_GETTER_BODY(signature);
}

#get_type ⇒ Object

Returns an integer representing the message type. Its value will be one of the MESSAGE_TYPE constants.



213
214
215
216
217
 
# File 'ext/ruby-dbus-message.c', line 213

static VALUE
cDBusMessage_get_type(VALUE self)
{
  return INT2FIX(dbus_message_get_type(MSG_GET(self)));
}

#has_destination(service) ⇒ Object

Returns true if the message has a destination service with the given service name.



495
496
497
498
499
500
501
 
# File 'ext/ruby-dbus-message.c', line 495

static VALUE
cDBusMessage_has_destination(VALUE self, VALUE service)
{
  if (!dbus_message_has_destination(MSG_GET(self), StringValuePtr(service)))
    return Qfalse;
  return Qtrue;
}

#has_sender(service) ⇒ Object

Returns true if the message has the given service name as its sender.



509
510
511
512
513
514
515
 
# File 'ext/ruby-dbus-message.c', line 509

static VALUE
cDBusMessage_has_sender(VALUE self, VALUE service)
{
  if (!dbus_message_has_sender(MSG_GET(self), StringValuePtr(service)))
    return Qfalse;
  return Qtrue;
}

#has_signature(signature) ⇒ Object

Returns true if the message has the given type signature. See DBusMessage#get_signature for more details on type signatures.



524
525
526
527
528
529
530
 
# File 'ext/ruby-dbus-message.c', line 524

static VALUE
cDBusMessage_has_signature(VALUE self, VALUE signature)
{
  if (!dbus_message_has_signature(MSG_GET(self), StringValuePtr(signature)))
    return Qfalse;
  return Qtrue;
}

#is_error(error_name) ⇒ Object

Returns true if the message is an error message with the given error name field.



480
481
482
483
484
485
486
 
# File 'ext/ruby-dbus-message.c', line 480

static VALUE
cDBusMessage_is_error(VALUE self, VALUE error)
{
  if (!dbus_message_is_error(MSG_GET(self), StringValuePtr(error)))
    return Qfalse;
  return Qtrue;
}

#is_method_call(interface, method_name) ⇒ Object

Returns true if the message is a method call message with the given method name and interface fields.



448
449
450
451
452
453
454
455
 
# File 'ext/ruby-dbus-message.c', line 448

static VALUE
cDBusMessage_is_method_call(VALUE self, VALUE interface, VALUE method)
{
  if (!dbus_message_is_method_call(MSG_GET(self), StringValuePtr(interface),
                                   StringValuePtr(method)))
    return Qfalse;
  return Qtrue;
}

#is_signal(interface, signal_name) ⇒ Object

Returns true if the message is a signal message with the given interface and signal name fields.



464
465
466
467
468
469
470
471
 
# File 'ext/ruby-dbus-message.c', line 464

static VALUE
cDBusMessage_is_signal(VALUE self, VALUE interface, VALUE signal_name)
{
  if (!dbus_message_is_signal(MSG_GET(self), StringValuePtr(interface),
                              StringValuePtr(signal_name)))
    return Qfalse;
  return Qtrue;
}

#set_auto_activation(true|false) ⇒ nil

Indicates that the addressed service will be auto-activated before the message is delivered. If the service fails to activate, an activation error reply message will be received.

Returns:

  • (nil) 


580
581
582
583
584
585
586
587
588
589
590
591
 
# File 'ext/ruby-dbus-message.c', line 580

static VALUE
cDBusMessage_set_auto_activation(VALUE self, VALUE value)
{
  dbus_bool_t val;

  if (TYPE(value) == T_FALSE || TYPE(value) == T_NIL)
    val = FALSE;
  else
    val = TRUE;
  dbus_message_set_auto_activation(MSG_GET(self), val);
  return Qnil;
}

#set_destination(service) ⇒ Object

Sets the message’s destination service.

Returns false if not enough memory.



292
293
294
295
296
 
# File 'ext/ruby-dbus-message.c', line 292

static VALUE
cDBusMessage_set_destination(VALUE self, VALUE value)
{
  MESSAGE_STR_SETTER_BODY(destination);
}

#set_error_name(name) ⇒ Object

Sets the name of the error (for an error message).

Returns false if not enough memory.



278
279
280
281
282
 
# File 'ext/ruby-dbus-message.c', line 278

static VALUE
cDBusMessage_set_error_name(VALUE self, VALUE value)
{
  MESSAGE_STR_SETTER_BODY(error_name);
}

#set_interface(interface) ⇒ Object

Sets the interface this message is being sent to (for a method call), or the interface a signal is being emitted from (for a signal).

Returns false if not enough memory.



249
250
251
252
253
 
# File 'ext/ruby-dbus-message.c', line 249

static VALUE
cDBusMessage_set_interface(VALUE self, VALUE value)
{
  MESSAGE_STR_SETTER_BODY(interface);
}

#set_member(member) ⇒ Object

Sets the interface member being invoked (for a method call), or emitted (for a signal).

Returns false if not enough memory.



264
265
266
267
268
 
# File 'ext/ruby-dbus-message.c', line 264

static VALUE
cDBusMessage_set_member(VALUE self, VALUE value)
{
  MESSAGE_STR_SETTER_BODY(member);
}

#set_no_reply(true|false) ⇒ nil

Indicates whether or not the message wants a reply. If set, there is no way to know whether a message arrived successfully at the destination.

Returns:

  • (nil) 


414
415
416
417
418
419
420
421
422
423
424
425
 
# File 'ext/ruby-dbus-message.c', line 414

static VALUE
cDBusMessage_set_no_reply(VALUE self, VALUE value)
{
  dbus_bool_t val;

  if (TYPE(value) == T_FALSE || TYPE(value) == T_NIL)
    val = FALSE;
  else
    val = TRUE;
  dbus_message_set_no_reply(MSG_GET(self), val);
  return Qnil;
}

#set_path(object_path) ⇒ Object

Sets the object path this message is being sent to (for a method call), or the path a signal is being emitted from (for a signal).

Returns false if not enough memory.



234
235
236
237
238
 
# File 'ext/ruby-dbus-message.c', line 234

static VALUE
cDBusMessage_set_path(VALUE self, VALUE value)
{
  MESSAGE_STR_SETTER_BODY(path);
}

#set_reply_serial(serial) ⇒ true

Sets the serial number (see DbusMessage#get_serial) of the message that this message is a reply to.

Returns:

  • (true) 


564
565
566
567
568
569
570
 
# File 'ext/ruby-dbus-message.c', line 564

static VALUE
cDBusMessage_set_reply_serial(VALUE self, VALUE serial)
{
  if (!dbus_message_set_reply_serial(MSG_GET(self), NUM2UINT(serial)))
    return Qfalse;
  return Qtrue;
}

#set_sender(service) ⇒ Object

Sets the service sending this message.

Returns false if not enough memory.



306
307
308
309
310
 
# File 'ext/ruby-dbus-message.c', line 306

static VALUE
cDBusMessage_set_sender(VALUE self, VALUE value)
{
  MESSAGE_STR_SETTER_BODY(sender);
}

#to_s ⇒ Object 



87
88
89
 
# File 'lib/dbus/binding.rb', line 87

def to_s
  "#<#{self.class.to_s} path=\"#{get_path}\" interface=\"#{get_interface}\" member=\"#{get_member}\" sender=\"#{get_sender}\">"
end