Class: DBus::Binding::DBusMessageIter

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

Overview

The DBusMessageIter class is an iterator abstraction for accessing the argument values of a DBusMessage.

This abstraction is quite low-level, and it is recommended that you use the Enumerable and Array-like methods on DBusMessage to access message argument values instead, as they perform the necessary integration with DBusMessageIter, and will ensure that the values you get have been converted to the correct Ruby types.

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.new ⇒ self

The new method of this class is not available for invocation.

Returns:

  • (self) 


21
22
23
24
25
26
 
# File 'ext/ruby-dbus-common.c', line 21

VALUE
rdbus_private_method(VALUE klass)
{
  rb_raise(rb_eNoMethodError, "Method is unavailable to non-native methods");
  return Qnil;
}

Instance Method Details

#append(value) ⇒ Object

Appends the given value to the message this iterator is associated with. Ruby types are automatically converted to the closest matching D-BUS message argument type.



96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
 
# File 'lib/dbus/binding.rb', line 96

def append(value)
  case
  when value.nil?
    append_nil
  when value.is_a?(ObjectPath)
    append_object_path(value)
  when value.is_a?(String)
    append_string(value)
  when value.is_a?(Fixnum)
    append_int32(value)
  when value.is_a?(Bignum)
    append_int64(value)
  when value.is_a?(Float)
    append_double(value)
  when value.is_a?(TrueClass)
    append_boolean(true)
  when value.is_a?(FalseClass)
    append_boolean(false)
  when value.is_a?(Hash)
    di = append_dict
    value.each{|k,v| di.append_dict_key(k); di.append(v); }
    true
  when value.is_a?(Array)
    raise ArgumentError, "empty arrays are not supported" if value.empty?
    dtype = ruby_to_dbus_type(value[0])
    ai = append_array(dtype)
    value.each{|v| ai.append(v) if ruby_to_dbus_type(v) == dtype}
    true
  else
    raise ArgumentError, "unsupported argument type #{value.class}"
  end
end

#append_array(typecode) ⇒ Object

Appends an array of the specified type to this message, and returns an iterator for adding values to the new array.

See DBusMessageIter#append for an example of usage.

Returns nil if no memory.



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

static VALUE
cDBusMessageIter_append_array(VALUE self, VALUE type)
{
  RubyDBusMessageIter *parent = NULL;
  RubyDBusMessageIter *child = NULL;

  parent = ITER_WRAPPER_GET(self);
  child = _alloc_message_iter(parent->message, NULL);
  if (dbus_message_iter_append_array(parent->real_iter, child->real_iter, NUM2INT(type)))
    return Data_Wrap_Struct(cDBusMessageIter, NULL, rdbus_free_message_iter, child);
  rdbus_free_message_iter(child);
  return Qnil;
}

#append_boolean(true|false|nil) ⇒ Object

Appends a boolean argument value to this message. nil is regarded as a false value if passed through.

Returns false if no memory.



380
381
382
383
384
385
386
387
388
389
390
391
 
# File 'ext/ruby-dbus-message-iter.c', line 380

static VALUE
cDBusMessageIter_append_boolean(VALUE self, VALUE value)
{
  dbus_bool_t val;
  if (TYPE(value) == T_FALSE || TYPE(value) == T_NIL)
    val = FALSE;
  else
    val = TRUE;
  if (dbus_message_iter_append_boolean(ITER_GET(self), val))
    return Qtrue;
  return Qfalse;
}

#append_byte(byte) ⇒ Object

Appends a byte value to this message. As Ruby has no byte type, providing an integer representing the byte value suffices. Note that the supplied value is clamped to 8 bits.

Returns false if no memory.



403
404
405
406
407
408
409
410
411
 
# File 'ext/ruby-dbus-message-iter.c', line 403

static VALUE
cDBusMessageIter_append_byte(VALUE self, VALUE value)
{
  unsigned char val;
  val = NUM2UINT(value) & 0xff;
  if (dbus_message_iter_append_byte(ITER_GET(self), val))
    return Qtrue;
  return Qfalse;
}

