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