easy_upnp 1.1.2 → 1.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a269aa109f5d07c0b8ddfd218316a42073704783
-  data.tar.gz: ada5f6562fa9b61599348acd514ddca7c5eb4204
+  metadata.gz: 77ca5dc016b9e9587ab894416d38ec9ed66f22dd
+  data.tar.gz: 2990a6748c83422a25b915cf6bd62d6f62f93507
 SHA512:
-  metadata.gz: fbe22254daada0ff4c6bfc9fe3ff8f4a0a61b62345bc3d959fff778e4df452d53c4980495a5a26eff8506d819ab03b9814f0f7503cd0360ae542948a6ae7873e
-  data.tar.gz: bb77cd15ac6cad082c69986b19cb9d392e322e8405ee9f111eb8744677313565b5832dbeaf1e509ce363ee5490ece40a01a8cb51b2a547316072a535e77dc5d2
+  metadata.gz: c449b3c3f8b66bb55d6ba755b1e684b2388ce0be5e663b9594ba7c9ecd255c8b7fa0da5d293c80a8d103a63bdee6b203b773d5edbe00b7fcbce782da3c50fd3e
+  data.tar.gz: ea9a9a024ea173a111915249ffb3a4c8a331b0c6f852c69212cd8c9369572e527a4d02465e66c9325788588078180da4b90088e3de584f96c0ab152831197116

data/README.md

@@ -132,3 +132,101 @@ validator = client.arg_validator(:SetVolume, :Channel)
 validator.allowed_values
 #=> ["Master"]
 ```
+
+## Events
+
+easy_upnp allows you to subscribe to events. UPnP events are supported by registering HTTP callbacks with services. You can read more about the specifics in Section 4 of the [UPnP Device Architecture document](http://upnp.org/specs/arch/UPnP-arch-DeviceArchitecture-v1.1.pdf). Using this you could, for example, receive events when the volume or mute state changes on your UPnP-enabled TV. You might see something like this HTTP request, for example:
+
+```
+NOTIFY / HTTP/1.1
+Host: 192.168.1.100:8888
+Date: Sun, 17 Apr 2016 07:40:01 GMT
+User-Agent: UPnP/1.0
+Content-Type: text/xml; charset="utf-8"
+Content-Length: 479
+NT: upnp:event
+NTS: upnp:propchange
+SID: uuid:9742fed0-046f-11e6-8000-fcf1524b4f9c
+SEQ: 0
+
+<?xml version="1.0"?><e:propertyset xmlns:e="urn:schemas-upnp-org:event-1-0"><e:property><LastChange>&lt;Event xmlns=&quot;urn:schemas-upnp-org:metadata-1-0/RCS/&quot;&gt;
+  &lt;InstanceID val=&quot;0&quot;&gt;
+    &lt;PresetNameList val=&quot;FactoryDefaults&quot;/&gt;
+    &lt;Mute val=&quot;0&quot; channel=&quot;Master&quot;/&gt;
+    &lt;Volume val=&quot;34&quot; channel=&quot;Master&quot;/&gt;
+  &lt;/InstanceID&gt;
+&lt;/Event&gt;
+</LastChange></e:property></e:propertyset>
+```
+
+There are two ways you can subscribe to events with easy_upnp:
+
+1. Registering a custom HTTP endpoint.
+2. Providing a callback `lambda` or `Proc` which is called each time an event is fired.
+
+In the case of (2), easy_upnp behind the scenes starts a WEBrick HTTP server, which calls the provided callback whenever it receives an HTTP `NOTIFY` request. 
+
+Because event subscriptions expire, easy_upnp starts a background thread to renew the subscription on an interval.
+
+#### Calling URLs
+
+To add a URL to be called on events:
+
+```ruby
+# Registers the provided URL with the service. If everything works appropriately, this
+# URL will be called with HTTP NOTIFY requests from the service.
+manager = service.add_event_callback('http://myserver/path/to/callback')
+
+# The object that's returned allows you to manage the event subscription. To 
+# cancel the subscription, for example:
+manager.unsubscribe
+
+# You can also start the subscription after unsubscribing:
+manager.subscribe
+
+# Or get the subscription identifier:
+manager.subscription_id
+#=> "uuid:6ef254f0-04d1-11e6-8000-fcf1524b4f9c"
+```
+
+You can also construct a manager that attempts to manage an existing subscription:
+
+```ruby
+manager = service.add_event_callback('http://myserver/path/to/callback') do |c|
+  c.existing_sid = 'uuid:6ef254f0-04d1-11e6-8000-fcf1524b4f9c'
+end
+```
+
+#### Calling ruby code
+
+If you don't want to have to set up an HTTP endpoint to listen to events, you can have easy_upnp do it for you. The `on_event` starts an internal HTTP server on an ephemeral port behind the scenes and triggers the provided callback each time a request is recieved. 
+
+```ruby
+# Parse and print the XML body of the request
+callback = ->(request) { puts Nokogiri::XML(request.body).to_xml }
+manager = service.on_event(callback)
+
+# End the subscription and shut down the internal HTTP server
+manager.unsubscribe
+
+# This will start a new HTTP server and start a new subscription
+manager.subscribe
+```
+
+While the default configurations are probably fine for most situations, you can configure both the internal HTTP server and the subscription manager when you call `on_event` by passing a configuration block:
+
+```ruby
+manager = service.on_event(callback) do |c|
+  c.configure_http_listener do |l|
+    l.listen_port = 8888
+    l.bind_address = '192.168.1.100'
+  end
+  
+  c.configure_subscription_manager do |m|
+    m.requested_timeout = 1800
+    m.resubscription_interval_buffer = 60
+    m.existing_sid = 'uuid:6ef254f0-04d1-11e6-8000-fcf1524b4f9c'
+    m.log_level = Logger::INFO
+  end
+end
+```

data/lib/easy_upnp/control_point/client_wrapper.rb

@@ -1,11 +1,13 @@
+require_relative '../options_base'
+
 module EasyUpnp
   class ClientWrapper
     def initialize(endpoint,
                    urn,
-                   call_options:,
-                   advanced_typecasting:,
-                   log_enabled:,
-                   log_level:)
+                   call_options,
+                   advanced_typecasting,
+                   log_enabled,
+                   log_level)
 
       # For some reason was not able to pass these options in the config block
       # in Savon 2.11
@@ -40,9 +42,10 @@ module EasyUpnp
               :'xmlns:u' => @urn
           },
       }.merge(@call_options)
+      advanced_typecasting = @advanced_typecasting
 
       response = @client.call(action_name, attrs) do
-        advanced_typecasting @advanced_typecasting
+        advanced_typecasting advanced_typecasting
         message(args)
       end
     end

data/lib/easy_upnp/control_point/device_control_point.rb

@@ -53,10 +53,10 @@ module EasyUpnp
       @client = ClientWrapper.new(
         service_endpoint,
         urn,
-        call_options: @options.call_options,
-        advanced_typecasting: @options.advanced_typecasting,
-        log_enabled: @options.log_enabled,
-        log_level: @options.log_level
+        @options.call_options,
+        @options.advanced_typecasting,
+        @options.log_enabled,
+        @options.log_level
       )
 
       definition_xml = Nokogiri::XML(definition)
@@ -163,8 +163,17 @@ module EasyUpnp
 
       options = EventConfigOptions.new(&block)
 
-      listener = EasyUpnp::HttpListener.new(callback: callback) do |c|
+      listener = EasyUpnp::HttpListener.new do |c|
         options.configure_http_listener.call(c)
+
+        # It'd be kinda weird if a user set this (since a callback is taken as
+        # an argument to the `on_event` method), but it'd be even weirder if
+        # we ignored it.
+        user_callback = c.callback
+        c.callback do |r|
+          user_callback.call(r) if user_callback
+          callback.call(r)
+        end
       end
 
       # exposing the URL as a lambda allows the subscription manager to get a

data/lib/easy_upnp/version.rb

@@ -1,3 +1,3 @@
 module EasyUpnp
-  VERSION = '1.1.2'
+  VERSION = '1.1.4'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: easy_upnp
 version: !ruby/object:Gem::Version
-  version: 1.1.2
+  version: 1.1.4
 platform: ruby
 authors:
 - Christopher Mullins
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-04-17 00:00:00.000000000 Z
+date: 2016-04-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake