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

Represents a message sent over or received from another application over the bus.

A message has a type (DBusMessage#get_type) field indicating the nature of the message, and this can be used to decide which additional fields will contain useful data.

In addition, a message can have application-specific values added to it, these are called values or arguments. The order and type of the appended values define the message type signature (see DBusMessage#get_signature).

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]