ruby-dbus 0.18.0.beta1 → 0.18.0.beta2

data/lib/dbus/marshall.rb

@@ -12,6 +12,8 @@
 
 require "socket"
 
+require_relative "../dbus/type"
+
 # = D-Bus main module
 #
 # Module containing all the D-Bus modules and classes.
@@ -23,217 +25,128 @@ module DBus
   # = D-Bus packet unmarshaller class
   #
   # Class that handles the conversion (unmarshalling) of payload data
-  # to Array.
+  # to #{::Object}s (in **plain** mode) or to {Data::Base} (in **exact** mode)
+  #
+  # Spelling note: this codebase always uses a double L
+  # in the "marshall" word and its inflections.
   class PacketUnmarshaller
-    # Index pointer that points to the byte in the data that is
-    # currently being processed.
-    #
-    # Used to kown what part of the buffer has been consumed by unmarshalling.
-    # FIXME: Maybe should be accessed with a "consumed_size" method.
-    attr_reader :idx
-
-    # Create a new unmarshaller for the given data _buffer_ and _endianness_.
+    # Create a new unmarshaller for the given data *buffer*.
+    # @param buffer [String]
+    # @param endianness [:little,:big]
     def initialize(buffer, endianness)
-      @buffy = buffer.dup
-      @endianness = endianness
-      case @endianness
-      when BIG_END
-        @uint32 = "N"
-        @uint16 = "n"
-        @double = "G"
-      when LIL_END
-        @uint32 = "V"
-        @uint16 = "v"
-        @double = "E"
-      else
-        raise InvalidPacketException, "Incorrect endianness #{@endianness}"
-      end
-      @idx = 0
+      # TODO: this dup can be avoided if we can prove
+      # that an IncompleteBufferException leaves the original *buffer* intact
+      buffer = buffer.dup
+      @raw_msg = RawMessage.new(buffer, endianness)
     end
 
     # Unmarshall the buffer for a given _signature_ and length _len_.
-    # Return an array of unmarshalled objects
+    # Return an array of unmarshalled objects.
     # @param signature [Signature]
     # @param len [Integer,nil] if given, and there is not enough data
     #   in the buffer, raise {IncompleteBufferException}
-    # @return [Array<::Object>]
+    # @param mode [:plain,:exact]
+    # @return [Array<::Object,DBus::Data::Base>]
+    #    Objects in `:plain` mode, {DBus::Data::Base} in `:exact` mode
+    #    The array size corresponds to the number of types in *signature*.
     # @raise IncompleteBufferException
-    def unmarshall(signature, len = nil)
-      raise IncompleteBufferException if len && @buffy.bytesize < @idx + len
+    # @raise InvalidPacketException
+    def unmarshall(signature, len = nil, mode: :plain)
+      @raw_msg.want!(len) if len
 
       sigtree = Type::Parser.new(signature).parse
       ret = []
       sigtree.each do |elem|
-        ret << do_parse(elem)
+        ret << do_parse(elem, mode: mode)
       end
       ret
     end
 
-    # Align the pointer index on a byte index of _alignment_, which
-    # must be 1, 2, 4 or 8.
-    def align(alignment)
-      case alignment
-      when 1
-        nil
-      when 2, 4, 8
-        bits = alignment - 1
-        @idx = @idx + bits & ~bits
-        raise IncompleteBufferException if @idx > @buffy.bytesize
-      else
-        raise ArgumentError, "Unsupported alignment #{alignment}"
-      end
+    # after the headers, the body starts 8-aligned
+    def align_body
+      @raw_msg.align(8)
     end
 
-    ###############################################################
-    # FIXME: does anyone except the object itself call the above methods?
-    # Yes : Message marshalling code needs to align "body" to 8 byte boundary
-    private
+    # @return [Integer]
+    def consumed_size
+      @raw_msg.pos
+    end
 
-    # Retrieve the next _nbytes_ number of bytes from the buffer.
-    def read(nbytes)
-      raise IncompleteBufferException if @idx + nbytes > @buffy.bytesize
+    private
 
-      ret = @buffy.slice(@idx, nbytes)
-      @idx += nbytes
-      ret
+    # @param data_class [Class] a subclass of Data::Base (specific?)
+    # @return [::Integer,::Float]
+    def aligned_read_value(data_class)
+      @raw_msg.align(data_class.alignment)
+      bytes = @raw_msg.read(data_class.alignment)
+      bytes.unpack1(data_class.format[@raw_msg.endianness])
     end
 