#append_dict ⇒ Object

Appends a dictionary to this message, and returns an iterator for adding values to the new dictionary. Use DBusMessageIter#append_dict_key in conjunction with another append method to add key=>value pairs to the dictionary.

See DBusMessageIter#append for an example of usage.

Returns nil if no memory.



607
608
609
610
611
612
613
614
615
616
617
618
619
 
# File 'ext/ruby-dbus-message-iter.c', line 607

static VALUE
cDBusMessageIter_append_dict(VALUE self)
{
  RubyDBusMessageIter *parent = NULL;
  RubyDBusMessageIter *child = NULL;

  parent = ITER_WRAPPER_GET(self);
  child = _alloc_message_iter(parent->message, NULL);
  if (dbus_message_iter_append_dict(parent->real_iter, child->real_iter))
    return Data_Wrap_Struct(cDBusMessageIter, NULL, rdbus_free_message_iter, child);
  rdbus_free_message_iter(child);
  return Qnil;
}

#append_dict_key(string) ⇒ Object

Appends a dictionary key value to this message. Use in conjunction with another append call for the value to populate a dictionary.

See DBusMessageIter#append for an example of usage.

Returns false if no memory.



561
562
563
564
565
566
567
 
# File 'ext/ruby-dbus-message-iter.c', line 561

static VALUE
cDBusMessageIter_append_dict_key(VALUE self, VALUE value)
{
  if (dbus_message_iter_append_dict_key(ITER_GET(self), StringValuePtr(value)))
    return Qtrue;
  return Qfalse;
}

#append_double(float) ⇒ Object

Appends a floating point value to this message. Note that your value will be truncated if it is larger than the associated D-BUS type.

Returns false if no memory.



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

static VALUE
cDBusMessageIter_append_double(VALUE self, VALUE value)
{
  double val;
  val = NUM2DBL(value);
  if (dbus_message_iter_append_double(ITER_GET(self), val))
    return Qtrue;
  return Qfalse;
}

#append_int32(integer) ⇒ Object

Appends a signed 32-bit integer value to this message. Note that your value will be truncated if it is larger than the associated D-BUS type.

Returns false if no memory.



423
424
425
426
427
428
429
430
431
 
# File 'ext/ruby-dbus-message-iter.c', line 423

static VALUE
cDBusMessageIter_append_int32(VALUE self, VALUE value)
{
  dbus_int32_t val;
  val = NUM2INT(value);
  if (dbus_message_iter_append_int32(ITER_GET(self), val))
    return Qtrue;
  return Qfalse;
}

#append_int64(integer) ⇒ Object

Appends a signed 64-bit integer value to this message. Note that your value will be truncated if it is larger than the associated D-BUS type.

Returns false if no memory.



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

static VALUE
cDBusMessageIter_append_int64(VALUE self, VALUE value)
{
  dbus_int64_t val;
  val = NUM2LL(value);
  if (dbus_message_iter_append_int64(ITER_GET(self), val))
    return Qtrue;
  return Qfalse;
}

#append_nil ⇒ Object

Appends a nil argument value to this message.

Returns false if no memory.



363
364
365
366
367
368
369
 
# File 'ext/ruby-dbus-message-iter.c', line 363

static VALUE
cDBusMessageIter_append_nil(VALUE self)
{
  if (dbus_message_iter_append_nil(ITER_GET(self)))
    return Qtrue;
  return Qfalse;
}

#append_object_path(string) ⇒ Object

Appends an object path value to this message.

Returns false if no memory.



541
542
543
544
545
546
547
 
# File 'ext/ruby-dbus-message-iter.c', line 541

static VALUE
cDBusMessageIter_append_object_path(VALUE self, VALUE value)
{
  if (dbus_message_iter_append_object_path(ITER_GET(self), StringValuePtr(value)))
    return Qtrue;
  return Qfalse;
}

