# 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
    123 def self.error(msg, error_name, description = nil)
    124   ErrorMessage.new(error_name, description).reply_to(msg)
    125 end

method_return(msg) click to toggle source

Create a regular reply to a message msg.

        # File lib/dbus/message.rb
    118 def self.method_return(msg)
    119   MethodReturnMessage.new.reply_to(msg)
    120 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
     83 def initialize(mtype = INVALID)
     84   @message_type = mtype
     85
     86   @flags = 0
     87   @protocol = 1
     88   @body_length = 0
     89   @signature = ""
     90   @@serial_mutex.synchronize do
     91     @serial = @@serial
     92     @@serial += 1
     93   end
     94   @params = []
     95   @destination = nil
     96   @interface = nil
     97   @error_name = nil
     98   @member = nil
     99   @path = nil
    100   @reply_serial = nil
    101   @flags = NO_REPLY_EXPECTED if mtype == METHOD_RETURN
    102 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
    137 def add_param(type, val)
    138   type = type.chr if type.is_a?(Integer)
    139   @signature += type.to_s
    140   @params << [type, val]
    141 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
    243 def annotate_exception(exc)
    244   new_exc = exc.exception("#{exc}; caused by #{self}")
    245   new_exc.set_backtrace(exc.backtrace)
    246   new_exc
    247 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
    166 def marshall
    167   if @path == RESERVED_PATH
    168     # the bus would disconnect us, better explain why
    169     raise "Cannot send a message with the reserved path #{RESERVED_PATH}: #{inspect}"
    170   end
    171
    172   params_marshaller = PacketMarshaller.new(endianness: ENDIANNESS)
    173   @params.each do |type, value|
    174     params_marshaller.append(type, value)
    175   end
    176   @body_length = params_marshaller.packet.bytesize
    177
    178   marshaller = PacketMarshaller.new(endianness: ENDIANNESS)
    179   marshaller.append(Type::BYTE, ENDIANNESS_CHAR.ord)
    180   marshaller.append(Type::BYTE, @message_type)
    181   marshaller.append(Type::BYTE, @flags)
    182   marshaller.append(Type::BYTE, @protocol)
    183   marshaller.append(Type::UINT32, @body_length)
    184   marshaller.append(Type::UINT32, @serial)
    185
    186   headers = []
    187   headers << [PATH,         ["o", @path]]         if @path
    188   headers << [INTERFACE,    ["s", @interface]]    if @interface
    189   headers << [MEMBER,       ["s", @member]]       if @member
    190   headers << [ERROR_NAME,   ["s", @error_name]]   if @error_name
    191   headers << [REPLY_SERIAL, ["u", @reply_serial]] if @reply_serial
    192   headers << [DESTINATION,  ["s", @destination]]  if @destination
    193   #           SENDER is not sent, the message bus fills it in instead
    194   headers << [SIGNATURE,    ["g", @signature]]    if @signature != ""
    195   marshaller.append("a(yv)", headers)
    196
    197   marshaller.align(8)
    198
    199   marshaller.packet + params_marshaller.packet
    200 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
    113 def message_type_s
    114   TYPE_NAMES[message_type] || "unknown_type_#{message_type}"
    115 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
    130 def reply_to(msg)
    131   @reply_serial = msg.serial
    132   @destination = msg.sender
    133   self
    134 end

to_s() click to toggle source

        # File lib/dbus/message.rb
    104 def to_s
    105   "#{message_type} sender=#{sender} -> dest=#{destination} " \
    106     "serial=#{serial} reply_serial=#{reply_serial} " \
    107     "path=#{path}; interface=#{interface}; member=#{member} " \
    108     "error_name=#{error_name}"
    109 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
    208 def unmarshall_buffer(buf)
    209   pu = PacketUnmarshaller.new(buf, RawMessage.endianness(buf[0]))
    210   mdata = pu.unmarshall(MESSAGE_SIGNATURE)
    211   _, @message_type, @flags, @protocol, @body_length, @serial,
    212     headers = mdata
    213
    214   headers.each do |struct|
    215     case struct[0]
    216     when PATH
    217       @path = struct[1]
    218     when INTERFACE
    219       @interface = struct[1]
    220     when MEMBER
    221       @member = struct[1]
    222     when ERROR_NAME
    223       @error_name = struct[1]
    224     when REPLY_SERIAL
    225       @reply_serial = struct[1]
    226     when DESTINATION
    227       @destination = struct[1]
    228     when SENDER
    229       @sender = struct[1]
    230     when SIGNATURE
    231       @signature = struct[1]
    232     end
    233   end
    234   pu.align_body
    235   if @body_length.positive? && @signature
    236     @params = pu.unmarshall(@signature, @body_length)
    237   end
    238   [self, pu.consumed_size]
    239 end