doxie 0.0.10 → 0.0.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3370afbb5baece77571aaf553c9ab158627ea651
-  data.tar.gz: 79755e715fff9cd0f21a0e1487cf23e1adbd0844
+  metadata.gz: b1d12a896170887de484098d01ed3aa71a340b19
+  data.tar.gz: cb8783fd43705f51653b91101241615cfd733da0
 SHA512:
-  metadata.gz: 6a941b7938332624eba5ae4c7738ce6a7d432c42d23c3ff5f373b0465a0bfef65f31b9fe2a1a6834dce9b9711bea2b5d639faf178495e6a85d51baf59db8fbe3
-  data.tar.gz: 531724d20aa48191801ed2cf8be13b579809b905a68e7fcd628cca0570273bf7810e0aee83c409977f589ae347d8314938503c30b448431cebbd9f48e1cd63c4
+  metadata.gz: 261beb1d25db1fde8806789009d9da2f9e7491210d5cdf76155e4d05608599ead332ff0459fb90ed38129ef914e20b42ab166bd0b314207568d6600947843d56
+  data.tar.gz: 0c58ead8065c7f13fcab942efef7bc8f5b2c66a7528aafeeb43da299f883462e5b3c7aa3e7584f118fcf8376a5730a79ebe882a637f7b8df37a27719a65d7354

data/README.md

