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