Class DBus::Binding::DBusMessageIter
In: ruby-dbus.c
lib/dbus/binding.rb
Parent: Object

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.

Methods

Public Class methods

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

[Source]

/*
 *  call-seq:
 *      new => self
 *  
 *  The new method of this class is not available for invocation.
 */
VALUE
rdbus_private_method(VALUE klass)
{
  rb_raise(rb_eNoMethodError, "Method is unavailable to non-native methods");
  return Qnil;
}

Public Instance methods

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.

[Source]

     # File lib/dbus/binding.rb, line 96
 96:     def append(value)
 97:       case
 98:       when value.nil?
 99:         append_nil
100:       when value.is_a?(ObjectPath)
101:         append_object_path(value)
102:       when value.is_a?(String)
103:         append_string(value)
104:       when value.is_a?(Fixnum)
105:         append_int32(value)
106:       when value.is_a?(Bignum)
107:         append_int64(value)
108:       when value.is_a?(Float)
109:         append_double(value)
110:       when value.is_a?(TrueClass)
111:         append_boolean(true)
112:       when value.is_a?(FalseClass)
113:         append_boolean(false)
114:       when value.is_a?(Hash)
115:         di = append_dict
116:         value.each{|k,v| di.append_dict_key(k); di.append(v); }
117:         true
118:       when value.is_a?(Array)
119:         raise ArgumentError, "empty arrays are not supported" if value.empty?
120:         dtype = ruby_to_dbus_type(value[0])
121:         ai = append_array(dtype)
122:         value.each{|v| ai.append(v) if ruby_to_dbus_type(v) == dtype}
123:         true
124:       else
125:         raise ArgumentError, "unsupported argument type #{value.class}"
126:       end
127:     end

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.

[Source]

/*
 *  call-seq:
 *      append_array(typecode) => iterator
 *
 *  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.
 */
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;
}

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

Returns false if no memory.

[Source]

/*
 *  call-seq:
 *      append_boolean(true|false|nil) => true|false
 *
 *  Appends a boolean argument value to this message. +nil+ is
 *  regarded as a false value if passed through.
 *
 *  Returns +false+ if no memory.
 */
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;
}

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.

[Source]

/*
 *  call-seq:
 *      append_byte(byte) => true|false
 *
 *  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.
 */
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;
}

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.

[Source]

/*
 *  call-seq:
 *      append_dict => iterator
 *
 *  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 <tt>key=>value</tt> pairs
 *  to the dictionary.
 *
 *  See DBusMessageIter#append for an example of usage.
 *
 *  Returns +nil+ if no memory.
 */
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;
}

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.

[Source]

/*
 *  call-seq:
 *      append_dict_key(string) => true|false
 *
 *  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.
 */
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;
}

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.

[Source]

/*
 *  call-seq:
 *      append_double(float) => true|false
 *
 *  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.
 */
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;
}

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.

[Source]

/*
 *  call-seq:
 *      append_int32(integer) => true|false
 *
 *  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.
 */
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;
}

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.

[Source]

/*
 *  call-seq:
 *      append_int64(integer) => true|false
 *
 *  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.
 */
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;
}

Appends a nil argument value to this message.

Returns false if no memory.

[Source]

/*
 *  call-seq:
 *      append_nil => true|false
 *
 *  Appends a nil argument value to this message.
 *
 *  Returns +false+ if no memory.
 */
static VALUE
cDBusMessageIter_append_nil(VALUE self)
{
  if (dbus_message_iter_append_nil(ITER_GET(self)))
    return Qtrue;
  return Qfalse;
}

Appends an object path value to this message.

Returns false if no memory.

[Source]

/*
 *  call-seq:
 *      append_object_path(string) => true|false
 *
 *  Appends an object path value to this message. 
 *
 *  Returns +false+ if no memory.
 */
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;
}

Appends a string value to this message.

Returns false if no memory.

[Source]

/*
 *  call-seq:
 *      append_string(string) => true|false
 *
 *  Appends a string value to this message. 
 *
 *  Returns +false+ if no memory.
 */
static VALUE
cDBusMessageIter_append_string(VALUE self, VALUE value)
{
  if (dbus_message_iter_append_string(ITER_GET(self), StringValuePtr(value)))
    return Qtrue;
  return Qfalse;
}

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.

[Source]

/*
 *  call-seq:
 *      append_uint32(integer) => true|false
 *
 *  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.
 */
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;
}

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.

[Source]

/*
 *  call-seq:
 *      append_uint64(integer) => true|false
 *
 *  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.
 */
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;
}

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

See DBusMessageIter#get_array for an example of usage.

[Source]

/*
 *  call-seq:
 *      array_iter => iterator
 *
 *  Returns an array iterator for the array argument that this iterator
 *  currently points to.
 *
 *  See DBusMessageIter#get_array for an example of usage.
 */
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);
}

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

See DBusMessageIter#get_dict for an example of usage.

[Source]

