# class DBus::Message

# D-Bus message class¶ ↑

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

### Constants

DESTINATION
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

### 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]

The serial number of the message this message is a reply for.

sender[RW]

The sender of the message.

serial[R]

The serial of the message.

signature[RW]

The signature of the message contents.

### Public Class Methods

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

Create an error reply to a message m.

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

method_return(m) click to toggle source

Create a regular reply to a message m.

    # File lib/dbus/message.rb, line 109
    def self.method_return(m)
      MethodReturnMessage.new.reply_to(m)
    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 80
    def initialize(mtype = INVALID)
      @message_type = mtype

      @flags = 0
      @protocol = 1
      @body_length = 0
      @signature = String.new
      @@serial_mutex.synchronize do
        @serial = @@serial
        @@serial += 1
      end
      @params = Array.new
      @destination = nil
      @interface = nil
      @error_name = nil
      @member = nil
      @path = nil
      @reply_serial = nil

      if mtype == METHOD_RETURN
        @flags = NO_REPLY_EXPECTED
      end
    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 128
    def add_param(type, val)
      type = type.chr if type.kind_of?(Fixnum)
      @signature += type.to_s
      @params << [type, val]
    end

annotate_exception(ex) 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 241
    def annotate_exception(ex)
      new_ex = ex.exception("#{ex}; caused by #{self}")
      new_ex.set_backtrace(ex.backtrace)
      new_ex
    end

marshall() click to toggle source

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

    # File lib/dbus/message.rb, line 150
    def marshall
      if @path == "/org/freedesktop/DBus/Local"
        raise InvalidDestinationName
      end

      params = PacketMarshaller.new
      @params.each do |param|
        params.append(param[0], param[1])
      end
      @body_length = params.packet.bytesize

      marshaller = PacketMarshaller.new
      marshaller.append(Type::BYTE, HOST_END)
      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)
      @params.each do |param|
        marshaller.append(param[0], param[1])
      end
      marshaller.packet
    end

reply_to(m) click to toggle source

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

    # File lib/dbus/message.rb, line 121
    def reply_to(m)
      @reply_serial = m.serial
      @destination = m.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(buf) click to toggle source

Unmarshall the data of a message found in the buffer buf using Message#unmarshall_buf. Return the message.

    # File lib/dbus/message.rb, line 234
    def unmarshall(buf)
      ret, _ = unmarshall_buffer(buf)
      ret
    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 the detected message and the index pointer of the buffer where the message data ended.

    # File lib/dbus/message.rb, line 192
    def unmarshall_buffer(buf)
      buf = buf.dup
      if buf[0] == ?l
        endianness = LIL_END
      else
        endianness = BIG_END
      end
      pu = PacketUnmarshaller.new(buf, endianness)
      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(8)
      if @body_length > 0 and @signature
        @params = pu.unmarshall(@signature, @body_length)
      end
      [self, pu.idx]
    end