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.



557
558
559
560
561
562
563
564
565
566
567
568
569
 
# File 'ext/ruby-dbus-message-iter.c', line 557

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

  parent = RDBUS_GET(RubyDBusMessageIter, self);
  child = _alloc_message_iter(parent->message, NULL);
  if (dbus_message_iter_append_array(parent->real_iter, child->real_iter, NUM2INT(type)))
    return RDBUS_NEW(cDBusMessageIter, child);
  _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.



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

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.



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

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.



584
585
586
587
588
589
590
591
592
593
594
595
596
 
# File 'ext/ruby-dbus-message-iter.c', line 584

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

  parent = RDBUS_GET(RubyDBusMessageIter, self);
  child = _alloc_message_iter(parent->message, NULL);
  if (dbus_message_iter_append_dict(parent->real_iter, child->real_iter))
    return RDBUS_NEW(cDBusMessageIter, child);
  _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.



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

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.



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

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.



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

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.



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

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.



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

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.



518
519
520
521
522
523
524
 
# File 'ext/ruby-dbus-message-iter.c', line 518

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.



502
503
504
505
506
507
508
 
# File 'ext/ruby-dbus-message-iter.c', line 502

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.



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

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.



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

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.



296
297
298
299
300
301
302
303
304
305
306
307
308
 
# File 'ext/ruby-dbus-message-iter.c', line 296

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

  self_iter = RDBUS_GET(RubyDBusMessageIter, 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 RDBUS_NEW(cDBusMessageIter, 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.



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

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

  self_iter = RDBUS_GET(RubyDBusMessageIter, 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 RDBUS_NEW(cDBusMessageIter, 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.



121
122
123
124
125
 
# File 'ext/ruby-dbus-message-iter.c', line 121

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.



134
135
136
137
138
 
# File 'ext/ruby-dbus-message-iter.c', line 134

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.



162
163
164
165
166
167
168
169
 
# File 'ext/ruby-dbus-message-iter.c', line 162

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.



148
149
150
151
152
153
 
# File 'ext/ruby-dbus-message-iter.c', line 148

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) 


281
282
283
284
285
 
# File 'ext/ruby-dbus-message-iter.c', line 281

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) 


238
239
240
241
242
243
 
# File 'ext/ruby-dbus-message-iter.c', line 238

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) 


178
179
180
181
182
183
 
# File 'ext/ruby-dbus-message-iter.c', line 178

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) 


208
209
210
211
212
213
 
# File 'ext/ruby-dbus-message-iter.c', line 208

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) 


266
267
268
269
270
271
 
# File 'ext/ruby-dbus-message-iter.c', line 266

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) 


252
253
254
255
256
257
 
# File 'ext/ruby-dbus-message-iter.c', line 252

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) 


192
193
194
195
196
197
 
# File 'ext/ruby-dbus-message-iter.c', line 192

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) 


222
223
224
225
226
227
 
# File 'ext/ruby-dbus-message-iter.c', line 222

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.



92
93
94
95
96
97
98
 
# File 'ext/ruby-dbus-message-iter.c', line 92

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.



106
107
108
109
110
111
112
 
# File 'ext/ruby-dbus-message-iter.c', line 106

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