/*
 *  call-seq:
 *      dict_iter => iterator
 *
 *  Returns a dictionary iterator for the dictionary argument that this
 *  iterator currently points to. 
 *
 *  See DBusMessageIter#get_dict for an example of usage.
 */
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()

Alias for value

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

[Source]

/*
 *  call-seq:
 *      get_arg_type => typecode
 *
 *  Returns the argument type of the argument that the iterator
 *  currently points at. This is one of the TYPE_xxx codes.
 */
static VALUE
cDBusMessageIter_get_arg_type(VALUE self)
{
  return INT2FIX(dbus_message_iter_get_arg_type(ITER_GET(self)));
}

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.

[Source]

     # File lib/dbus/binding.rb, line 183
183:     def get_array
184:       iter = array_iter
185:       ret = []
186:       loop do
187:         ret << iter.value
188:         break if !iter.has_next
189:         iter.next
190:       end
191:       ret
192:     end

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

[Source]

/*
 *  call-seq:
 *      get_array_type => typecode
 *
 *  Returns the element type of the array argument that the iterator currently
 *  points at.
 */
static VALUE
cDBusMessageIter_get_array_type(VALUE self)
{
  return INT2FIX(dbus_message_iter_get_array_type(ITER_GET(self)));
}

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

[Source]

/*
 *  call-seq:
 *      get_boolean => true|false
 *
 *  Returns the boolean value of the argument that the iterator currently
 *  points at.
 */
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;
}

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.

[Source]

/*
 *  call-seq:
 *      get_byte => byte
 *
 *  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.
 */
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);
}

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.

[Source]

     # File lib/dbus/binding.rb, line 169
169:     def get_dict
170:       iter = dict_iter
171:       ret = {}
172:       loop do
173:         ret[iter.get_dict_key] = iter.value
174:         break if !iter.has_next
175:         iter.next
176:       end
177:       ret
178:     end

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.

[Source]

/*
 *  call-seq:
 *      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.
 */
static VALUE
cDBusMessageIter_get_dict_key(VALUE self)
{
  return rb_str_new2(dbus_message_iter_get_dict_key(ITER_GET(self)));
}

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

[Source]

/*
 *  call-seq:
 *      get_double => float
 *
 *  Returns the floating point value of the argument that the
 *  iterator currently points at.
 */
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)));
}

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

[Source]

/*
 *  call-seq:
 *      get_int32 => integer
 *
 *  Returns the 32-bit integer value of the argument that the iterator
 *  currently points at.
 */
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)));
}

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

[Source]

/*
 *  call-seq:
 *      get_int64 => integer
 *
 *  Returns the 64-bit integer value of the argument that the
 *  iterator currently points at.
 */
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)));
}

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

[Source]

/*
 *  call-seq:
 *      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.
 */
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)));
}

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

[Source]

/*
 *  call-seq:
 *      get_string => string
 *
 *  Returns the string value of the argument that the iterator currently
 *  points at.
 */
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)));
}

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

[Source]

/*
 *  call-seq:
 *      get_uint32 => integer
 *
 *  Returns the unsigned 32-bit integer value of the argument that the
 *  iterator currently points at.
 */
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)));
}

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

[Source]

/*
 *  call-seq:
 *      get_uint64 => integer
 *
 *  Returns the unsigned 64-bit integer value of the argument that the
 *  iterator currently points at.
 */
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)));
}

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

[Source]

/*
 *  call-seq:
 *      has_next => true|false
 *
 *  Returns true if there are additional arguments after the current
 *  iterator argument.
 */
static VALUE
cDBusMessageIter_has_next(VALUE self)
{
  if (dbus_message_iter_has_next(ITER_GET(self)))
    return Qtrue;
  return Qfalse;
}

Moves the iterator to the next argument.

[Source]

/*
 *  call-seq:
 *      next => true|false
 *
 *  Moves the iterator to the next argument.
 */
static VALUE
cDBusMessageIter_next(VALUE self)
{
  if (dbus_message_iter_next(ITER_GET(self)))
    return Qtrue;
  return Qfalse;
}

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.

[Source]

     # File lib/dbus/binding.rb, line 132
132:     def value
133:       case get_arg_type
134:       when TYPE_NIL
135:         nil
136:       when TYPE_BYTE
137:         get_byte
138:       when TYPE_BOOLEAN
139:         get_boolean
140:       when TYPE_INT32
141:         get_int32
142:       when TYPE_UINT32
143:         get_uint32
144:       when TYPE_INT64
145:         get_int64
146:       when TYPE_UINT64
147:         get_uint64
148:       when TYPE_DOUBLE
149:         get_double
150:       when TYPE_STRING
151:         get_string
152:       when TYPE_ARRAY
153:         get_array
154:       when TYPE_DICT
155:         get_dict
156:       when TYPE_OBJECT_PATH
157:         ObjectPath.new(get_object_path)
158:       else
159:         raise DBusError, "unsupported iter arg type '#{type_as_string(get_arg_type)}'"
160:       end
161:     end

[Validate]