rslp 0.0.2 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3f495c04e7aa0fa38ebead86d3100b360d13de94d02ee3fc2f54bc41eb5b087c
-  data.tar.gz: 88a33d40ab0aa9e71048c73c765a250c60d559eda2619f483c1800bec48d4ba7
+  metadata.gz: 1c95a3256bfee540b035527983b2855d2ed8cfee989c766674259cc5649c928f
+  data.tar.gz: c78b46ee391b1dc210100c998a1e37ef1ab27e1dca89474aef4f48a2c0670612
 SHA512:
-  metadata.gz: bf1356f4e184640cf4b8f13198dca65469cf653228b1a9679dfce3da82ab0de9f236f81d85e01d3b11d3fd27e8dd472345a09aebf9111df207dc233c27acecb4
-  data.tar.gz: f67b5df2e8b5c6849b9fe826bee87b594bd4dcc351da1c640b0f3a637c106875e6160097f4e3a783abdfa9896df18b4813294dba6e94a81c914daebeb3d36f24
+  metadata.gz: cfbdfcea3945c0d0ee3625a0494e012b98ad85704089e254cafa2d9b9e3e85db19d93fb06ded3518e5c3d10073c43c1efcc1537b3ac4679867b3e035d881b0c3
+  data.tar.gz: 9e504c569a23cbfd41701beddf4670cf2441eea128ce9686c6ceb10bc7ebf61554a6641367ddebf490b8cd2c979ff45cb2d76b8f7d2961030f7d67c4e5564f5f

data/CHANGES.md

@@ -1,3 +1,18 @@
+## 0.1.1 - 22-Oct-2022
+* Added many more specs, along with instructions for how to install and
+  run an openslp container via Docker so that you can run the specs.
+* The :url parameter to the register method now raises an error unless
+  it is present. It was always required in practice, but now it's enforced.
+* Many documentation updates, notably that some methods may not actually
+  be implemented yet by the underlying OpenSLP library.
+
+## 0.1.0 - 19-Oct-2022
+* Updated the constructor, now uses keyword arguments.
+* Constructor now accepts a hostname, or a comma separate lists of hosts.
+* Added the set_app_property_file singleton method.
+* Changed the deregister method to return the url.
+* Minor refactoring of callback procs.
+
 ## 0.0.2 - 12-Oct-2022
 * Fixed the parse_service_url singleton method. The underlying SLPSrvURL
   struct is now a managed struct.

data/README.md

@@ -24,6 +24,17 @@ None that I'm aware of. Please report bugs on the project page at:
 
 https://github.com/djberg96/rslp
 
+## Running the Specs
+You will need an OpenSLP server running on localhost to run all of the specs.
+The easiest way to do that is to install docker and run:
+
+  `docker run -d -p 427:427/tcp -p 427:427/udp vcrhonek/openslp`
+
+Once you're done just terminate the container.
+
+## Notes
+Also see Novell's SLP implementation.
+
 ## Future Plans
 None at this time.
 

data/lib/rslp.rb

@@ -11,7 +11,7 @@ module OpenSLP
     extend OpenSLP::Functions
 
     # The version of the rslp library.
-    VERSION = '0.0.2'.freeze
+    VERSION = '0.1.1'.freeze
 
     # Internal error raised whenever an openslp function fails.
     class Error < StandardError; end
@@ -31,24 +31,32 @@ module OpenSLP
     #
     # The +async+ argument may be set to true or false and establishes whether
     # the underlying handle is set to handle asynchronous operations or not. By
-    # default this value is false.
+    # default this value is false, and may not be supported by your implementation.
+    #
+    # The +host+ argument, if present, will associate the Host/IP with the OpenSLP
+    # handle. This is the Hostname/IP address of the Service Agent / Directory Agent
+    # from # which service is requested. For multicast, use a comma separated list of
+    # Hostnames/IP addresses.
     #
     # If a block is given, then the object itself is yielded to the block, and
     # it is automatically closed at the end of the block.
     #
     # Examples:
     #
-    #   OpenSLP::SLP.new('en-us') do |slp|
+    #   # Block form
+    #   OpenSLP::SLP.new(lang: 'en-us', async: false, host: 'localhost') do |slp|
     #     # ... do stuff
     #   end
     #
-    #   slp = OpenSLP::SLP.new('en-us')
+    #   # Non-block form
+    #   slp = OpenSLP::SLP.new(lang: 'en-us')
     #   # Do stuff
     #   slp.close
     #
-    def initialize(lang = '', async = false)
+    def initialize(lang: '', async: false, host: nil)
       @lang = lang
       @async = async
