dnet-ffi 0.1.3

data/lib/dnet/arp.rb

@@ -0,0 +1,168 @@
+# Address resolution Protocol
+
+module Dnet
+  module Arp
+    # ARP header
+    # 
+    #   field :hrd, :uint16, :desc => 'format of hardware address'
+    #   field :pro, :uint16, :desc => 'format of protocol address'
+    #   field :hln, :uint16, :desc => 'length of hw address (ETH_ADDR_LEN)'
+    #   field :pln, :uint16, :desc => 'length of proto address (IP_ADDR_LEN)'
+    #   field :op,  :uint16, :desc => 'operation'
+    class Hdr < ::FFI::Struct
+      include ::FFI::DRY::StructHelper
+      include ::Dnet::NetEndianHelper
+      
+      dsl_layout do
+        field :hrd, :uint16, :desc => 'format of hardware address'
+        field :pro, :uint16, :desc => 'format of protocol address'
+        field :hln, :uint16, :desc => 'length of hw address (ETH_ADDR_LEN)'
+        field :pln, :uint16, :desc => 'length of proto address (IP_ADDR_LEN)'
+        field :op,  :uint16, :desc => 'operation'
+      end
+
+      # ARP operations
+      module Op
+        ::Dnet.constants.grep(/^(ARP_OP_([A-Z][A-Z0-9_]+))$/) do
+          self.const_set $2, ::Dnet.const_get($1)
+        end
+
+        module_function
+        def list
+          @@list ||= constants.inject({}){|h,c| h.merge! c => const_get(c) }
+        end
+      end # Op
+    end # Hdr
+
+    # Ethernet/IP ARP message
+    #
+    #   array :sha, [:uint8, ETH_ADDR_LEN], :desc => 'sender hardware address'
+    #   array :spa, [:uint8, IP_ADDR_LEN],  :desc => 'sender protocol address'
+    #   array :tha, [:uint8, ETH_ADDR_LEN], :desc => 'target hardware address'
+    #   array :tpa, [:uint8, IP_ADDR_LEN],  :desc => 'target protocol address'
+    #
+    class Ethip < ::FFI::Struct
+      include ::FFI::DRY::StructHelper
+      include ::Dnet::NetEndianHelper
+
+      dsl_layout do
+        array :sha, [:uint8, ETH_ADDR_LEN], :desc => 'sender hardware address'
+        array :spa, [:uint8, IP_ADDR_LEN],  :desc => 'sender protocol address'
+        array :tha, [:uint8, ETH_ADDR_LEN], :desc => 'target hardware address'
+        array :tpa, [:uint8, IP_ADDR_LEN],  :desc => 'target protocol address'
+      end
+
+    end # Ethip
+
+    
+    # FFI mapping to libdnet's "arp_entry" struct.
+    #
+    # dnet(3)'s ARP cache entries are described by the following C structure:
+    # 
+    #   struct  :pa,  ::Dnet::Addr, :desc => 'protocol address'
+    #   struct  :ha,  ::Dnet::Addr, :desc => 'hardware address'
+    #
+    class Entry < ::FFI::Struct
+      include ::FFI::DRY::StructHelper
+
+      dsl_layout do
+        struct  :pa,  ::Dnet::Addr, :desc => 'protocol address'
+        struct  :ha,  ::Dnet::Addr, :desc => 'hardware address'
+      end
+
+    end # Entry
+
+    # A handle for accessing the kernel arp(4) cache. This does not require
+    # root privileges.
+    class Handle < LoopableHandle
+
+      # Obtains a handle to access the kernel arp(4) cache. Uses dnet(3)'s 
+      # arp_open() function under the hood.
+      def initialize
+        if (@handle = ::Dnet.arp_open).address == 0
+          raise H_ERR.new("unable to open arp handle")
+        end
+        _handle_opened!
+      end
+      
+      # Closes the handle. Uses dnet(3)'s arp_close() function under the hood.
+      def close
+        _do_if_open { _handle_closed!; ::Dnet.arp_close(@handle) }
+      end
+
+      # Iterates over the kernel arp cache, yielding each entry (cast as an
+      # Entry) to a block. Uses dnet(3)'s arp_loop() function under the hood.
+      def loop &block
+        _loop ::Dnet, :arp_loop, Entry, &block
+      end
+
+      # Retrieves the ARP entry for the protocol address specified by 'addr'
+      # (supplied as a String). Uses dnet(3)'s addr_aton() function to parse
+      # 'addr' and arp_get() to retrieve a result, which is cast as an Entry 
+      # instance.
+      def get(addr)
+        _check_open!
+        ae = Entry.new
+        return ae if ae.pa.set_string(addr) and 
+                     ::Dnet.arp_get(@handle, ae) == 0
+      end
+
+      # Adds a new ARP entry specified as an Entry object. Uses dnet(3)'s 
+      # arp_add() function under the hood.
+      def add(entry)
+        _check_open!
+        ::Dnet.arp_add(@handle, entry)
+      end
+
+      # Deletes the ARP entry for the protocol address specified by
+      # 'entry' supplied as an Entry object. Uses dnet(3)'s arp_delete()
+      # function under the hood.
+      def delete(entry)
+        _check_open!
+        ::Dnet.arp_delete(@handle, entry)
+      end
+
+    end # Handle
+
+    # #define arp_pack_hdr_ethip(hdr, op, sha, spa, tha, tpa) do { \
+    #   struct arp_hdr *pack_arp_p = (struct arp_hdr *)(hdr); \
+    #   struct arp_ethip *pack_ethip_p = (struct arp_ethip *) \
+    #     ((uint8_t *)(hdr) + ARP_HDR_LEN); \
+    #   pack_arp_p->ar_hrd = htons(ARP_HRD_ETH); \
+    #   pack_arp_p->ar_pro = htons(ARP_PRO_IP); \
+    #   pack_arp_p->ar_hln = ETH_ADDR_LEN; \
+    #   pack_arp_p->ar_pln = IP_ADDR_LEN; \
+    #   pack_arp_p->ar_op = htons(op); \
+    #   memmove(pack_ethip_p->ar_sha, &(sha), ETH_ADDR_LEN); \
+    #   memmove(pack_ethip_p->ar_spa, &(spa), IP_ADDR_LEN); \
+    #   memmove(pack_ethip_p->ar_tha, &(tha), ETH_ADDR_LEN); \
+    #   memmove(pack_ethip_p->ar_tpa, &(tpa), IP_ADDR_LEN); \
+    # } while (0)
+
+    def self.open(*args)
+      Handle.open(*args) {|*y| yield(*y) if block_given? }
+    end
+
+    def self.each_entry(*args)
+      Handle.each_entry(*args) {|*y| yield(*y) }
+    end
+
+    def self.entries(*args)
+      Handle.entries(*args)
+    end
+
+  end # Arp
+
+  # This is just an alias for Arp::Handle
+  ArpHandle = Arp::Handle
+
+  typedef :pointer, :arp_t
+  callback :arp_handler, [Arp::Entry, :ulong], :int
+  attach_function :arp_open, [], :arp_t
+  attach_function :arp_add, [:arp_t, Arp::Entry], :int
+  attach_function :arp_delete, [:arp_t, Arp::Entry], :int
+  attach_function :arp_get, [:arp_t, Arp::Entry], :int
+  attach_function :arp_loop, [:arp_t, :arp_handler, :ulong], :int
+  attach_function :arp_close, [:arp_t], :arp_t
+
+end

data/lib/dnet/blob.rb

@@ -0,0 +1,246 @@
+
+## blob is dnet(3)'s name for binary buffers
+
+module Dnet
+
+  # FFI mapping to dnet(3)'s "blob_t" binary buffer struct.
+  #
+  #   field :base, :pointer, :desc => 'start of data'
+  #   field :off,  :pointer, :desc => 'offset into data'
+  #   field :end,  :pointer, :desc => 'end of data'
+  #   field :size, :pointer, :desc => 'size of allocation'
+  #
+  class Blob < FFI::ManagedStruct
+    include ::FFI::DRY::StructHelper
+    include HandleHelpers
+
+    dsl_layout do
+      field :base, :pointer, :desc => 'start of data'
+      field :off,  :int,     :desc => 'offset into data'
+      field :end,  :int,     :desc => 'end of data'
+      field :size, :int,     :desc => 'size of allocation'
+    end
+
+    # Initializes a new Blob using dnet(3)'s blob_new under the hood.
+    #
+    # blob_new is used to allocate a new dynamic binary buffer, returning
+    # NULL on failure.
+    #
+    # Below is the dnet(3) C function definition:
+    #
+    #    blob_t * blob_new(void);
+    #
+    def initialize
+      super(::Dnet.blob_new())
+      _handle_opened!
+    end
+
+    # Called by the garbage collector for ::FFI:ManagedStruct objects
+    def self.release(blob)
+      blob.release()
+    end
+
+    def base_ptr
+      self[:base]
+    end
+
+    def curr_ptr
+      safe[:base] + self[:off]
+    end
+
+    def end_ptr
+      self[:base] + self[:end]
+    end
+
+    # This method calls dnet(3)'s blob_free behind the scenes. It should 
+    # automatically get run by the garbage collector when a blob is no longer
+    # referenced.
+    # 
+    # blob_free deallocates the memory associated with blob b and returns NULL.
+    def release
+      _do_if_open { _handle_closed! ; ::Dnet.blob_free(self) }
+    end
+
+    # blob_pack converts and writes, and blob_unpack() reads and converts data
+    # in blob b according to the given format fmt as described below, returning
+    # 0 on success, and -1 on failure.
+    #
+    # The format string is composed of zero or more directives: ordinary 
+    # characters (not % ), which are copied to / read from the blob, and 
+    # conversion specifications, each of which results in reading / writing 
+    # zero or more subsequent arguments.
+    #
+    # Each conversion specification is introduced by the character %, and may
+    # be prefixed by length specifier. The arguments must correspond properly
+    # (after type promotion) with the length and conversion specifiers.
+    #
+    # The length specifier is either a a decimal digit string specifying the
+    # length of the following argument, or the literal character * indicating
+    # that the length should be read from an integer argument for the argument
+    # following it.
+    #
+    # The conversion specifiers and their meanings are:
+    #
+    #     D       An unsigned 32-bit integer in network byte order.
+    #     H       An unsigned 16-bit integer in network byte order.
+    #     b       A binary buffer (length specifier required).
+    #     c       An unsigned character.
+    #     d       An unsigned 32-bit integer in host byte order.
+    #     h       An unsigned 16-bit integer in host byte order.
+    #     s       A C-style null-terminated string, whose maximum length must be
+    #             specified when unpacking.
+    #
+    # Custom conversion routines and their specifiers may be registered via
+    # blob_register_pack, currently undocumented. 
+    #
+    # TODO add ruby wrapper for blob_register_pack.
+    #
+    # XXX want to wrap varargs FFI for easier type casting?
+    def pack(sfmt, *args)
+      _check_open!
+      (fmt = ::FFI::MemoryPointer.from_string(sfmt)).autorelease=true
+      ::Dnet.blob_pack(self, fmt, *args)
+    end
+
+    # Uses dnet(3)s 'blob_unpack' under the hood.  See pack() for more 
+    # information.
+    #
+    # XXX TODO - want to wrap varargs FFI for easier type casting?
+    def unpack(sfmt, *args)
+      _check_open!
+      (fmt = ::FFI::MemoryPointer.from_string(sfmt)).autorelease=true
+      ::Dnet.blob_unpack(self, fmt, *args)
+    end
+
+    # Writes the data supplied from a string or pointer to the blob at the 
+    # current offset. If a pointer is supplied, a size must accompany it.
+    # Uses dnet(3)'s "blob_write" under the hood.
+    def write(buf, bsz=nil)
+      _check_open!
+      ptr, psz = ::Dnet::Util.derive_pointer(buf, bsz)
+      ::Dnet.blob_write(self, ptr, psz)
+    end
+
+    # Reads 'len' bytes out of the blob from the current offset. If len is nil
+    # (the default) then all remaining bytes are read. Moves the offset 
+    # accordingly. This method uses dnet(3)'s "blob_read" under the hood.
+    def read(len=nil)
+      _check_open!
+      len ||= self[:end] - self[:off]
+      (buf = ::FFI::MemoryPointer.new("\x00", len)).autorelease = true
+      if rlen=::Dnet.blob_read(self, buf, len)
+        return buf.read_string_length(rlen)
+      else
+        nil
+      end
+    end
+
+    # Returns the entirety of the blob from beginning to end.
+    # Note, this will also move the offset to the end of the buffer.
+    def string()
+      _check_open!
+      rewind()
+      read()
+    end
+
+    # rewinds the blob buffer offset to the beginning
+    def rewind
+      _check_open!
+      ::Dnet.blob_seek(self, 0, 0)
+    end
+
+    # sets the blob buffer offset to p. returns -1 on failure
+    def pos=(p)
+      _check_open!
+      ::Dnet.blob_seek(self, p.to_i, 0)
+    end
+
+    # base pointer - start of data
+    def base; 
+      _check_open!
+      self[:base]
+    end
+
+    # size of allocated data - aka self[:size]
+    def blob_size; 
+      _check_open!
+      self[:size]
+    end
+
+    # returns the current position offset of the blob buffer - aka self[:off]
+    def pos
+      _check_open!
+      self[:off]
+    end
+
+    # returns the end of the blob buffer in use - aka self[:end]
+    def blob_end
+      _check_open!
+      self[:end]
+    end
+
+    # This method calls dnet(3)'s blob_seek under the hood.
+    #
+    # blob_seek repositions the offset within blob b to off, according to the
+    # directive whence (see lseek(2) for details), returning the new absolute
+    # offset, or -1 on failure.
+    def seek(off, whence=0)
+      _check_open!
+      ::Dnet.blob_seek(self, off.to_i, whence.to_i)
+    end
+
+    # Uses dnet(3)'s "blob_index" under the hood. An additional 'rewind' 
+    # argument was added which can be used to force a rewind before searching.
+    # The default value for "rewind" is "false". nil is returned on a failed
+    # search.
+    def index(bstr, rewind=false)
+      _check_open!
+      self.rewind() if rewind
+      (buf = ::FFI::MemoryPointer.from_string(bstr)).autorelease=true
+      if (i=::Dnet.blob_index(self, buf, bstr.size)) > -1
+        return i
+      else
+        return nil
+      end
+    end
+
+    # Uses dnet(3)'s "blob_rindex" under the hood. An additional 'rewind' 
+    # argument was added which can be used to force a rewind before searching.
+    # The default value for "rewind" is "false". nil is returned on a failed
+    # search.
+    def rindex(buf, rewind=false)
+      _check_open!
+      self.rewind() if rewind
+      (buf = ::FFI::MemoryPointer.from_string(bstr)).autorelease=true
+      if (i=::Dnet.blob_rindex(self, buf, bstr.size)) > -1
+        return i
+      else
+        return nil
+      end
+    end
+
+    # Prints a hexdump on standard output using dnet(3)'s "blob_print" under 
+    # the hood.  Can optionally rewind the blob before dumping using the 
+    # 'rewind' argument (default: rewind=true).
+    #
+    # NOTE: len does not appear to do anything at all for blob_print
+    def print_dump(rewind=true, len=nil)
+      _check_open!
+      self.rewind if rewind==true
+      len ||= self[:end] - self[:off]
+      Dnet.blob_print(self, "hexl", len.to_i)
+    end
+  end
+
+  attach_function :blob_new,    [], :pointer
+  attach_function :blob_read,   [Blob, :pointer, :int], :int
+  attach_function :blob_write,  [Blob, :pointer, :int], :int
+  attach_function :blob_seek,   [Blob, :int, :int], :int
+  attach_function :blob_index,  [Blob, :pointer, :int], :int
+  attach_function :blob_rindex, [Blob, :string, :int], :int
+  attach_function :blob_pack,   [Blob, :string, :varargs], :int
+  attach_function :blob_unpack, [Blob, :string, :varargs], :int
+  attach_function :blob_print,  [Blob, :string, :int], :int
+  attach_function :blob_free,   [Blob], :pointer
+end
+

data/lib/dnet/bsd.rb

@@ -0,0 +1,123 @@
+# Here's where various BSD sockets typedefs and structures go
+# ... good to have around
+
+require 'socket'
+
+module Dnet
+  typedef :uint8, :sa_family_t
+  typedef :uint32, :in_addr_t
+  typedef :uint16, :in_port_t
+
+  # contains AF_* constants culled from Ruby's ::Socket
+  module AF
+    include ::FFI::DRY::ConstMap
+    slurp_constants(::Socket, "AF_")
+    def self.list; @@list ||= super() ; end
+  end
+
+  # Common superclass for all sockaddr struct classes
+  #
+  class SockAddrFamily < ::FFI::Struct
+    include ::FFI::DRY::StructHelper
+    
+    # returns an address family name for the :family struct member value
+    def lookup_family
+      ::Dnet::AF[ self[:family] ]
+    end
+  end
+
+  # generic sockaddr, always good to have around
+  #
+  #   field :len,    :uint8,        :desc => 'total length of struct'
+  #   field :family, :sa_family_t,  :desc => 'address family (AF_*)'
+  #   field :data,   :char,         :desc => 'variable length bound by :len'
+  #
+  class SockAddr < SockAddrFamily
+    dsl_layout do
+      field :len,    :uint8,        :desc => 'total length of struct'
+      field :family, :sa_family_t,  :desc => 'address family (AF_*)'
+      field :data,   :char,         :desc => 'variable length bound by :len'
+    end
+  end
+
+
+  # Used to represent a 32-bit IPv4 address in a sock_addr_in structure
+  # 
+  #   field :in_addr,  :in_addr_t, :desc => 'inet address' }
+  #
+  class InAddr < ::FFI::Struct
+    include ::FFI::DRY::StructHelper
+    dsl_layout { field :in_addr,  :in_addr_t, :desc => 'inet address' }
+  end
+
+  # sockaddr inet, always good to have around
+  #
+  #   field :len,    :uint8,        :desc => 'length of structure (16)'
+  #   field :family, :sa_family_t,  :desc => 'address family (AF_INET)'
+  #   field :port,   :in_port_t,    :desc => '16-bit TCP or UDP port number'
+  #   field :addr,   :in_addr_t,    :desc => '32-bit IPv4 address'
+  #   field :_sa_zero, [:uint8,8],  :desc => 'unused'
+  #
+  class SockAddrIn < SockAddrFamily
+    dsl_layout do
+      field :len,    :uint8,        :desc => 'length of structure (16)'
+      field :family, :sa_family_t,  :desc => 'address family (AF_INET)'
+      field :port,   :in_port_t,    :desc => '16-bit TCP or UDP port number'
+      field :addr,   :in_addr_t,    :desc => '32-bit IPv4 address'
+      array :_sa_zero, [:uint8,8],  :desc => 'unused'
+    end
+  end
+
+  # Used to represent an IPv6 address in a sock_addr_in6 structure
+  #
+  #   field :s6_addr, [:uint, 16], :desc => 'IPv6 address'
+  #
+  class In6Addr < ::FFI::Struct
+    include ::FFI::DRY::StructHelper
+    dsl_layout { array :s6_addr, [:uint8, 16], :desc => 'IPv6 address' }
+  end
+
+  # IPv6 socket address
+  #
+  #   field :len,      :uint8,       :desc => 'length of structure(24)'
+  #   field :family,   :sa_family_t, :desc => 'address family (AF_INET6)'
+  #   field :port,     :in_port_t,   :desc => 'transport layer port'
+  #   field :flowinfo, :uint32,      :desc => 'priority & flow label'
+  #   struct :addr,     In6Addr      :desc => 'IPv6 address'
+  #
+  class SockAddrIn6 < SockAddrFamily
+    dsl_layout do
+      field :len,      :uint8,       :desc => 'length of structure(24)'
+      field :family,   :sa_family_t, :desc => 'address family (AF_INET6)'
+      field :port,     :in_port_t,   :desc => 'transport layer port'
+      field :flowinfo, :uint32,      :desc => 'priority & flow label'
+      struct :addr,     In6Addr,     :desc => 'IPv6 address'
+    end
+  end
+
+
+  # data-link socket address
+  #
+  #   field :len,       :uint8,   :desc => 'length of structure(variable)'
+  #   field :family,:sa_family_t, :desc => 'address family (AF_LINK)'
+  #   field :sdl_index, :uint16,  :desc => 'system assigned index, if > 0'
+  #   field :dltype,    :uint8,   :desc => 'IFT_ETHER, etc. from net/if_types.h'
+  #   field :nlen,      :uint8,   :desc => 'name length, from :_data'
+  #   field :alen,      :uint8,   :desc => 'link-layer addres-length'
+  #   field :slen,      :uint8,   :desc => 'link-layer selector length'
+  #   field :_data,     :char,    :desc => 'minimum work area=12, can be larger'
+  #
+  class SockAddrDl < SockAddrFamily
+    dsl_layout do
+      field :len,       :uint8,   :desc => 'length of structure(variable)'
+      field :family, :sa_family_t, :desc => 'address family (AF_LINK)'
+      field :sdl_index, :uint16,  :desc => 'system assigned index, if > 0'
+      field :dltype,    :uint8,   :desc => 'IFT_ETHER, etc. from net/if_types.h'
+      field :nlen,      :uint8,   :desc => 'name length, from :_data'
+      field :alen,      :uint8,   :desc => 'link-layer addres-length'
+      field :slen,      :uint8,   :desc => 'link-layer selector length'
+      field :_data,     :char,    :desc => 'minimum work area=12, can be larger'
+    end
+  end
+
+end