Class DBus::Message
In: lib/dbus/message.rb
Parent: Object

D-Bus message class

Class that holds any type of message that travels over the bus.

Methods

Constants

MESSAGE_SIGNATURE = "yyyyuua(yv)"   Type of a message (by specification).
INVALID = 0   FIXME: following message type constants should be under Message::Type IMO well, yeah sure

Invalid message type.

METHOD_CALL = 1   Method call message type.
METHOD_RETURN = 2   Method call return value message type.
ERROR = 3   Error message type.
SIGNAL = 4   Signal message type.
NO_REPLY_EXPECTED = 0x1   Message flag signyfing that no reply is expected.
NO_AUTO_START = 0x2   Message flag signifying that no automatic start is required/must be performed.
PATH = 1   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.
INTERFACE = 2
MEMBER = 3
ERROR_NAME = 4
REPLY_SERIAL = 5
DESTINATION = 6
SENDER = 7
SIGNATURE = 8

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

Create an error reply to a message m.

[Source]

# File lib/dbus/message.rb, line 110
    def self.error(m, error_name, description=nil)
      ErrorMessage.new(error_name, description).reply_to(m)
    end

Create a regular reply to a message m.

[Source]

# File lib/dbus/message.rb, line 105
    def self.method_return(m)
      MethodReturnMessage.new.reply_to(m)
    end

Create a message with message type mtype with default values and a unique serial number.

[Source]

# File lib/dbus/message.rb, line 80
    def initialize(mtype = INVALID)
      @message_type = mtype

      @flags = 0
      @protocol = 1
      @body_length = 0
      @signature = String.new
      @@serial_mutex.synchronize do
        @serial = @@serial
        @@serial += 1
      end
      @params = Array.new
      @destination = nil
      @interface = nil
      @error_name = nil
      @member = nil
      @path = nil
      @reply_serial = nil

      if mtype == METHOD_RETURN
        @flags = NO_REPLY_EXPECTED
      end
    end

Public Instance methods

Add a parameter val of type type to the message.

[Source]

# File lib/dbus/message.rb, line 124
    def add_param(type, val)
      type = type.chr if type.kind_of?(Fixnum)
      @signature += type.to_s
      @params << [type, val]
    end

Marshall the message with its current set parameters and return it in a packet form.

[Source]

# File lib/dbus/message.rb, line 146
    def marshall
      if @path == "/org/freedesktop/DBus/Local"
        raise InvalidDestinationName
      end

      params = PacketMarshaller.new
      @params.each do |param|
        params.append(param[0], param[1])
      end
      @body_length = params.packet.bytesize

      marshaller = PacketMarshaller.new
      marshaller.append(Type::BYTE, HOST_END)
      marshaller.append(Type::BYTE, @message_type)
      marshaller.append(Type::BYTE, @flags)
      marshaller.append(Type::BYTE, @protocol)
      marshaller.append(Type::UINT32, @body_length)
      marshaller.append(Type::UINT32, @serial)
      marshaller.array(Type::Parser.new("y").parse[0]) do
        if @path
          marshaller.struct do
            marshaller.append(Type::BYTE, PATH)
            marshaller.append(Type::BYTE, 1)
            marshaller.append_simple_string("o")
            marshaller.append(Type::OBJECT_PATH, @path)
          end
        end
        if @interface
          marshaller.struct do
            marshaller.append(Type::BYTE, INTERFACE)
            marshaller.append(Type::BYTE, 1)
            marshaller.append_simple_string("s")
            marshaller.append(Type::STRING, @interface)
          end
        end
        if @member
          marshaller.struct do
            marshaller.append(Type::BYTE, MEMBER)
            marshaller.append(Type::BYTE, 1)
            marshaller.append_simple_string("s")
            marshaller.append(Type::STRING, @member)
          end
        end
        if @error_name
          marshaller.struct do
            marshaller.append(Type::BYTE, ERROR_NAME)
            marshaller.append(Type::BYTE, 1)
            marshaller.append_simple_string("s")
            marshaller.append(Type::STRING, @error_name)
          end
        end
        if @reply_serial
          marshaller.struct do
            marshaller.append(Type::BYTE, REPLY_SERIAL)
            marshaller.append(Type::BYTE, 1)
            marshaller.append_simple_string("u")
            marshaller.append(Type::UINT32, @reply_serial)
          end
        end
        if @destination
          marshaller.struct do
            marshaller.append(Type::BYTE, DESTINATION)
            marshaller.append(Type::BYTE, 1)
            marshaller.append_simple_string("s")
            marshaller.append(Type::STRING, @destination)
          end
        end
        if @signature != ""
          marshaller.struct do
            marshaller.append(Type::BYTE, SIGNATURE)
            marshaller.append(Type::BYTE, 1)
            marshaller.append_simple_string("g")
            marshaller.append(Type::SIGNATURE, @signature)
          end
        end
      end
      marshaller.align(8)
      @params.each do |param|
        marshaller.append(param[0], param[1])
      end
      marshaller.packet
    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.

[Source]

# File lib/dbus/message.rb, line 117
    def reply_to(m)
      @reply_serial = m.serial
      @destination = m.sender
      self
    end

Unmarshall the data of a message found in the buffer buf using Message#unmarshall_buf. Return the message.

[Source]

# File lib/dbus/message.rb, line 276
    def unmarshall(buf)
      ret, size = unmarshall_buffer(buf)
      ret
    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 the detected message and the index pointer of the buffer where the message data ended.

[Source]

# File lib/dbus/message.rb, line 234
    def unmarshall_buffer(buf)
      buf = buf.dup
      if buf[0] == ?l
        endianness = LIL_END
      else
        endianness = BIG_END
      end
      pu = PacketUnmarshaller.new(buf, endianness)
      mdata = pu.unmarshall(MESSAGE_SIGNATURE)
      dummy, @message_type, @flags, @protocol, @body_length, @serial, 
        headers = mdata

      headers.each do |struct|
        case struct[0]
        when PATH
          @path = struct[1]
        when INTERFACE
          @interface = struct[1]
        when MEMBER
          @member = struct[1]
        when ERROR_NAME
          @error_name = struct[1]
        when REPLY_SERIAL
          @reply_serial = struct[1]
        when DESTINATION
          @destination = struct[1]
        when SENDER
          @sender = struct[1]
        when SIGNATURE
          @signature = struct[1]
        end
      end
      pu.align(8)
      if @body_length > 0 and @signature
        @params = pu.unmarshall(@signature, @body_length)
      end
      [self, pu.idx]
    end

[Validate]