class DBus::Message

D-Bus message class

Class that holds any type of message that travels over the bus.

Constants

DESTINATION
ENDIANNESS
ENDIANNESS_CHAR

“l” or “B”

ERROR

Error message type.

ERROR_NAME
INTERFACE
INVALID

FIXME: following message type constants should be under Message::Type IMO well, yeah sure

Invalid message type.

MEMBER
MESSAGE_SIGNATURE

Type of a message (by specification).

METHOD_CALL

Method call message type.

METHOD_RETURN

Method call return value message type.

NO_AUTO_START

Message flag signifying that no automatic start is required/must be performed.

NO_REPLY_EXPECTED

Message flag signyfing that no reply is expected.

PATH

FIXME: what are these? a message element constant enumeration? See method below, in a message, you have and array of optional parameters that come with an index, to determine their meaning. The values are in spec, more a definition than an enumeration.

REPLY_SERIAL
RESERVED_PATH
SENDER
SIGNAL

Signal message type.

SIGNATURE
TYPE_NAMES

Names used by signal match rules

Attributes

destination[RW]

The destination connection of the object that must be used/was used.

error_name[RW]

The name of the error (in case of an error message type).

interface[RW]

The interface of the object that must be used/was used.

member[RW]

The interface member (method/signal name) of the object that must be used/was used.

message_type[R]

The type of the message.

params[R]

The parameters of the message.

path[RW]

The path of the object instance the message must be sent to/is sent from.

protocol[R]

The protocol.

reply_serial[RW]

@return [Integer] (u32)

The serial number of the message this message is a reply for.
sender[RW]

The sender of the message.

serial[R]

@return [Integer] (u32)

The serial of the message.
signature[RW]

The signature of the message contents.

Public Class Methods

error(msg, error_name, description = nil) click to toggle source

Create an error reply to a message msg.

# File lib/dbus/message.rb, line 123
def self.error(msg, error_name, description = nil)
  ErrorMessage.new(error_name, description).reply_to(msg)
end
method_return(msg) click to toggle source

Create a regular reply to a message msg.

# File lib/dbus/message.rb, line 118
def self.method_return(msg)
  MethodReturnMessage.new.reply_to(msg)
end
new(mtype = INVALID) click to toggle source

Create a message with message type mtype with default values and a unique serial number.

# File lib/dbus/message.rb, line 83
def initialize(mtype = INVALID)
  @message_type = mtype

  @flags = 0
  @protocol = 1
  @body_length = 0
  @signature = ""
  @@serial_mutex.synchronize do
    @serial = @@serial
    @@serial += 1
  end
  @params = []
  @destination = nil
  @interface = nil
  @error_name = nil
  @member = nil
  @path = nil
  @reply_serial = nil
  @flags = NO_REPLY_EXPECTED if mtype == METHOD_RETURN
end

Public Instance Methods

add_param(type, val) click to toggle source

Add a parameter val of type type to the message.

# File lib/dbus/message.rb, line 137
def add_param(type, val)
  type = type.chr if type.is_a?(Integer)
  @signature += type.to_s
  @params << [type, val]
end
annotate_exception(exc) click to toggle source

Make a new exception from ex, mark it as being caused by this message @api private

# File lib/dbus/message.rb, line 243
def annotate_exception(exc)
  new_exc = exc.exception("#{exc}; caused by #{self}")
  new_exc.set_backtrace(exc.backtrace)
  new_exc
end
marshall() click to toggle source

Marshall the message with its current set parameters and return it in a packet form. @return [String]

# File lib/dbus/message.rb, line 166
def marshall
  if @path == RESERVED_PATH
    # the bus would disconnect us, better explain why
    raise "Cannot send a message with the reserved path #{RESERVED_PATH}: #{inspect}"
  end

  params_marshaller = PacketMarshaller.new(endianness: ENDIANNESS)
  @params.each do |type, value|
    params_marshaller.append(type, value)
  end
  @body_length = params_marshaller.packet.bytesize

  marshaller = PacketMarshaller.new(endianness: ENDIANNESS)
  marshaller.append(Type::BYTE, ENDIANNESS_CHAR.ord)
  marshaller.append(Type::BYTE, @message_type)
  marshaller.append(Type::BYTE, @flags)
  marshaller.append(Type::BYTE, @protocol)
  marshaller.append(Type::UINT32, @body_length)
  marshaller.append(Type::UINT32, @serial)

  headers = []
  headers << [PATH,         ["o", @path]]         if @path
  headers << [INTERFACE,    ["s", @interface]]    if @interface
  headers << [MEMBER,       ["s", @member]]       if @member
  headers << [ERROR_NAME,   ["s", @error_name]]   if @error_name
  headers << [REPLY_SERIAL, ["u", @reply_serial]] if @reply_serial
  headers << [DESTINATION,  ["s", @destination]]  if @destination
  #           SENDER is not sent, the message bus fills it in instead
  headers << [SIGNATURE,    ["g", @signature]]    if @signature != ""
  marshaller.append("a(yv)", headers)

  marshaller.align(8)

  marshaller.packet + params_marshaller.packet
end
message_type_s() click to toggle source

@return [String] name of message type, as used in match rules:

"method_call", "method_return", "signal", "error"
# File lib/dbus/message.rb, line 113
def message_type_s
  TYPE_NAMES[message_type] || "unknown_type_#{message_type}"
end
reply_to(msg) click to toggle source

Mark this message as a reply to a another message msg, taking the serial number of msg as reply serial and the sender of msg as destination.

# File lib/dbus/message.rb, line 130
def reply_to(msg)
  @reply_serial = msg.serial
  @destination = msg.sender
  self
end
to_s() click to toggle source
# File lib/dbus/message.rb, line 104
def to_s
  "#{message_type} sender=#{sender} -> dest=#{destination} " \
  "serial=#{serial} reply_serial=#{reply_serial} " \
  "path=#{path}; interface=#{interface}; member=#{member} " \
  "error_name=#{error_name}"
end
unmarshall_buffer(buf) click to toggle source

Unmarshall a packet contained in the buffer buf and set the parameters of the message object according the data found in the buffer. @return [Array(Message,Integer)]

the detected message (self) and
the index pointer of the buffer where the message data ended.
# File lib/dbus/message.rb, line 208
def unmarshall_buffer(buf)
  pu = PacketUnmarshaller.new(buf, RawMessage.endianness(buf[0]))
  mdata = pu.unmarshall(MESSAGE_SIGNATURE)
  _, @message_type, @flags, @protocol, @body_length, @serial,
    headers = mdata

  headers.each do |struct|
    case struct[0]
    when PATH
      @path = struct[1]
    when INTERFACE
      @interface = struct[1]
    when MEMBER
      @member = struct[1]
    when ERROR_NAME
      @error_name = struct[1]
    when REPLY_SERIAL
      @reply_serial = struct[1]
    when DESTINATION
      @destination = struct[1]
    when SENDER
      @sender = struct[1]
    when SIGNATURE
      @signature = struct[1]
    end
  end
  pu.align_body
  if @body_length.positive? && @signature
    @params = pu.unmarshall(@signature, @body_length)
  end
  [self, pu.consumed_size]
end