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
The destination connection of the object that must be used/was used.
The name of the error (in case of an error message type).
The interface of the object that must be used/was used.
The interface member (method/signal name) of the object that must be used/was used.
The type of the message.
The parameters of the message.
The path of the object instance the message must be sent to/is sent from.
The protocol.
The serial number of the message this message is a reply for.
The sender of the message.
The serial of the message.
The signature of the message contents.
Public Class Methods
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
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
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 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
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 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
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
# 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 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