+      @host = host
 
       ptr = FFI::MemoryPointer.new(:ulong)
 
@@ -57,6 +65,16 @@ module OpenSLP
 
       @handle = ptr.read_ulong
 
+      if @host
+        if @host.split(',').size > 1
+          result = SLPAssociateIFList(@handle, @host)
+          raise Error, "SLPAssociateIFList(): #{result}" if result != :SLP_OK
+        else
+          result = SLPAssociateIP(@handle, @host)
+          raise Error, "SLPAssociateIP(): #{result}" if result != :SLP_OK
+        end
+      end
+
       if block_given?
         begin
           yield self
@@ -86,11 +104,13 @@ module OpenSLP
     # Returns the url if successful.
     #
     def register(options = {})
+      url = options.fetch(:url){ raise ArgumentError, ":url must be provided" }
+
       options[:lifetime] ||= SLP_LIFETIME_DEFAULT
       options[:attributes] ||= ""
       options[:fresh] ||= true
 
-      options[:callback] ||= Proc.new{ |hslp, err, cookie| }
+      options[:callback] ||= Proc.new{ |_hslp, err, _cookie| }
 
       if options[:attributes] && options[:attributes] != ""
         attributes = options[:attributes].map{ |k,v| "(#{k}=#{v})" }.join(',')
@@ -103,7 +123,7 @@ module OpenSLP
 
         result = SLPReg(
           @handle,
-          options[:url],
+          url,
           options[:lifetime],
           nil,
           attributes,
@@ -117,14 +137,14 @@ module OpenSLP
         cookie.free unless cookie.null?
       end
 
-      options[:url]
+      url
     end
 
     # Deregisters the advertisement for +url+ in all scopes where the service
     # is registered and all language locales.
     #
     def deregister(url)
-      callback = Proc.new{ |hslp, err, cookie| }
+      callback = Proc.new{ |_hslp, err, _cookie| }
 
       begin
         cookie = FFI::MemoryPointer.new(:void)
@@ -134,7 +154,7 @@ module OpenSLP
         cookie.free unless cookie.null?
       end
 
-      true
+      url
     end
 
     # Deletes specified attributes from a registered service. The attributes
@@ -143,6 +163,10 @@ module OpenSLP
     #
     # Returns the list of deleted attributes if successful.
     #
+    # Note that this method may not be supported. In that case, the only way
+    # to alter a service's attributes is to deregister it then register it
+    # again without the undesired attributes.
+    #
     def delete_service_attributes(url, attributes)
       callback = Proc.new{ |hslp, err, cookie| }
 
@@ -188,12 +212,15 @@ module OpenSLP
     # form of an LDAP search filter. The default is an empty string, which
     # will gather all services of the requested type.
     #
+    # The result is an array of hashes, with the URL as the key and its
+    # remaining lifetime as the value.
+    #
     def find_services(type, scope = '', filter = '')
       arr = []
 
-      callback = Proc.new{ |hslp, url, life, err, cook|
+      callback = Proc.new{ |_hslp, url, lifetime, err, _cookie|
         if err == SLP_OK
-          arr << {url => life}
+          arr << {url => lifetime}
           true
         else
           false
@@ -225,7 +252,7 @@ module OpenSLP
     def find_service_types(auth = '*', scope = '')
       arr = []
 
-      callback = Proc.new{ |hslp, types, err, cookie|
+      callback = Proc.new{ |_hslp, types, err, _cookie|
         if err == SLP_OK
           arr << types
           true
@@ -237,7 +264,7 @@ module OpenSLP
       begin
         cookie = FFI::MemoryPointer.new(:void)
         result = SLPFindSrvTypes(@handle, auth, scope, callback, cookie)
-        raise Error, "SLPFindSrvs(): #{result}" if result != :SLP_OK
+        raise Error, "SLPFindSrvTypes(): #{result}" if result != :SLP_OK
       ensure
         cookie.free unless cookie.null?
       end
@@ -253,7 +280,7 @@ module OpenSLP
     def find_service_attributes(url, attrs = '', scope = '')
       arr = []
 
-      callback = Proc.new{ |hslp, attrlist, err, cookie|
+      callback = Proc.new{ |_hslp, attrlist, err, _cookie|
         if err == SLP_OK
           arr << attrlist
           true
@@ -350,5 +377,17 @@ module OpenSLP
 
       str
     end
+
+    # Set the application-specific configuration file full path name.
+    #
+    # The contents of this property file will override the contents of the
+    # default or global UA configuration file (usually /etc/slp.conf or
+    # C:\windows\slp.conf).
+    #
+    def self.set_app_property_file(path)
+      result = SLPSetAppPropertyFile(string)
+      raise Error, "SLPSetAppPropertyFile(): #{result}" if result != :SLP_OK
+      path
+    end
   end
 end

data/lib/slp/functions.rb

@@ -49,10 +49,12 @@ module OpenSLP
     callback :SLPAttrCallback, [:handle, :string, :int, :pointer], :bool
     callback :SLPRegReportCallback, [:handle, :int, :pointer], :void
 
+    attach_function :SLPAssociateIFList, [:handle, :string], SLPError
+    attach_function :SLPAssociateIP, [:handle, :string], SLPError
     attach_function :SLPClose, [:handle], :void
-    attach_function :SLPEscape, [:string, :pointer, :bool], SLPError
     attach_function :SLPDelAttrs, [:handle, :string, :string, :SLPRegReportCallback, :pointer], SLPError
     attach_function :SLPDereg, [:handle, :string, :SLPRegReportCallback, :pointer], SLPError
+    attach_function :SLPEscape, [:string, :pointer, :bool], SLPError
 
     attach_function :SLPFindAttrs,
       [:handle, :string, :string, :string, :SLPAttrCallback, :pointer], SLPError
@@ -74,6 +76,7 @@ module OpenSLP
     attach_function :SLPReg,
       [:handle, :string, :ushort, :string, :string, :bool, :SLPRegReportCallback, :pointer], SLPError
 
+    attach_function :SLPSetAppPropertyFile, [:string], SLPError
     attach_function :SLPSetProperty, [:string, :string], :void
     attach_function :SLPUnescape, [:string, :pointer, :bool], SLPError
   end

data/rslp.gemspec

@@ -3,7 +3,7 @@ require 'rbconfig'
 
 Gem::Specification.new do |spec|
   spec.name       = 'rslp'
-  spec.version    = '0.0.2'
+  spec.version    = '0.1.1'
   spec.license    = 'Apache-2.0'
   spec.author     = 'Daniel J. Berger'
   spec.email      = 'djberg96@gmail.com'
@@ -31,7 +31,7 @@ Gem::Specification.new do |spec|
   }
 
   spec.description = <<-EOF
-    The rslp library is an FFI interface for the OpenSLP service
-    location protocol library.
+    The rslp library is an FFI interface for the OpenSLP service location
+    protocol library. See http://www.openslp.org for more information.
   EOF
 end

data/spec/rslp_spec.rb

@@ -1,20 +1,26 @@
-########################################################################
+##############################################################################
 # rslp_spec.rb
 #
-# Test suite for the rslp library.
-########################################################################
+# Test suite for the rslp library. Note that these specs assume that you
+# have an OpenSLP server running on localhost. If not, install Docker and
+# run the following command:
+#
+#   docker run -d -p 427:427/tcp -p 427:427/udp vcrhonek/openslp
+#
+# Once complete, simply stop the docker container and delete the image.
+##############################################################################
 require 'rspec'
 require 'rslp'
 
 RSpec.describe OpenSLP::SLP do
   before do
     @lang = 'en-us'
-    @slp = described_class.new(@lang, false)
+    @slp = described_class.new(lang: @lang, async: false, host: 'localhost')
   end
 
   context "version" do
     example "version is set to the expected value" do
-      expect(described_class::VERSION).to eq('0.0.2')
+      expect(described_class::VERSION).to eq('0.1.1')
     end
   end
 
@@ -109,6 +115,144 @@ RSpec.describe OpenSLP::SLP do
         expect(described_class.unescape_reserved("\\2Ctag-example\\2C")).to eq(expected)
       end
     end
+
+    context "set_app_property_file" do
+      example "defines a set_app_property_file method" do
+        expect(described_class).to respond_to(:set_app_property_file)
+      end
+    end
+  end
+
+  describe "instance methods" do
+    let(:service){ "service:ntp" }
+    let(:url){ "#{service}://time.windows.com" }
+    let(:attributes){ {"foo" => "hello", "bar" => "world"} }
+
+    context "close" do
+      example "has a close method that returns the expected value" do
+        expect(@slp).to respond_to(:close)
+        expect(@slp.close).to be_nil
+      end
+
+      example "calling close multiple times has no effect" do
+        expect(@slp.close).to be_nil
+        expect(@slp.close).to be_nil
+      end
+    end
+
+    context "find_scopes" do
+      example "has a find_scopes method" do
+        expect(@slp).to respond_to(:find_scopes)
+      end
+
+      example "the find_scopes method returns the expected value" do
+        expect(@slp.find_scopes).to eq(['DEFAULT'])
+      end
+    end
+
+    context "find_services" do
+      before do
+        sleep 1
+        @slp.register(url: url, attributes: attributes)
+      end
+
+      example "has a find_services method" do
+        expect(@slp).to respond_to(:find_services)
+      end
+
+      example "the find_services method returns the expected types" do
+        results = @slp.find_services(service)
+        expect(results).to be_kind_of(Array)
+        expect(results.first).to be_kind_of(Hash)
+      end
+
+      example "the find_services method returns the expected values" do
+        results = @slp.find_services(service)
+        expect(results.first.keys).to include(url)
+        expect(results.first.values.first).to be_kind_of(Numeric)
+      end
+
+      example "the find_services method with valid scope returns the expected values" do
+        results = @slp.find_services(service, 'DEFAULT')
+        expect(results.first.keys).to include(url)
+        expect(results.first.values.first).to be_kind_of(Numeric)
+      end
+
+=begin
+      # These specs appear to cause a segfault in the OpenSLP daemon.
+      example "the find_services method with invalid scope returns an empty value" do
+        results = @slp.find_services(service, 'bogus')
+        expect(results).to be_empty
+      end
+
+      example "the find_services method with filter on existing attribute returns the expected values" do
+        results = @slp.find_services(service, '', "(foo=hello)")
+        expect(results).to eq(1)
+      end
+=end
+    end
+
+    context "find_service_types" do
+      example "has a find_services method" do
+        expect(@slp).to respond_to(:find_service_types)
+      end
+
+      example "the find_service_types method returns the expected results" do
+        results = @slp.find_service_types
+        expect(results).to be_kind_of(Array)
+        expect(results.first).to eq(service)
+      end
+    end
+
+    context "registration" do
+      example "registers a service successfully if url is provided" do
+        expect(@slp.register(url: url)).to eq(url)
+      end
+
+      example "doesn't matter if service is already registered" do
+        expect(@slp.register(url: url)).to eq(url)
+      end
+
+      example "accepts hash attributes option and registers them as expected" do
+        expect(@slp.register(url: url, attributes: attributes)).to eq(url)
+      end
+
+      example "raises an error if the :url option is not provided" do
+        expect{ @slp.register }.to raise_error(ArgumentError, ":url must be provided")
+      end
+
+      example "registers a service successfully with a lifetime value" do
+        expect(@slp.register(url: url, lifetime: OpenSLP::SLP::SLP_LIFETIME_MAXIMUM)).to eq(url)
+        expect(@slp.find_services(service).first.values.first).to be_within(1).of(OpenSLP::SLP::SLP_LIFETIME_MAXIMUM)
+      end
+    end
+
+    context "deregistration" do
+      example "deregisters a service successfully if it exists" do
+        expect(@slp.deregister(url)).to eq(url)
+        expect(@slp.find_services(url)).to be_empty
+      end
+
+      example "fails to deregister a service successfully if it does not exist" do
+        expect{ @slp.deregister('bogus') }.to raise_error(OpenSLP::SLP::Error)
+      end
+    end
+
+    context "find service attributes" do
+      before do
+        @slp.register(url: url, attributes: attributes)
+      end
+
+      example "successfully finds service attribute when they exist" do
+        expect(@slp.find_service_attributes(url)).to eq(["(foo=hello),(bar=world)"])
+        expect(@slp.find_service_attributes(url, "foo")).to eq(["(foo=hello)"])
+        expect(@slp.find_service_attributes(url, "foo,bar")).to eq(["(foo=hello),(bar=world)"])
+      end
+
+      example "returns an empty array if the service attribute does not exist" do
+        expect(@slp.find_service_attributes(url, "bogus")).to eq([])
+      end
+    end
   end
 
   after do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rslp
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.1.1
 platform: ruby
 authors:
 - Daniel J. Berger
@@ -35,7 +35,7 @@ cert_chain:
   ORVCZpRuCPpmC8qmqxUnARDArzucjaclkxjLWvCVHeFa9UP7K3Nl9oTjJNv+7/jM
   WZs4eecIcUc4tKdHxcAJ0MO/Dkqq7hGaiHpwKY76wQ1+8xAh
   -----END CERTIFICATE-----
-date: 2022-10-13 00:00:00.000000000 Z
+date: 2022-10-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi
@@ -80,8 +80,8 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '3.9'
 description: |2
-      The rslp library is an FFI interface for the OpenSLP service
-      location protocol library.
+      The rslp library is an FFI interface for the OpenSLP service location
+      protocol library. See http://www.openslp.org for more information.
 email: djberg96@gmail.com
 executables: []
 extensions: []
@@ -131,7 +131,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.16
+rubygems_version: 3.3.7
 signing_key:
 specification_version: 4
 summary: Interface for the OpenSLP library