@@ -2,7 +2,7 @@
 
 [![Gem Version](https://badge.fury.io/rb/doxie.svg)](https://badge.fury.io/rb/doxie) [![Build Status](https://travis-ci.org/cbetta/doxie.svg?branch=master)](https://travis-ci.org/cbetta/doxie)
 
-A wrapper for the Doxie Go Wifi API. Specification as per the [developer documentation](http://help.getdoxie.com/content/doxiego/05-advanced/03-wifi/04-api/Doxie-API-Developer-Guide.pdf).
+A wrapper for the [Doxie Go Wifi](http://getdoxie.com) API. Specification as per the [developer documentation](http://help.getdoxie.com/content/doxiego/05-advanced/03-wifi/04-api/Doxie-API-Developer-Guide.pdf).
 
 ## Installation
 
@@ -25,6 +25,11 @@ client = Doxie::Client.new(ip: '192.168.1.2', password: 'test')
 
 ### GET /hello.json
 
+Returns status information for the scanner, firmware, network mode, and password
+configuration. Accessing this command does not require a password if one has been
+set. The values returned depend on whether the scanner is creating its own
+network or joining an existing network.
+
 ```rb
 client.hello
 => {
@@ -39,8 +44,28 @@ client.hello
 }
 ```
 
+* __model__: Always DX250.
+* __name__: The name of the scanner, which defaults to the form "Doxie_XXXXXX".
+  The name of a scanner can be changed by using the Doxie desktop app.
+* __firmwareWiFi__: The Wi-Fi firmware version.
+* __hasPassword__: Indicates whether a password has been set to authenticate API
+  access. Passwords can be set and removed by using the Doxie desktop app.
+* __MAC__: The MAC address of the scanner as shown on the scanner's bottom
+  label.
+* __mode__: "AP" if the scanner is creating its own network or "Client" if the
+  scanner is joining an existing network.
+* __network__: If the scanner is in "Client" mode, this is the name of the
+  network it has joined.
+* __ip__: If the scanner is in "Client" mode, this is the IP of the scanner on
+  the network it has joined.
+
 ### GET /hello_extra.json
 
+Returns additional status values. These values are accessed separately from
+those in `/hello.json` because there can be a delay of several seconds in
+loading them. Accessing this command does not require a password if one has
+been set.
+
 ```rb
 client.hello_extra
 => {
@@ -49,8 +74,16 @@ client.hello_extra
 }
 ```
 
+* __firmware__: The scanner firmware version.
+* __connectedToExternalPower__: Indicates whether the scanner is connected to
+  its AC adapter versus running on battery power. This value is not cached, so
+  it immediately reflects any state changes.
+
 ### GET /restart.json
 
+Restarts the scanner's Wi-Fi system. The scanner's status light blinks blue
+during the restart.
+
 ```rb
 client.restart
 => true
@@ -58,6 +91,9 @@ client.restart
 
 ### GET /scans.json
 
+Returns an array of all scans currently in the scanner’s memory. After scanning
+a document, the scan will available via the API several second later.
+
 ```rb
 client.scans
 => [
@@ -69,9 +105,17 @@ client.scans
 ]
 ```
 
+Calling this function immediately after scanning something may return a blank
+result, even if there are other scans on the scanner, due to the scanner's
+memory being in use. Consider retrying if a successful HTTP status code is
+returned along with a blank body.
 
 ### GET /scans/recent.json
 
+Returns the path to the last scan if available. Monitoring this value for
+changes provides a simple way to detect new scans without having to fetch the
+entire list of scans.
+
 ```rb
 client.recent_scans
 => {
@@ -111,15 +155,31 @@ client.thumbnail "/DOXIE/JPEG/IMG_0001.JPG", 'test.jpg'
 => true
 ```
 
+Thumbnails are constrained to fit within 240x240 pixels. Thumbnails for new
+scans are not generated until after the scan has been made available in
+`/scans.json` and `/scans/recent.json`. This function will return 404 Not Found
+if the thumbnail has not yet been generated. Retrying after a delay is
+recommended to handle such cases.
+
 ### DELETE /scans/DOXIE/JPEG/IMG_XXXX.JPG
 
+Deletes the scan at the specified path.
+
 ```rb
 client.delete_scan "/DOXIE/JPEG/IMG_0001.JPG"
 => true
 ```
 
+Deleting takes several seconds because a lock on the internal storage must be
+obtained and released. Deleting may fail if the lock cannot be obtained
+(e.g., the scanner is busy), so consider retrying on failure conditions. When
+deleting multiple scans, use `/scans/delete.json` for best performance.
+
 ### POST /scans/delete.json
 
+Deletes multiple scans in a single operation. This is much faster than deleting
+each scan individually. 
+
 ```rb
 client.delete_scans ["/DOXIE/JPEG/IMG_0001.JPG", "/DOXIE/JPEG/IMG_0002.JPG"]
 => true

data/doxie.gemspec

@@ -1,7 +1,8 @@
+require File.expand_path('lib/doxie/version', File.dirname(__FILE__))
 
 Gem::Specification.new do |s|
   s.name        = 'doxie'
-  s.version     = '0.0.10'
+  s.version     =  Doxie::VERSION
   s.summary     = "Doxie API Wrapper for getting scans off your Doxie scanner"
   s.description = "Doxie API Wrapper for getting scans off your Doxie scanner"
   s.authors     = ["Cristiano Betta"]

data/lib/doxie.rb

@@ -1,119 +1,2 @@
-require 'net/http'
-require 'json'
-
-module Doxie
-  class Client
-    class Error < StandardError; end
-    class ClientError < Error; end
-    class ServerError < Error; end
-    class AuthenticationError < ClientError; end
-
-    USERNAME = 'doxie'.freeze
-
-    attr_accessor :ip, :password
-
-    def initialize options
-      @ip = options[:ip] || ''
-      @password = options[:password] || ''
-    end
-
-    def hello
-      get('/hello.json')
-    end
-
-    def hello_extra
-      get('/hello_extra.json')
-    end
-
-    def restart
-      get('/restart.json')
-    end
-
-    def scans
-      get('/scans.json')
-    end
-
-    def recent_scans
-      get('/scans/recent.json')
-    end
-
-    def scan scan_name, file_name = nil
-      file "/scans#{scan_name}", file_name
-    end
-
-    def thumbnail scan_name, file_name = nil
-      file "/thumbnails#{scan_name}", file_name
-    end
-
-    def delete_scan scan_name
-      delete("/scans#{scan_name}")
-    end
-
-    def delete_scans scan_names
-      post("/scans/delete.json", scan_names)
-    end
-
-    private
-
-    def get path
-      uri = uri_for(path)
-      message = Net::HTTP::Get.new(uri.request_uri)
-      parse(request(uri, message))
-    end
-
-    def post path, params
-      uri = uri_for(path)
-      message = Net::HTTP::Post.new(uri.request_uri)
-      message.body = JSON.generate(params)
-      parse(request(uri, message))
-    end
-
-
-    def delete path
-      uri = uri_for(path)
-      message = Net::HTTP::Delete.new(uri.request_uri)
-      parse(request(uri, message))
-    end
-
-    def uri_for path
-      URI("https://#{ip}:8080#{path}")
-    end
-
-    def request(uri, message)
-      message.basic_auth USERNAME, password if password
-      http = Net::HTTP.new(uri.host, uri.port)
-      http.request(message)
-    end
-
-    def parse response
-      case response
-      when Net::HTTPNoContent
-        return true
-      when Net::HTTPSuccess
-        if response['Content-Type'].split(';').first == 'application/json'
-          JSON.parse(response.body)
-        else
-          response.body
-        end
-      when Net::HTTPUnauthorized
-        raise AuthenticationError, "#{response.code} response from #{ip}"
-      when Net::HTTPClientError
-        raise ClientError, "#{response.code} response from #{ip}"
-      when Net::HTTPServerError
-        raise ServerError, "#{response.code} response from #{ip}"
-      else
-        raise Error, "#{response.code} response from #{ip}"
-      end
-    end
-
-    def file scan_name, file_name
-      body = get(scan_name)
-      if file_name
-        File.open(file_name, 'wb') { |file| file.write(body) }
-        true
-      else
-        body
-      end
-    end
-  end
-end
+require 'doxie/version'
+require 'doxie/client'

data/lib/doxie/client.rb

@@ -0,0 +1,119 @@
+require 'net/http'
+require 'json'
+
+module Doxie
+  class Client
+    class Error < StandardError; end
+    class ClientError < Error; end
+    class ServerError < Error; end
+    class AuthenticationError < ClientError; end
+
+    USERNAME = 'doxie'.freeze
+
+    attr_accessor :ip, :password
+
+    def initialize options
+      @ip = options[:ip] || ''
+      @password = options[:password] || ''
+    end
+
+    def hello
+      get('/hello.json')
+    end
+
+    def hello_extra
+      get('/hello_extra.json')
+    end
+
+    def restart
+      get('/restart.json')
+    end
+
+    def scans
+      get('/scans.json')
+    end
+
+    def recent_scans
+      get('/scans/recent.json')
+    end
+
+    def scan scan_name, file_name = nil
+      file "/scans#{scan_name}", file_name
+    end
+
+    def thumbnail scan_name, file_name = nil
+      file "/thumbnails#{scan_name}", file_name
+    end
+
+    def delete_scan scan_name
+      delete("/scans#{scan_name}")
+    end
+
+    def delete_scans scan_names
+      post("/scans/delete.json", scan_names)
+    end
+
+    private
+
+    def get path
+      uri = uri_for(path)
+      message = Net::HTTP::Get.new(uri.request_uri)
+      parse(request(uri, message))
+    end
+
+    def post path, params
+      uri = uri_for(path)
+      message = Net::HTTP::Post.new(uri.request_uri)
+      message.body = JSON.generate(params)
+      parse(request(uri, message))
+    end
+
+
+    def delete path
+      uri = uri_for(path)
+      message = Net::HTTP::Delete.new(uri.request_uri)
+      parse(request(uri, message))
+    end
+
+    def uri_for path
+      URI("https://#{ip}:8080#{path}")
+    end
+
+    def request(uri, message)
+      message.basic_auth USERNAME, password if password
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.request(message)
+    end
+
+    def parse response
+      case response
+      when Net::HTTPNoContent
+        return true
+      when Net::HTTPSuccess
+        if response['Content-Type'].split(';').first == 'application/json'
+          JSON.parse(response.body)
+        else
+          response.body
+        end
+      when Net::HTTPUnauthorized
+        raise AuthenticationError, "#{response.code} response from #{ip}"
+      when Net::HTTPClientError
+        raise ClientError, "#{response.code} response from #{ip}"
+      when Net::HTTPServerError
+        raise ServerError, "#{response.code} response from #{ip}"
+      else
+        raise Error, "#{response.code} response from #{ip}"
+      end
+    end
+
+    def file scan_name, file_name
+      body = get(scan_name)
+      if file_name
+        File.open(file_name, 'wb') { |file| file.write(body) }
+        true
+      else
+        body
+      end
+    end
+  end
+end

data/lib/doxie/version.rb

@@ -0,0 +1,3 @@
+module Doxie
+  VERSION = '0.0.11'
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: doxie
 version: !ruby/object:Gem::Version
-  version: 0.0.10
+  version: 0.0.11
 platform: ruby
 authors:
 - Cristiano Betta
@@ -76,6 +76,8 @@ files:
 - README.md
 - doxie.gemspec
 - lib/doxie.rb
+- lib/doxie/client.rb
+- lib/doxie/version.rb
 - spec/doxie_spec.rb
 homepage: https://github.com/cbetta/doxie
 licenses: