Class DBus::Binding::DBusMessage
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

Included Modules

Enumerable

Public Class methods

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

[Source]

/*
 *  call-seq:
 *    new(type) => self
 *
 *  Creates a new DBusMessage of the specified type, which may be one
 *  of the DBus MESSAGE_TYPE constants.
 */
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);
}

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.

[Source]

/*
 *  call-seq:
 *      new_error(request_message, error_name, error_message)
 *
 *  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.
 */
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);
}

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

[Source]

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

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

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

[Source]

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

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.

[Source]

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

Public Instance methods

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.

[Source]

    # File lib/dbus/binding.rb, line 76
76:     def <<(value)
77:       iter = get_append_iter
78:       iter.append(value)
79:       nil
80:     end

Returns the message argument value at the given offset

[Source]

    # File lib/dbus/binding.rb, line 63
63:     def [](offset)
64:       entries[offset]
65:     end

Appends each item in the given Array to the message

[Source]

    # File lib/dbus/binding.rb, line 68
68:     def append(ary)
69:       iter = get_append_iter
70:       ary.each{|value| iter.append(value)}
71:       nil
72:     end

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

[Source]

    # File lib/dbus/binding.rb, line 45
45:     def each
46:       raise DBusError, "block expected" unless block_given?
47:       iter = get_iter
48:       begin
49:         value = iter.value
50:       rescue
51:         return nil
52:       end
53:       yield value
54:       have_value = iter.next
55:       while have_value
56:         yield iter.value
57:         have_value = iter.next
58:       end
59:       nil
60:     end

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

[Source]

/*
 *  call-seq:
 *      get_append_iter => message append iterator
 *
 *  Returns a DBusMessageIter iterator instance for appending values to
 *  this message. The position of the iterator is at the end of any existing
 *  values.
 */
static VALUE
cDBusMessage_get_append_iter(VALUE self)
{
  return ITER_NEW(MSG_GET(self), TRUE);
}

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

[Source]

/*
 *  call-seq:
 *      get_auto_activation => true|false
 *
 *  Returns +true+ if the message will cause the addressed service
 *  to be auto-activated.
 */
static VALUE
cDBusMessage_get_auto_activation(VALUE self)
{
  if (!dbus_message_get_auto_activation(MSG_GET(self)))
    return Qfalse;
  return Qtrue;
}

Gets the destination service of this message.

[Source]

/*
 *  call-seq:
 *      get_destination => service
 *
 *  Gets the destination service of this message.
 */
static VALUE
cDBusMessage_get_destination(VALUE self)
{
  MESSAGE_STR_GETTER_BODY(destination);
}

Gets the error name (for an error message).

[Source]

/*
 *  call-seq:
 *      get_error_name => name
 *
 *  Gets the error name (for an error message).
 */
static VALUE
cDBusMessage_get_error_name(VALUE self)
{
  MESSAGE_STR_GETTER_BODY(error_name);
}

Gets the interface this message is being sent to.

[Source]

/*
 *  call-seq:
 *      get_path => objectpath
 *
 *  Gets the interface this message is being sent to.
 */
static VALUE
cDBusMessage_get_interface(VALUE self)
{
  MESSAGE_STR_GETTER_BODY(interface);
}

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.

[Source]

/*
 *  call-seq:
 *      get_iter => message iterator
 *
 *  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.
 */
static VALUE
cDBusMessage_get_iter(VALUE self)
{
  return ITER_NEW(MSG_GET(self), FALSE);
}

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

[Source]

/*
 *  call-seq:
 *      get_member => membername
 *
 *  Gets the interface member being invoked (for a method call), or
 *  emitted (for a signal).
 */
static VALUE
cDBusMessage_get_member(VALUE self)
{
  MESSAGE_STR_GETTER_BODY(member);
}

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

[Source]

/*
 *  call-seq:
 *      get_no_reply => true|false
 *
 *  Returns +true+ if the message sender is not expecting a reply message.
 */
static VALUE
cDBusMessage_get_no_reply(VALUE self)
{
  if (!dbus_message_get_no_reply(MSG_GET(self)))
    return Qfalse;
  return Qtrue;
}

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

[Source]

/*
 *  call-seq:
 *      get_path => objectpath
 *
 *  Gets the object path this message is being sent to (for a method call),
 *  or being emitted from (for a signal).
 */
static VALUE
cDBusMessage_get_path(VALUE self)
{
  MESSAGE_STR_GETTER_BODY(path);
}

Returns an array containing the path segments of the message path

[Source]

    # File lib/dbus/binding.rb, line 83
83:     def get_path_decomposed
84:       get_path.split("/")
85:     end

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

[Source]

/*
 *  call-seq:
 *    get_reply_serial => serial
 *
 *  Returns the serial number (see DbusMessage#get_serial) of the message
 *  that this message is a reply to.
 */
static VALUE
cDBusMessage_get_reply_serial(VALUE self)
{
  return INT2NUM(dbus_message_get_reply_serial(MSG_GET(self)));
}

Gets the sending service of this message.

[Source]

/*
 *  call-seq:
 *      get_sender => service
 *
 *  Gets the sending service of this message.
 */
static VALUE
cDBusMessage_get_sender(VALUE self)
{
  MESSAGE_STR_GETTER_BODY(sender);
}

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

[Source]

/*
 *  call-seq:
 *    get_serial => serial
 *
 *  Returns the client serial number of the message. This can't be set.
 */
static VALUE
cDBusMessage_get_serial(VALUE self)
{
  return INT2NUM(dbus_message_get_serial(MSG_GET(self)));
}

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:

[Source]

/*
 *  call-seq:
 *      get_signature => service
 *
 *  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:
 */
static VALUE
cDBusMessage_get_signature(VALUE self)
{
  MESSAGE_STR_GETTER_BODY(signature);
}

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

[Source]

/*
 *  call-seq:
 *      get_type => type
 *
 *  Returns an integer representing the message type. Its value will
 *  be one of the MESSAGE_TYPE constants.
 */
static VALUE
cDBusMessage_get_type(VALUE self)
{
  return INT2FIX(dbus_message_get_type(MSG_GET(self)));
}

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

[Source]

/*
 *  call-seq:
 *      has_destination(service) => true | false
 *  
 *  Returns +true+ if the message has a destination service with the given
 *  service name.
 */
static VALUE
cDBusMessage_has_destination(VALUE self, VALUE service)
{
  if (!dbus_message_has_destination(MSG_GET(self), StringValuePtr(service)))
    return Qfalse;
  return Qtrue;
}

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

[Source]

/*
 *  call-seq:
 *      has_sender(service) => true | false
 *  
 *  Returns +true+ if the message has the given service name as its sender.
 */
static VALUE
cDBusMessage_has_sender(VALUE self, VALUE service)
{
  if (!dbus_message_has_sender(MSG_GET(self), StringValuePtr(service)))
    return Qfalse;
  return Qtrue;
}

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

[Source]

/*
 *  call-seq:
 *    has_signature(signature) => true | false
 *
 *  Returns +true+ if the message has the given type signature.
 *  See DBusMessage#get_signature for more details on type signatures.
 */
static VALUE
cDBusMessage_has_signature(VALUE self, VALUE signature)
{
  if (!dbus_message_has_signature(MSG_GET(self), StringValuePtr(signature)))
    return Qfalse;
  return Qtrue;
}

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

[Source]

/*
 *  call-seq:
 *      is_error(error_name)
 *
 *  Returns +true+ if the message is an error message with the given error
 *  name field.
 */
static VALUE
cDBusMessage_is_error(VALUE self, VALUE error)
{
  if (!dbus_message_is_error(MSG_GET(self), StringValuePtr(error)))
    return Qfalse;
  return Qtrue;
}

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

[Source]

/*
 *  call-seq:
 *      is_method_call(interface, method_name) => true | false
 *
 *  Returns +true+ if the message is a method call message with the given
 *  method name and interface fields.
 */
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;
}

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

[Source]

/*
 *  call-seq:
 *      is_signal(interface, signal_name) => true | false
 *
 *  Returns +true+ if the message is a signal message with the given interface
 *  and signal name fields.
 */
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;
}

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.

[Source]

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

Sets the message’s destination service.

Returns false if not enough memory.

[Source]

/*
 *  call-seq:
 *      set_destination(service) => true|false
 *
 *  Sets the message's destination service.
 *
 *  Returns +false+ if not enough memory.
 */
static VALUE
cDBusMessage_set_destination(VALUE self, VALUE value)
{
  MESSAGE_STR_SETTER_BODY(destination);
}

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

Returns false if not enough memory.

[Source]

/*
 *  call-seq:
 *      set_error_name(name) => true|false
 *
 *  Sets the name of the error (for an error message).
 *
 *  Returns +false+ if not enough memory.
 */
static VALUE
cDBusMessage_set_error_name(VALUE self, VALUE value)
{
  MESSAGE_STR_SETTER_BODY(error_name);
}

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.

[Source]

/*
 *  call-seq:
 *      set_interface(interface) => true|false
 *
 *  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.
 */
static VALUE
cDBusMessage_set_interface(VALUE self, VALUE value)
{
  MESSAGE_STR_SETTER_BODY(interface);
}

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

Returns false if not enough memory.

[Source]

/*
 *  call-seq:
 *      set_member(member) => true|false
 *
 *  Sets the interface member being invoked (for a method call), or emitted 
 *  (for a signal).
 *
 *  Returns +false+ if not enough memory.
 */
static VALUE
cDBusMessage_set_member(VALUE self, VALUE value)
{
  MESSAGE_STR_SETTER_BODY(member);
}

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.

[Source]

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

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.

[Source]

/*
 *  call-seq:
 *      set_path(object_path) => true|false
 *
 *  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.
 */
static VALUE
cDBusMessage_set_path(VALUE self, VALUE value)
{
  MESSAGE_STR_SETTER_BODY(path);
}

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

[Source]

/*
 *  call-seq:
 *    set_reply_serial(serial) => true
 *
 *  Sets the serial number (see DbusMessage#get_serial) of the message
 *  that this message is a reply to.
 */
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;
}

Sets the service sending this message.

Returns false if not enough memory.

[Source]

/*
 *  call-seq:
 *      set_sender(service) => true|false
 *
 *  Sets the service sending this message.
 *
 *  Returns +false+ if not enough memory.
 */
static VALUE
cDBusMessage_set_sender(VALUE self, VALUE value)
{
  MESSAGE_STR_SETTER_BODY(sender);
}

[Source]

    # File lib/dbus/binding.rb, line 87
87:     def to_s
88:       "#<#{self.class.to_s} path=\"#{get_path}\" interface=\"#{get_interface}\" member=\"#{get_member}\" sender=\"#{get_sender}\">"
89:     end

[Validate]