#append_string(string) ⇒ Object

Appends a string value to this message.

Returns false if no memory.



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

static VALUE
cDBusMessageIter_append_string(VALUE self, VALUE value)
{
  if (dbus_message_iter_append_string(ITER_GET(self), StringValuePtr(value)))
    return Qtrue;
  return Qfalse;
}

#append_uint32(integer) ⇒ Object

Appends an unsigned 32-bit integer value to this message. Note that your value will be truncated if it is larger than the associated D-BUS type.

Returns false if no memory.



443
444
445
446
447
448
449
450
451
 
# File 'ext/ruby-dbus-message-iter.c', line 443

static VALUE
cDBusMessageIter_append_uint32(VALUE self, VALUE value)
{
  dbus_uint32_t val;
  val = NUM2UINT(value);
  if (dbus_message_iter_append_uint32(ITER_GET(self), val))
    return Qtrue;
  return Qfalse;
}

#append_uint64(integer) ⇒ Object

Appends an unsigned 64-bit integer value to this message. Note that your value will be truncated if it is larger than the associated D-BUS type.

Returns false if no memory.



485
486
487
488
489
490
491
492
493
 
# File 'ext/ruby-dbus-message-iter.c', line 485

static VALUE
cDBusMessageIter_append_uint64(VALUE self, VALUE value)
{
  dbus_uint64_t val;
  val = NUM2LL(value);
  if (dbus_message_iter_append_uint64(ITER_GET(self), val))
    return Qtrue;
  return Qfalse;
}

#array_iter ⇒ Object

Returns an array iterator for the array argument that this iterator currently points to.

See DBusMessageIter#get_array for an example of usage.



319
320
321
322
323
324
325
326
327
328
329
330
331
 
# File 'ext/ruby-dbus-message-iter.c', line 319

static VALUE
cDBusMessageIter_array_iter_new(VALUE self)
{
  RubyDBusMessageIter *self_iter = NULL;
  RubyDBusMessageIter *ary_iter = NULL;
  int array_type = DBUS_TYPE_INVALID;

  self_iter = ITER_WRAPPER_GET(self);
  _ensure_arg_type(self_iter->real_iter, DBUS_TYPE_ARRAY);
  ary_iter = _alloc_message_iter(self_iter->message, NULL);
  dbus_message_iter_init_array_iterator(self_iter->real_iter, ary_iter->real_iter, &array_type);
  return Data_Wrap_Struct(cDBusMessageIter, NULL, rdbus_free_message_iter, ary_iter);
}

#dict_iter ⇒ Object

Returns a dictionary iterator for the dictionary argument that this iterator currently points to.

See DBusMessageIter#get_dict for an example of usage.



342
343
344
345
346
347
348
349
350
351
352
353
 
# File 'ext/ruby-dbus-message-iter.c', line 342

static VALUE
cDBusMessageIter_dict_iter_new(VALUE self)
{
  RubyDBusMessageIter *self_iter = NULL;
  RubyDBusMessageIter *dict_iter = NULL;

  self_iter = ITER_WRAPPER_GET(self);
  _ensure_arg_type(self_iter->real_iter, DBUS_TYPE_DICT);
  dict_iter = _alloc_message_iter(self_iter->message, NULL);
  dbus_message_iter_init_dict_iterator(self_iter->real_iter, dict_iter->real_iter);
  return Data_Wrap_Struct(cDBusMessageIter, NULL, rdbus_free_message_iter, dict_iter);
}

#get_arg_type ⇒ Object

Returns the argument type of the argument that the iterator currently points at. This is one of the TYPE_xxx codes.



144
145
146
147
148
 
# File 'ext/ruby-dbus-message-iter.c', line 144

static VALUE
cDBusMessageIter_get_arg_type(VALUE self)
{
  return INT2FIX(dbus_message_iter_get_arg_type(ITER_GET(self)));
}

#get_array ⇒ Object

Returns the message argument value at the current position of the iterator as an Array. For this to work, the argument value has to be of the D-BUS type TYPE_ARRAY.



183
184
185
186
187
188
189
190
191
192
 
# File 'lib/dbus/binding.rb', line 183

def get_array
  iter = array_iter
  ret = []
  loop do
    ret << iter.value
    break if !iter.has_next
    iter.next
  end
  ret
end

#get_array_type ⇒ Object

Returns the element type of the array argument that the iterator currently points at.



157
158
159
160
161
 
# File 'ext/ruby-dbus-message-iter.c', line 157

static VALUE
cDBusMessageIter_get_array_type(VALUE self)
{
  return INT2FIX(dbus_message_iter_get_array_type(ITER_GET(self)));
}

#get_boolean ⇒ Object

Returns the boolean value of the argument that the iterator currently points at.



185
186
187
188
189
190
191
192
 
# File 'ext/ruby-dbus-message-iter.c', line 185

static VALUE
cDBusMessageIter_get_boolean(VALUE self)
{
  _ensure_arg_type(ITER_GET(self), DBUS_TYPE_BOOLEAN);
  if (dbus_message_iter_get_boolean(ITER_GET(self)))
    return Qtrue;
  return Qfalse;
}

#get_byte ⇒ Object

Returns the byte value of the argument that the iterator currently points at. As Ruby does not have a byte type, the returned value is a Fixnum.



171
172
173
174
175
176
 
# File 'ext/ruby-dbus-message-iter.c', line 171

static VALUE
cDBusMessageIter_get_byte(VALUE self)
{
  _ensure_arg_type(ITER_GET(self), DBUS_TYPE_BYTE);
  return INT2FIX(dbus_message_iter_get_byte(ITER_GET(self)) & 0xff);
}

#get_dict ⇒ Object

Returns the message argument value at the current position of the iterator as a Hash. For this to work, the argument value has to be of the D-BUS type TYPE_DICT.



169
170
171
172
173
174
175
176
177
178
 
# File 'lib/dbus/binding.rb', line 169

def get_dict
  iter = dict_iter
  ret = {}
  loop do
    ret[iter.get_dict_key] = iter.value
    break if !iter.has_next
    iter.next
  end
  ret
end

#get_dict_key ⇒ String

Returns the dictionary key for a dictionary entry that the iteratory currently points to. This will only work on iterators returned by DBusMessageIter#dict_iter.

Returns:

  • (String) 


304
305
306
307
308
 
# File 'ext/ruby-dbus-message-iter.c', line 304

static VALUE
cDBusMessageIter_get_dict_key(VALUE self)
{
  return rb_str_new2(dbus_message_iter_get_dict_key(ITER_GET(self)));
}

#get_double ⇒ Float

Returns the floating point value of the argument that the iterator currently points at.

Returns:

  • (Float) 


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

static VALUE
cDBusMessageIter_get_double(VALUE self)
{
  _ensure_arg_type(ITER_GET(self), DBUS_TYPE_DOUBLE);
  return rb_float_new(dbus_message_iter_get_double(ITER_GET(self)));
}

#get_int32 ⇒ Integer

Returns the 32-bit integer value of the argument that the iterator currently points at.

Returns:

  • (Integer) 


201
202
203
204
205
206
 
# File 'ext/ruby-dbus-message-iter.c', line 201

static VALUE
cDBusMessageIter_get_int32(VALUE self)
{
  _ensure_arg_type(ITER_GET(self), DBUS_TYPE_INT32);
  return INT2NUM(dbus_message_iter_get_int32(ITER_GET(self)));
}

#get_int64 ⇒ Integer

Returns the 64-bit integer value of the argument that the iterator currently points at.

Returns:

  • (Integer) 


231
232
233
234
235
236
 
# File 'ext/ruby-dbus-message-iter.c', line 231