-    # Read the string length and string itself from the buffer.
-    # Return the string.
-    def read_string
-      align(4)
-      str_sz = read(4).unpack1(@uint32)
-      ret = @buffy.slice(@idx, str_sz)
-      raise IncompleteBufferException if @idx + str_sz + 1 > @buffy.bytesize
+    # Based on the _signature_ type, retrieve a packet from the buffer
+    # and return it.
+    # @param signature [Type]
+    # @param mode [:plain,:exact]
+    # @return [Data::Base]
+    def do_parse(signature, mode: :plain)
+      # FIXME: better naming for packet vs value
+      packet = nil
+      data_class = Data::BY_TYPE_CODE[signature.sigtype]
 
-      @idx += str_sz
-      if @buffy[@idx].ord != 0
-        raise InvalidPacketException, "String is not nul-terminated"
+      if data_class.nil?
+        raise NotImplementedError,
+              "sigtype: #{signature.sigtype} (#{signature.sigtype.chr})"
       end
 
-      @idx += 1
-      # no exception, see check above
-      ret
-    end
+      if data_class.fixed?
+        value = aligned_read_value(data_class)
+        packet = data_class.from_raw(value, mode: mode)
+      elsif data_class.basic?
+        size = aligned_read_value(data_class.size_class)
+        value = @raw_msg.read(size)
+        nul = @raw_msg.read(1)
+        if nul != "\u0000"
+          raise InvalidPacketException, "#{data_class} is not NUL-terminated"
+        end
 
-    # Read the signature length and signature itself from the buffer.
-    # Return the signature.
-    def read_signature
-      str_sz = read(1).unpack1("C")
-      ret = @buffy.slice(@idx, str_sz)
-      raise IncompleteBufferException if @idx + str_sz + 1 >= @buffy.bytesize
+        packet = data_class.from_raw(value, mode: mode)
+      else
+        @raw_msg.align(data_class.alignment)
+        case signature.sigtype
+        when Type::STRUCT, Type::DICT_ENTRY
+          values = signature.members.map do |child_sig|
+            do_parse(child_sig, mode: mode)
+          end
+          packet = data_class.from_items(values, mode: mode, member_types: signature.members)
 
-      @idx += str_sz
-      if @buffy[@idx].ord != 0
-        raise InvalidPacketException, "Type is not nul-terminated"
-      end
+        when Type::VARIANT
+          data_sig = do_parse(Data::Signature.type, mode: :exact) # -> Data::Signature
+          types = Type::Parser.new(data_sig.value).parse # -> Array<Type>
+          unless types.size == 1
+            raise InvalidPacketException, "VARIANT must contain 1 value, #{types.size} found"
+          end
 
-      @idx += 1
-      # no exception, see check above
-      ret
-    end
+          type = types.first
+          value = do_parse(type, mode: mode)
+          packet = data_class.from_items(value, mode: mode, member_type: type)
 
-    # Based on the _signature_ type, retrieve a packet from the buffer
-    # and return it.
-    def do_parse(signature)
-      packet = nil
-      case signature.sigtype
-      when Type::BYTE
-        packet = read(1).unpack1("C")
-      when Type::UINT16
-        align(2)
-        packet = read(2).unpack1(@uint16)
-      when Type::INT16
-        align(2)
-        packet = read(2).unpack1(@uint16)
-        if (packet & 0x8000) != 0
-          packet -= 0x10000
-        end
-      when Type::UINT32, Type::UNIX_FD
-        align(4)
-        packet = read(4).unpack1(@uint32)
-      when Type::INT32
-        align(4)
-        packet = read(4).unpack1(@uint32)
-        if (packet & 0x80000000) != 0
-          packet -= 0x100000000
-        end
-      when Type::UINT64
-        align(8)
-        packet_l = read(4).unpack1(@uint32)
-        packet_h = read(4).unpack1(@uint32)
-        packet = if @endianness == LIL_END
-                   packet_l + packet_h * 2**32
-                 else
-                   packet_l * 2**32 + packet_h
-                 end
-      when Type::INT64
-        align(8)
-        packet_l = read(4).unpack1(@uint32)
-        packet_h = read(4).unpack1(@uint32)
-        packet = if @endianness == LIL_END
-                   packet_l + packet_h * 2**32
-                 else
-                   packet_l * 2**32 + packet_h
-                 end
-        if (packet & 0x8000000000000000) != 0
-          packet -= 0x10000000000000000
-        end
-      when Type::DOUBLE
-        align(8)
-        packet = read(8).unpack1(@double)
-      when Type::BOOLEAN
-        align(4)
-        v = read(4).unpack1(@uint32)
-        raise InvalidPacketException if ![0, 1].member?(v)
-
-        packet = (v == 1)
-      when Type::ARRAY
-        align(4)
-        # checks please
-        array_sz = read(4).unpack1(@uint32)
-        raise InvalidPacketException if array_sz > 67_108_864
-
-        align(signature.child.alignment)
-        raise IncompleteBufferException if @idx + array_sz > @buffy.bytesize
-
-        packet = []
-        start_idx = @idx
-        while @idx - start_idx < array_sz
-          packet << do_parse(signature.child)
-        end
+        when Type::ARRAY
+          array_bytes = aligned_read_value(Data::UInt32)
+          if array_bytes > 67_108_864
+            raise InvalidPacketException, "ARRAY body longer than 64MiB"
+          end
 
-        if signature.child.sigtype == Type::DICT_ENTRY
-          packet = Hash[packet]
-        end
-      when Type::STRUCT
-        align(8)
-        packet = []
-        signature.members.each do |elem|
-          packet << do_parse(elem)
+          # needed here because of empty arrays
+          @raw_msg.align(signature.child.alignment)
+
+          items = []
+          end_pos = @raw_msg.pos + array_bytes
+          while @raw_msg.pos < end_pos
+            item = do_parse(signature.child, mode: mode)
+            items << item
+          end
+          is_hash = signature.child.sigtype == Type::DICT_ENTRY
+          packet = data_class.from_items(items, mode: mode, member_type: signature.child, hash: is_hash)
         end
-        packet.freeze
-      when Type::VARIANT
-        string = read_signature
-        # error checking please
-        sig = Type::Parser.new(string).parse[0]
-        align(sig.alignment)
-        packet = do_parse(sig)
-      when Type::OBJECT_PATH
-        packet = read_string
-      when Type::STRING
-        packet = read_string
-        packet.force_encoding("UTF-8")
-      when Type::SIGNATURE
-        packet = read_signature
-      when Type::DICT_ENTRY
-        align(8)
-        key = do_parse(signature.members[0])
-        value = do_parse(signature.members[1])
-        packet = [key, value]
-      else
-        raise NotImplementedError,
-              "sigtype: #{signature.sigtype} (#{signature.sigtype.chr})"
       end
       packet
     end
@@ -246,11 +159,16 @@ module DBus
   class PacketMarshaller
     # The current or result packet.
     # FIXME: allow access only when marshalling is finished
+    # @return [String]
     attr_reader :packet
 
+    # @return [:little,:big]
+    attr_reader :endianness
+
     # Create a new marshaller, setting the current packet to the
     # empty packet.
-    def initialize(offset = 0)
+    def initialize(offset = 0, endianness: HOST_ENDIANNESS)
+      @endianness = endianness
       @packet = ""
       @offset = offset # for correct alignment of nested marshallers
     end
@@ -272,17 +190,6 @@ module DBus
       @packet = @packet.ljust(pad_count, 0.chr)
     end
 
-    # Append the the string _str_ itself to the packet.
-    def append_string(str)
-      align(4)
-      @packet += [str.bytesize].pack("L") + [str].pack("Z*")
-    end
-
-    # Append the the signature _signature_ itself to the packet.
-    def append_signature(str)
-      @packet += "#{str.bytesize.chr}#{str}\u0000"
-    end
-
     # Append the array type _type_ to the packet and allow for appending
     # the child elements.
     def array(type)
@@ -296,7 +203,8 @@ module DBus
       sz = @packet.bytesize - contentidx
       raise InvalidPacketException if sz > 67_108_864
 
-      @packet[sizeidx...sizeidx + 4] = [sz].pack("L")
+      sz_data = Data::UInt32.new(sz)
+      @packet[sizeidx...sizeidx + 4] = sz_data.marshall(endianness)
     end
 
     # Align and allow for appending struct fields.
@@ -308,84 +216,78 @@ module DBus
     # Append a value _val_ to the packet based on its _type_.
     #
     # Host native endianness is used, declared in Message#marshall
+    #
+    # @param type [SingleCompleteType] (or Integer or {Type})
+    # @param val [::Object]
     def append(type, val)
       raise TypeException, "Cannot send nil" if val.nil?
 
       type = type.chr if type.is_a?(Integer)
       type = Type::Parser.new(type).parse[0] if type.is_a?(String)
