# 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
    114 def self.error(m, error_name, description = nil)
    115   ErrorMessage.new(error_name, description).reply_to(m)
    116 end

method_return(m) click to toggle source

Create a regular reply to a message m.

        # File lib/dbus/message.rb
    109 def self.method_return(m)
    110   MethodReturnMessage.new.reply_to(m)
    111 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
    80 def initialize(mtype = INVALID)
    81   @message_type = mtype
    82
    83   @flags = 0
    84   @protocol = 1
    85   @body_length = 0
    86   @signature = ""
    87   @@serial_mutex.synchronize do
    88     @serial = @@serial
    89     @@serial += 1
    90   end
    91   @params = []
    92   @destination = nil
    93   @interface = nil
    94   @error_name = nil
    95   @member = nil
    96   @path = nil
    97   @reply_serial = nil
    98   @flags = NO_REPLY_EXPECTED if mtype == METHOD_RETURN
    99 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
    128 def add_param(type, val)
    129   type = type.chr if type.is_a?(Integer)
    130   @signature += type.to_s
    131   @params << [type, val]
    132 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
    234 def annotate_exception(ex)
    235   new_ex = ex.exception("#{ex}; caused by #{self}")
    236   new_ex.set_backtrace(ex.backtrace)
    237   new_ex
    238 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
    150 def marshall
    151   if @path == "/org/freedesktop/DBus/Local"
    152     raise InvalidDestinationName
    153   end
    154
    155   params = PacketMarshaller.new
    156   @params.each do |param|
    157     params.append(param[0], param[1])
    158   end
    159   @body_length = params.packet.bytesize
    160
    161   marshaller = PacketMarshaller.new
    162   marshaller.append(Type::BYTE, HOST_END)
    163   marshaller.append(Type::BYTE, @message_type)
    164   marshaller.append(Type::BYTE, @flags)
    165   marshaller.append(Type::BYTE, @protocol)
    166   marshaller.append(Type::UINT32, @body_length)
    167   marshaller.append(Type::UINT32, @serial)
    168
    169   headers = []
    170   headers << [PATH,         ["o", @path]]         if @path
    171   headers << [INTERFACE,    ["s", @interface]]    if @interface
    172   headers << [MEMBER,       ["s", @member]]       if @member
    173   headers << [ERROR_NAME,   ["s", @error_name]]   if @error_name
    174   headers << [REPLY_SERIAL, ["u", @reply_serial]] if @reply_serial
    175   headers << [DESTINATION,  ["s", @destination]]  if @destination
    176   #           SENDER is not sent, the message bus fills it in instead
    177   headers << [SIGNATURE,    ["g", @signature]]    if @signature != ""
    178   marshaller.append("a(yv)", headers)
    179
    180   marshaller.align(8)
    181   @params.each do |param|
    182     marshaller.append(param[0], param[1])
    183   end
    184   marshaller.packet
    185 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
    121 def reply_to(m)
    122   @reply_serial = m.serial
    123   @destination = m.sender
    124   self
    125 end

to_s() click to toggle source

        # File lib/dbus/message.rb
    101 def to_s
    102   "#{message_type} sender=#{sender} -> dest=#{destination} " \
    103   "serial=#{serial} reply_serial=#{reply_serial} " \
    104   "path=#{path}; interface=#{interface}; member=#{member} " \
    105   "error_name=#{error_name}"
    106 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
    193 def unmarshall_buffer(buf)
    194   buf = buf.dup
    195   endianness = if buf[0] == "l"
    196                  LIL_END
    197                else
    198                  BIG_END
    199                end
    200   pu = PacketUnmarshaller.new(buf, endianness)
    201   mdata = pu.unmarshall(MESSAGE_SIGNATURE)
    202   _, @message_type, @flags, @protocol, @body_length, @serial,
    203     headers = mdata
    204
    205   headers.each do |struct|
    206     case struct[0]
    207     when PATH
    208       @path = struct[1]
    209     when INTERFACE
    210       @interface = struct[1]
    211     when MEMBER
    212       @member = struct[1]
    213     when ERROR_NAME
    214       @error_name = struct[1]
    215     when REPLY_SERIAL
    216       @reply_serial = struct[1]
    217     when DESTINATION
    218       @destination = struct[1]
    219     when SENDER
    220       @sender = struct[1]
    221     when SIGNATURE
    222       @signature = struct[1]
    223     end
    224   end
    225   pu.align(8)
    226   if @body_length > 0 && @signature
    227     @params = pu.unmarshall(@signature, @body_length)
    228   end
    229   [self, pu.idx]
    230 end