static VALUE
cDBusMessageIter_get_int64(VALUE self)
{
  _ensure_arg_type(ITER_GET(self), DBUS_TYPE_INT64);
  return LL2NUM(dbus_message_iter_get_int64(ITER_GET(self)));
}

#get_object_path ⇒ String

Returns the object path value of the argument that the iterator currently points at. An object path value is a String.

Returns:

  • (String) 


289
290
291
292
293
294
 
# File 'ext/ruby-dbus-message-iter.c', line 289

static VALUE
cDBusMessageIter_get_object_path(VALUE self)
{
  _ensure_arg_type(ITER_GET(self), DBUS_TYPE_OBJECT_PATH);
  return rb_str_new2(dbus_message_iter_get_object_path(ITER_GET(self)));
}

#get_string ⇒ String

Returns the string value of the argument that the iterator currently points at.

Returns:

  • (String) 


275
276
277
278
279
280
 
# File 'ext/ruby-dbus-message-iter.c', line 275

static VALUE
cDBusMessageIter_get_string(VALUE self)
{
  _ensure_arg_type(ITER_GET(self), DBUS_TYPE_STRING);
  return rb_str_new2(dbus_message_iter_get_string(ITER_GET(self)));
}

#get_uint32 ⇒ Integer

Returns the unsigned 32-bit integer value of the argument that the iterator currently points at.

Returns:

  • (Integer) 


215
216
217
218
219
220
 
# File 'ext/ruby-dbus-message-iter.c', line 215

static VALUE
cDBusMessageIter_get_uint32(VALUE self)
{
  _ensure_arg_type(ITER_GET(self), DBUS_TYPE_UINT32);
  return INT2NUM(dbus_message_iter_get_uint32(ITER_GET(self)));
}

#get_uint64 ⇒ Integer

Returns the unsigned 64-bit integer value of the argument that the iterator currently points at.

Returns:

  • (Integer) 


245
246
247
248
249
250
 
# File 'ext/ruby-dbus-message-iter.c', line 245

static VALUE
cDBusMessageIter_get_uint64(VALUE self)
{
  _ensure_arg_type(ITER_GET(self), DBUS_TYPE_UINT64);
  return ULL2NUM(dbus_message_iter_get_uint64(ITER_GET(self)));
}

#has_next ⇒ Object

Returns true if there are additional arguments after the current iterator argument.



115
116
117
118
119
120
121
 
# File 'ext/ruby-dbus-message-iter.c', line 115

static VALUE
cDBusMessageIter_has_next(VALUE self)
{
  if (dbus_message_iter_has_next(ITER_GET(self)))
    return Qtrue;
  return Qfalse;
}

#next ⇒ Object

Moves the iterator to the next argument.



129
130
131
132
133
134
135
 
# File 'ext/ruby-dbus-message-iter.c', line 129

static VALUE
cDBusMessageIter_next(VALUE self)
{
  if (dbus_message_iter_next(ITER_GET(self)))
    return Qtrue;
  return Qfalse;
}

#value ⇒ Object Also known as: get

Returns the message argument value at the current position of the iterator. The value is converted from the D-BUS type to the closest matching Ruby type.



132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
 
# File 'lib/dbus/binding.rb', line 132

def value
  case get_arg_type
  when TYPE_NIL
    nil
  when TYPE_BYTE
    get_byte
  when TYPE_BOOLEAN
    get_boolean
  when TYPE_INT32
    get_int32
  when TYPE_UINT32
    get_uint32
  when TYPE_INT64
    get_int64
  when TYPE_UINT64
    get_uint64
  when TYPE_DOUBLE
    get_double
  when TYPE_STRING
    get_string
  when TYPE_ARRAY
    get_array
  when TYPE_DICT
    get_dict
  when TYPE_OBJECT_PATH
    ObjectPath.new(get_object_path)
  else
    raise DBusError, "unsupported iter arg type '#{type_as_string(get_arg_type)}'"
  end
end