-      case type.sigtype
-      when Type::BYTE
-        @packet += val.chr
-      when Type::UINT32, Type::UNIX_FD
-        align(4)
-        @packet += [val].pack("L")
-      when Type::UINT64
-        align(8)
-        @packet += [val].pack("Q")
-      when Type::INT64
-        align(8)
-        @packet += [val].pack("q")
-      when Type::INT32
-        align(4)
-        @packet += [val].pack("l")
-      when Type::UINT16
-        align(2)
-        @packet += [val].pack("S")
-      when Type::INT16
-        align(2)
-        @packet += [val].pack("s")
-      when Type::DOUBLE
-        align(8)
-        @packet += [val].pack("d")
-      when Type::BOOLEAN
-        align(4)
-        @packet += if val
-                     [1].pack("L")
-                   else
-                     [0].pack("L")
-                   end
-      when Type::OBJECT_PATH
-        append_string(val)
-      when Type::STRING
-        append_string(val)
-      when Type::SIGNATURE
-        append_signature(val)
-      when Type::VARIANT
-        append_variant(val)
-      when Type::ARRAY
-        append_array(type.child, val)
-      when Type::STRUCT, Type::DICT_ENTRY
-        unless val.is_a?(Array) || val.is_a?(Struct)
-          type_name = Type::TYPE_MAPPING[type.sigtype].first
-          raise TypeException, "#{type_name} expects an Array or Struct"
-        end
+      # type is [Type] now
+      data_class = Data::BY_TYPE_CODE[type.sigtype]
+      if data_class.nil?
+        raise NotImplementedError,
+              "sigtype: #{type.sigtype} (#{type.sigtype.chr})"
+      end
 
-        if type.sigtype == Type::DICT_ENTRY && val.size != 2
-          raise TypeException, "DICT_ENTRY expects a pair"
-        end
+      if data_class.fixed?
+        align(data_class.alignment)
+        data = data_class.new(val)
+        @packet += data.marshall(endianness)
+      elsif data_class.basic?
+        val = val.value if val.is_a?(Data::Basic)
+        align(data_class.size_class.alignment)
+        size_data = data_class.size_class.new(val.bytesize)
+        @packet += size_data.marshall(endianness)
+        # Z* makes a binary string, as opposed to interpolation
+        @packet += [val].pack("Z*")
+      else
+        case type.sigtype
+
+        when Type::VARIANT
+          append_variant(val)
+        when Type::ARRAY
+          append_array(type.child, val)
+        when Type::STRUCT, Type::DICT_ENTRY
+          val = val.value if val.is_a?(Data::Struct)
+          unless val.is_a?(Array) || val.is_a?(Struct)
+            type_name = Type::TYPE_MAPPING[type.sigtype].first
+            raise TypeException, "#{type_name} expects an Array or Struct, seen #{val.class}"
+          end
 
-        if type.members.size != val.size
-          type_name = Type::TYPE_MAPPING[type.sigtype].first
-          raise TypeException, "#{type_name} has #{val.size} elements but type info for #{type.members.size}"
-        end
+          if type.sigtype == Type::DICT_ENTRY && val.size != 2
+            raise TypeException, "DICT_ENTRY expects a pair"
+          end
+
+          if type.members.size != val.size
+            type_name = Type::TYPE_MAPPING[type.sigtype].first
+            raise TypeException, "#{type_name} has #{val.size} elements but type info for #{type.members.size}"
+          end
 
-        struct do
-          type.members.zip(val).each do |t, v|
-            append(t, v)
+          struct do
+            type.members.zip(val).each do |t, v|
+              append(t, v)
+            end
           end
+        else
+          raise NotImplementedError,
+                "sigtype: #{type.sigtype} (#{type.sigtype.chr})"
         end
-      else
-        raise NotImplementedError,
-              "sigtype: #{type.sigtype} (#{type.sigtype.chr})"
       end
     end
 
     def append_variant(val)
       vartype = nil
-      if val.is_a?(Array) && val.size == 2
+      if val.is_a?(DBus::Data::Base)
+        vartype = val.type # FIXME: box or unbox another variant?
+        vardata = val.value
+      elsif val.is_a?(Array) && val.size == 2
         case val[0]
-        when DBus::Type::Type
+        when Type
           vartype, vardata = val
+        # Ambiguous but easy to use, because Type
+        # cannot construct "as" "a{sv}" easily
         when String
           begin
             parsed = Type::Parser.new(val[0]).parse
@@ -401,14 +303,14 @@ module DBus
         vartype = Type::Parser.new(vartype).parse[0]
       end
 
-      append_signature(vartype.to_s)
+      append(Data::Signature.type, vartype.to_s)
       align(vartype.alignment)
