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

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)

Source

# File lib/dbus/message.rb, line 129
def self.error(msg, error_name, description = nil)
  ErrorMessage.new(error_name, description).reply_to(msg)
end

Create an error reply to a message msg.

method_return (msg)

Source

# File lib/dbus/message.rb, line 124
def self.method_return(msg)
  MethodReturnMessage.new.reply_to(msg)
end

Create a regular reply to a message msg.

new (mtype = INVALID)

Source

# File lib/dbus/message.rb, line 89
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

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

Public Instance Methods

add_param (type, val)

Source

# File lib/dbus/message.rb, line 143
def add_param(type, val)
  type = type.chr if type.is_a?(Integer)
  @signature += type.to_s
  @params << [type, val]
end

Add a parameter val of type type to the message.

annotate_exception (exc)

Source

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

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

marshall ()

Source

# File lib/dbus/message.rb, line 169
def marshall
  if @path == "/org/freedesktop/DBus/Local"
    raise InvalidDestinationName
  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

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

message_type_s ()

Source

# File lib/dbus/message.rb, line 119
def message_type_s
  TYPE_NAMES[message_type] || "unknown_type_#{message_type}"
end

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

"method_call", "method_return", "signal", "error"

reply_to (msg)

Source

# File lib/dbus/message.rb, line 136
def reply_to(msg)
  @reply_serial = msg.serial
  @destination = msg.sender
  self
end

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.

to_s ()

Source

# File lib/dbus/message.rb, line 110
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)

Source

# File lib/dbus/message.rb, line 210
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

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.