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.



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

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.



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

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.



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

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.



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

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.



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

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.



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

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.



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

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.



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

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.



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

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.



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

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.



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

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.



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

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.



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

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.



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

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.



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

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.



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

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.



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

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.



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

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.



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

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) 


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

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) 


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

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) 


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

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) 


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

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) 


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

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) 


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

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) 


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

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) 


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

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.



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

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.



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

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