-      sub = PacketMarshaller.new(@offset + @packet.bytesize)
+      sub = PacketMarshaller.new(@offset + @packet.bytesize, endianness: endianness)
       sub.append(vartype, vardata)
       @packet += sub.packet
     end
 
-    # @param child_type [DBus::Type::Type]
+    # @param child_type [Type]
     def append_array(child_type, val)
       if val.is_a?(Hash)
         raise TypeException, "Expected an Array but got a Hash" if child_type.sigtype != Type::DICT_ENTRY

data/lib/dbus/message.rb

@@ -172,7 +172,7 @@ module DBus
       @body_length = params.packet.bytesize
 
       marshaller = PacketMarshaller.new
-      marshaller.append(Type::BYTE, HOST_END)
+      marshaller.append(Type::BYTE, HOST_END.ord)
       marshaller.append(Type::BYTE, @message_type)
       marshaller.append(Type::BYTE, @flags)
       marshaller.append(Type::BYTE, @protocol)
@@ -204,13 +204,7 @@ module DBus
     #   the detected message (self) and
     #   the index pointer of the buffer where the message data ended.
     def unmarshall_buffer(buf)
-      buf = buf.dup
-      endianness = if buf[0] == "l"
-                     LIL_END
-                   else
-                     BIG_END
-                   end
-      pu = PacketUnmarshaller.new(buf, endianness)
+      pu = PacketUnmarshaller.new(buf, RawMessage.endianness(buf[0]))
       mdata = pu.unmarshall(MESSAGE_SIGNATURE)
       _, @message_type, @flags, @protocol, @body_length, @serial,
         headers = mdata
@@ -235,11 +229,11 @@ module DBus
           @signature = struct[1]
         end
       end
-      pu.align(8)
+      pu.align_body
       if @body_length.positive? && @signature
         @params = pu.unmarshall(@signature, @body_length)
       end
-      [self, pu.idx]
+      [self, pu.consumed_size]
     end
 
     # Make a new exception from ex, mark it as being caused by this message

data/lib/dbus/object.rb

@@ -61,15 +61,7 @@ module DBus
           retdata = [*retdata]
 
           reply = Message.method_return(msg)
-          if iface.name == PROPERTY_INTERFACE && member_sym == :Get
-            # Use the specific property type instead of the generic variant
-            # returned by Get.
-            # TODO: GetAll and Set still missing
-            property = dbus_lookup_property(msg.params[0], msg.params[1])
-            rsigs = [property.type]
-          else
-            rsigs = meth.rets.map(&:type)
-          end
+          rsigs = meth.rets.map(&:type)
           rsigs.zip(retdata).each do |rsig, rdata|
             reply.add_param(rsig, rdata)
           end
@@ -345,7 +337,9 @@ module DBus
         if property.readable?
           ruby_name = property.ruby_name
           value = public_send(ruby_name)
-          [value]
+          # may raise, DBus.error or https://ruby-doc.com/core-3.1.0/TypeError.html
+          typed_value = Data.make_typed(property.type, value)
+          [typed_value]
         else
           raise DBus.error("org.freedesktop.DBus.Error.PropertyWriteOnly"),
                 "Property '#{interface_name}.#{property_name}' (on object '#{@path}') is not readable"
@@ -357,6 +351,9 @@ module DBus
 
         if property.writable?
           ruby_name_eq = "#{property.ruby_name}="
+          # TODO: declare dbus_method :Set to take :exact argument
+          # and type check it here before passing its :plain value
+          # to the implementation
           public_send(ruby_name_eq, value)
         else
           raise DBus.error("org.freedesktop.DBus.Error.PropertyReadOnly"),
@@ -385,7 +382,10 @@ module DBus
             # > array.
             # so we will silently omit properties that fail to read.
             # Get'ting them individually will send DBus.Error
-            p_hash[p_name.to_s] = public_send(ruby_name)
+            value = public_send(ruby_name)
+            # may raise, DBus.error or https://ruby-doc.com/core-3.1.0/TypeError.html
+            typed_value = Data.make_typed(property.type, value)
+            p_hash[p_name.to_s] = typed_value
           rescue StandardError
             DBus.logger.debug "Property '#{interface_name}.#{p_name}' (on object '#{@path}')" \
                               " has raised during GetAll, omitting it"

data/lib/dbus/object_path.rb

@@ -9,7 +9,8 @@
 # See the file "COPYING" for the exact licensing terms.
 
 module DBus
-  # A {::String} that validates at initialization time
+  # A {::String} that validates at initialization time.
+  # See also {DBus::Data::ObjectPath}
   # @see https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-marshaling-object-path
   class ObjectPath < String
     # @raise Error if not a valid object path