sony_camera_remote_api 0.1.4 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6375fb3082ba64b715c9274945dc2b6b1dd59886
-  data.tar.gz: 9472f59d3577ccbd5c2e004f4c58b81692559883
+  metadata.gz: 1673c9a0e55968b5691e720ba4580f10fdc89301
+  data.tar.gz: b7dfb169b64c3625e80d5a480a8d50d3aa6a5af2
 SHA512:
-  metadata.gz: e9ba24e31f964de2c2071cd5130bb357fdd64634c5c3856c9aa5b1c7011257baaeb7adcae210ee18f28efe3fd99a9d10893f7718277d684b8d761d1cc7ca3fbf
-  data.tar.gz: c4dac8ad1de4ef5df1db9b0aedf1197e19507746a0fdbbbdd5abc1a49a28ff28a5cc2852cc8fffb8979b1e6d4e6c35971cae2684bf2070b9810ebc61c0ef20cb
+  metadata.gz: 41eef398296c1351f7c792c9ca67c38a7102f831790f97d381e8db2ce15deb252b9b335de830f91c3d922c54822120b56fad94868afff9b62765eac6a42a1107
+  data.tar.gz: 90bb27d0d5cad30a6d3999f640efa1caf4f47fc4f96a5c105cf35b363687ba844962b805765b5dceb74e07167690b0a22271f318e10590e6326f69ad7837b942

data/lib/core_ext/hash_patch.rb

@@ -1,13 +1,18 @@
+# Hash extension for handling API response.
 class Hash
-  # Get result element of API response.
+  # Get result element.
   def result
     self['result']
   end
-  # Get id element of API response.
+  # Get results element.
+  def results
+    self['results']
+  end
+  # Get id element.
   def id
     self['id']
   end
-  # Get error element of API response.
+  # Get error element.
   def error
     self['error']
   end

data/lib/sony_camera_remote_api/camera_api.rb

@@ -14,11 +14,12 @@ module SonyCameraRemoteAPI
     # Default timeout for waiting camera parameter changes
     DEFAULT_PARAM_CHANGE_TIMEOUT = 15
 
-    def_delegators :@raw_api_manager, :apis, :support?
     def_delegators :@api_group_manager, :get_parameter, :get_parameter!,
                                         :set_parameter, :set_parameter!,
-                                        :get_current, :get_current!
-    def_delegator :@api_group_manager, :support_group?
+                                        :get_current, :get_current!,
+                                        :parameters
+    def_delegators :@raw_api_manager, :apis
+
 
 
     # Create CameraAPIManager object.
@@ -31,28 +32,6 @@ module SonyCameraRemoteAPI
     end
 
 
-    # Call camera APIs with checking if it is available by 'getAvailableApiList'.
-    # If not available, wait a minute until the called API turns to be available.
-    # @param [String] service_type
-    # @param [String] method
-    # @param [Array,String] params
-    # @param [Fixnum] id
-    # @param [String] version
-    # @param [Fixnum] timeout Timeout in seconds for waiting until the API is available
-    def call_api_safe(service_type, method, params, id, version, timeout = DEFAULT_API_CALL_TIMEOUT, **args)
-      unless getAvailableApiList['result'][0].include? method
-        log.error "Method '#{method}' is not available now! waiting..."
-        begin
-          wait_event(timeout: timeout) { |res| res[0]['names'].include? method }
-        rescue EventTimeoutError => e
-          raise APINotAvailable.new, "Method '#{method}' is not available now!"
-        end
-        log.info "Method '#{method}' has become available."
-      end
-      @raw_api_manager.call_api(service_type, method, params, id, version)
-    end
-
-
     # getEvent API.
     # Long polling flag is set true as default.
     # @param [Array,String] params
@@ -92,6 +71,7 @@ module SonyCameraRemoteAPI
     #   * polling = true  : Always use long polling in getEvent call
     #   * polling = false : Never use long polling in getEvent call
     # @raise EventTimeoutError
+    # @todo add example
     def wait_event(timeout: DEFAULT_PARAM_CHANGE_TIMEOUT, polling: nil, &block)
       start_time = Time.now if timeout
       # Long-polling is disabled only at the first call
@@ -117,13 +97,33 @@ module SonyCameraRemoteAPI
 
 
     # Ghost method, which handles almost API calls.
-    # If Camera API (servie type == camera) is called, call_api_safe() is used.
+    # You can call an API as a method with the same name.
+    # We don't have to specify service_type and version for almost APIs.
+    # But some APIs have multiple service types and versions, so that we have to specify one service type or version.
+    # When '!' is appended to the end of the method name, it does not raise Exception even if any error occurred.
     # @param [String] method
     # @param [Array,String] params
     # @param [String] service_type
     # @param [Fixnum] id
     # @param [String] version
     # @param [Fixnum] timeout   Timeout in seconds for waiting until the API is available
+    # @example
+    #   # Initialize
+    #   cam = SonyCameraRemoteAPI::Camera.new
+    #   cam.change_function_to_shoot 'still', 'Single'
+    #
+    #   # Call getMethodTypes API with parameter: ['1.0'], service type: 'camera' and id: 1.
+    #   response = cam.getMethodTypes ['1.0'], service_type: 'camera', id: 1
+    #   puts response.id
+    #   response.results.each do |r|
+    #     puts '----'
+    #     puts r
+    #   end
+    #
+    #   # Call setCurrentTime API if supported.
+    #   cam.setCurrentTime! [{'dateTime' => Time.now.utc.iso8601,
+    #                       'timeZoneOffsetMinute' => 540,
+    #                       'dstOffsetMinute' => 0}]
     def method_missing(method, params = [], *args, **opts)
       ignore_error = true if method.to_s.end_with? '!'
       method = method.to_s.delete('!').to_sym
@@ -141,7 +141,7 @@ module SonyCameraRemoteAPI
           else
             response = @raw_api_manager.call_api(service, name, params, id, version)
           end
-        rescue APINotSupported, APINotAvailable, IllegalArgument, HTTPClient::BadResponseError => e
+        rescue APIForbidden, APINotSupported, APINotAvailable, IllegalArgument, HTTPClient::BadResponseError => e
           if ignore_error
             return nil
           else
@@ -153,8 +153,47 @@ module SonyCameraRemoteAPI
     end
 
 
+    # Get whether the API or API group is supported by a camera.
+    # @param [Symbol] api_or_group_name The API or API group name
+    # @return [Boolean] +true+ if supported, +false+ otherwise.
+    # @example
+    #   # Initialize
+    #   cam = SonyCameraRemoteAPI::Camera.new
+    #   cam.change_function_to_shoot 'still', 'Single'
+    #
+    #   # Check if actZoom API is supported.
+    #   puts cam.support? :actZoom
+    #   # Check if ZoomSetting API group is supported.
+    #   puts cam.support? :ZoomSetting
+    def support?(api_or_group_name)
+      @raw_api_manager.support?(api_or_group_name) || @api_group_manager.support_group?(api_or_group_name)
+    end
+
+
     private
 
+    # Call camera APIs with checking if it is available by 'getAvailableApiList'.
+    # If not available, wait a minute until the called API turns to be available.
+    # @param [String] service_type
+    # @param [String] method
+    # @param [Array,String] params
+    # @param [Fixnum] id
+    # @param [String] version
+    # @param [Fixnum] timeout Timeout in seconds for waiting until the API is available
+    def call_api_safe(service_type, method, params, id, version, timeout = DEFAULT_API_CALL_TIMEOUT, **args)
+      unless getAvailableApiList['result'][0].include? method
+        log.error "Method '#{method}' is not available now! waiting..."
+        begin
+          wait_event(timeout: timeout) { |res| res[0]['names'].include? method }
+        rescue EventTimeoutError => e
+          raise APINotAvailable.new, "Method '#{method}' is not available now!"
+        end
+        log.info "Method '#{method}' has become available."
+      end
+      @raw_api_manager.call_api(service_type, method, params, id, version)
+    end
+
+
     # Call getEvent without polling if getEvent with polling failed.
     def get_event_both(poll, timeout: nil)
       getEvent(poll, timeout: timeout)
@@ -194,6 +233,5 @@ module SonyCameraRemoteAPI
       retry_count += 1
       retry
     end
-
   end
 end

data/lib/sony_camera_remote_api/camera_api_group.rb

@@ -130,32 +130,58 @@ module SonyCameraRemoteAPI
     end
 
 
-    # Get current value of a camera parameter.
+    # Get current value of the camera parameter.
     # @param [Symbol] group_name Parameter name
-    # @return [Object] current value
-    # @raise APINotSupported, APINotAvailable, IllegalArgument
+    # @return [Object] Current value
+    # @raise APIForbidden, APINotSupported, APINotAvailable, IllegalArgument
+    # @example
+    #   # Initialize
+    #   cam = SonyCameraRemoteAPI::Camera.new
+    #   cam.change_function_to_shoot 'still', 'Single'
+    #
+    #   value = cam.get_current :ContShootingMode
+    #   puts value      #=> 'Burst', 'MotionShot', Continuous' ...
     def get_current(group_name, **opts)
       get_parameter(group_name, available: false, supported: false, **opts)[:current]
     end
 
 
-    # Almost same as get_current, but this method does not raise Exception
-    # even if the parameter is not supported, available or its arguments illegal.
-    # @param [Symbol] group_name Parameter name
-    # @return [Object] current value
+    # Almost same as get_current, but this method does not raise Exception.
+    # @return [Object, nil] Current value or nil if any error occurred.
+    # @see get_current
+    # @example
+    #   # Initialize
+    #   cam = SonyCameraRemoteAPI::Camera.new
+    #   cam.change_function_to_shoot 'still', 'Single'
+    #
+    #   value = cam.get_current! :ContShootingMode
+    #   if value
+    #     puts "ContShootingMode is supported, and current value is #{value}"
+    #   else
+    #     puts 'ContShootingMode is not supported.'
+    #   end
     def get_current!(group_name, **opts)
       get_parameter!(group_name, available: false, supported: false, **opts)[:current]
     end
 
 
-    # Get supported/available/current value of a camera parameter.
+    # Get supported/available/current value of the camera parameter.
     # @param [Symbol] group_name Parameter name
     # @param [Boolean] available Flag to get available values
     # @param [Boolean] supported Flag to get supported values
     # @return [Hash]  current/available/supported values
-    # @raise APINotSupported, APINotAvailable, IllegalArgument
+    # @raise APIForbidden, APINotSupported, APINotAvailable, IllegalArgument
+    # @example
+    #   # Initialize
+    #   cam = SonyCameraRemoteAPI::Camera.new
+    #   cam.change_function_to_shoot 'movie'
+    #
+    #   result = cam.get_parameter :ExposureMode
+    #   puts "current value   : #{result[:current]}"
+    #   puts "available values: #{result[:available]}"
+    #   puts "supported values: #{result[:supported]}"
     def get_parameter(group_name, available: true, supported: true, **opts)
-      result = { current: nil, available: [], supported: [] }
+      result = { current: nil, available: nil, supported: nil }
       begin
         grp = search_group group_name
       rescue APIForbidden, APINotSupported => e
@@ -178,8 +204,25 @@ module SonyCameraRemoteAPI
     end
 
 
-    # Almost same as get_parameter, but this method does not raise Exception
-    # even if the parameter is not supported, available or its arguments illegal.
+    # Almost same as get_parameter, but this method does not raise Exception.
+    # @return [Hash] current/available/supported values. If any error occurs, the value that cannot get become nil.
+    # @see get_parameter
+    # @example
+    #   # Initialize
+    #   cam = SonyCameraRemoteAPI::Camera.new
+    #   cam.change_function_to_shoot 'still', 'Single'
+    #
+    #   result = cam.get_parameter! :ExposureMode
+    #   if result[:current]
+    #     puts 'ExposureMode is supported.'
+    #     if result[:available] && result[:supported]
+    #       puts 'And you can change the value by #set_parameter.'
+    #     else
+    #       puts 'And you can change the value by the hardware dial or switch (NOT by #set_parameter).'
+    #     end
+    #   else
+    #     puts 'ExposureMode is not supported!'
+    #   end
     def get_parameter!(group_name, **opts)
       get_parameter(group_name, **opts)
     rescue APIForbidden, APINotSupported, APINotAvailable, IllegalArgument => e
@@ -190,13 +233,28 @@ module SonyCameraRemoteAPI
     end
 
 
-    # Set a camera parameter to the given value.
+    # Set the camera parameter to the given value.
     # @param [Symbol] group_name Parameter name
     # @param [Object] value New value to be set
-    # @return [Hash]  current/available/old values
-    # @raise APINotSupported, APINotAvailable, IllegalArgument
+    # @return [Hash]  current/available/old values after setting parameter.
+    #   If given value is equal to current value, available/old values become nil.
+    # @raise APIForbidden, APINotSupported, APINotAvailable, IllegalArgument
+    # @example
+    #   # Initialize
+    #   cam = SonyCameraRemoteAPI::Camera.new
+    #   cam.change_function_to_shoot 'still', 'Single'
+    #
+    #   result = cam.set_parameter :FlashMode, 'slowSync'
+    #   if result[:old]
+    #     puts "The value is changed from '#{result[:old]}' to '#{result[:current]}'."
+    #   else
+    #     puts 'The value is not changed.'
+    #   end
+    #   puts "current value   : #{result[:current]}"
+    #   puts "available values: #{result[:available]}"
+    #   puts "old value       : #{result[:old]}"
     def set_parameter(group_name, value, *args, **opts)
-      result = { current: nil, available: [], old: nil }
+      result = { current: nil, available: nil, old: nil }
       begin
         grp = search_group group_name
       rescue APIForbidden, APINotSupported => e
@@ -208,7 +266,6 @@ module SonyCameraRemoteAPI
         value = grp.preprocess_value(value, args, condition)
         # If value is equal to current value, do nothing.
         result.merge! grp.current_value(@api_manager, condition, **opts)
-        result[:old] = result[:current]
         if grp.eq_current? value, result[:current], condition
           return result
         end
@@ -229,8 +286,27 @@ module SonyCameraRemoteAPI
     end
 
 
-    # Almost same as set_parameter, but this method does not raise Exception
-    # even if the parameter is not supported, available or its arguments illegal.
+    # Almost same as set_parameter, but this method does not raise Exception.
+    # @return [Hash] current/available/old values after setting parameter.
+    #   If given value is equal to current value, available/old values become nil.
+    #   If any error occurs, the values that cannot get become nil.
+    # @see set_parameter
+    # @example
+    #   # Initialize
+    #   cam = SonyCameraRemoteAPI::Camera.new
+    #   cam.change_function_to_shoot 'still', 'Single'
+    #
+    #   result = cam.set_parameter! :FlashMode, 'on'
+    #   if result[:current]
+    #     puts 'FlashMode is supported.'
+    #     if result[:current] == 'on'
+    #       puts "And successfully set the value to '#{result[:current]}'."
+    #     else
+    #       puts 'But cannot set the value.'
+    #     end
+    #   else
+    #     puts 'FlashMode is not supported!'
+    #   end
     def set_parameter!(group_name, value, **opts)
       set_parameter(group_name, value, **opts)
     rescue APIForbidden, APINotSupported, APINotAvailable, IllegalArgument => e
@@ -241,6 +317,13 @@ module SonyCameraRemoteAPI
     end
 
 
+    # Get an array of supported camera parameters.
+    # @return [Array<String>] supported camera parameters
+    def parameters
+      @api_groups.keys
+    end
+
+
     # Returns whether the parameter is supported or not.
     # @return [Boolean] +true+ if the parameter is supported, false otherwise.
     def support_group?(group_name)

data/lib/sony_camera_remote_api/client/main.rb

@@ -11,12 +11,13 @@ require 'time'
 require 'pp'
 
 module SonyCameraRemoteAPI
-  # CLI client module
+  # sonycam client module
   module Client
 
     # Default config file saved in home directory.
     GLOBAL_CONFIG_FILE = File.expand_path('~/.sonycamconf')
 
+    # Main class of client
     class Main < Thor
       include Utils
       include Scripts
@@ -39,9 +40,9 @@ module SonyCameraRemoteAPI
         def load_camera_config
           # If SSID is specified, load the camera config.
           if options[:ssid]
-            @shelf.get options[:ssid] || @shelf.get_default
+            @shelf.get options[:ssid] || @shelf.get
           else
-            @shelf.get_default
+            @shelf.get
           end
         end
 
@@ -67,7 +68,7 @@ module SonyCameraRemoteAPI
           puts 'Initializing camera...'
           if config['endpoints'].nil?
             @cam = SonyCameraRemoteAPI::Camera.new reconnect_by: method(:load_and_connect)
-            @shelf.set_endpoints config['ssid'], @cam.endpoints
+            @shelf.set_ep config['ssid'], @cam.endpoints
             puts 'SSDP configuration saved.'
           else
             @cam = SonyCameraRemoteAPI::Camera.new endpoints: config['endpoints'],
@@ -108,7 +109,7 @@ module SonyCameraRemoteAPI
         # Show for other parameter
         def show_normal(result)
           array = []
-          if result[:supported].empty?
+          unless result[:supported]
             # If current value is present but NO supported value, it is immutable.
             result[:supported] = [result[:current]]
           end
@@ -127,7 +128,7 @@ module SonyCameraRemoteAPI
         # Show for WhiteBalance parameter
         def show_WhiteBalance(result)
           array = []
-          if result[:supported].empty?
+          unless result[:supported]
             # If current value is present but NO supported value, it is immutable.
             result[:supported] = [result[:current]]
           end
@@ -374,7 +375,7 @@ module SonyCameraRemoteAPI
       option :transfer, type: :boolean, desc: 'Transfer postview image', default: false
       def rapid
         init_camera
-        unless @cam.support_group? :ContShootingMode
+        unless @cam.support? :ContShootingMode
           puts 'This camera does not support continuous shooting mode. Exiting...'
           exit 1
         end

data/lib/sony_camera_remote_api/client/shelf.rb

@@ -155,7 +155,7 @@ module SonyCameraRemoteAPI
             return
           end
         end
-        @shelf.set_interface if_name, specified['ssid'] if specified
+        @shelf.set_if if_name, specified['ssid'] if specified
         invoke :list, [], options
       end
 

data/lib/sony_camera_remote_api/logging.rb

@@ -35,10 +35,16 @@ module Logging
   # Log file is common in each user class.
   # @param [String, IO, Array<String, IO>] log_file file name or stream to output log.
   # @return [void]
-  def output_to(*log_file)
+  def set_output(*log_file)
     Logging.log_file self.class.name, log_file
   end
 
+  # Set log level.
+  # @param [Fixnum] level Log level for Logger object.
+  def set_level(level)
+    @@level = level
+  end
+
   #--------------------PUBLIC METHODS END----------------------
 
 
@@ -47,6 +53,8 @@ module Logging
   # Use a hash class-ivar to cache a unique Logger per class.
   @loggers = {}
 
+  @@level = Logger::DEBUG
+
   # These module class methods are private to user class.
   class << self
     # Set log files and streams. Logger class instance is re-created.
@@ -70,6 +78,7 @@ module Logging
       end
       logger = Logger.new MultiDelegator.delegate(:write, :close).to(*fios)
       logger.progname = classname.split('::')[-1]
+      logger.level = @@level
       logger
     end
   end

data/lib/sony_camera_remote_api/raw_api.rb

@@ -157,12 +157,12 @@ module SonyCameraRemoteAPI
           end
           version = api_info.versions[0]
         end
-        if opts.key? :service
-          service = opts[:service]
-          if api_info.service_types.include? opts[:service]
-            service = opts[:service]
+        if opts.key? :service_type
+          service = opts[:service_type]
+          if api_info.service_types.include? opts[:service_type]
+            service = opts[:service_type]
           else
-            raise ServiceTypeInvalid, "The service type '#{opts[:service]}' is invalid for method '#{method}'."
+            raise ServiceTypeInvalid, "The service type '#{opts[:service_type]}' is invalid for method '#{method}'."
           end
         else
           # raise error if service type is not given for method having multi service types

data/lib/sony_camera_remote_api/shelf.rb

@@ -4,6 +4,7 @@ require 'yaml'
 
 
 module SonyCameraRemoteAPI
+  # Class for handling multiple camera's connection configurations.
   class Shelf
     include Utils
 
@@ -125,7 +126,7 @@ module SonyCameraRemoteAPI
 
     # Set endpoint information to a camera config.
     # @return [Boolean] +true+ if successfully set endpoints, +false+ otherwise.
-    def set_endpoints(endpoints, ssid = nil)
+    def set_ep(endpoints, ssid = nil)
       entry = get(ssid)
       if entry
         entry['endpoints'] = endpoints
@@ -136,9 +137,21 @@ module SonyCameraRemoteAPI
     end
 
 
+    # Get endpoint information to a camera config.
+    # @return [Boolean] +true+ if successfully set endpoints, +false+ otherwise.
+    def ep(ssid = nil)
+      entry = get(ssid)
+      if entry
+        entry['endpoints']
+      else
+        nil
+      end
+    end
+
+
     # Set interface by which the camera is connected.
     # @return [Boolean] +true+ if successfully set default camera, +false+ otherwise.
-    def set_interface(interface, ssid = nil)
+    def set_if(interface, ssid = nil)
       entry = get(ssid)
       if entry
         entry['interface'] = interface
@@ -163,6 +176,20 @@ module SonyCameraRemoteAPI
     end
 
 
+    # Restart interface, and then connect to the camera.
+    # If SSID is not given, default camera is used.
+    # @param [String] ssid SSID
+    # @return [Boolean] +true+ if successfully connected, +false+ otherwise.
+    def reconnect(ssid = nil)
+      entry = get(ssid)
+      if entry
+        Scripts.restart_and_connect entry['interface'], entry['ssid'], entry['pass']
+      else
+        false
+      end
+    end
+
+
     private
 
     # Get camera whose SSID uniquely matches with specified string.

data/lib/sony_camera_remote_api/version.rb

@@ -1,3 +1,4 @@
 module SonyCameraRemoteAPI
-  VERSION = '0.1.4'.freeze
+  # Version
+  VERSION = '0.2.0'.freeze
 end

data/lib/sony_camera_remote_api.rb

@@ -4,6 +4,7 @@ require 'sony_camera_remote_api/ssdp'
 require 'sony_camera_remote_api/utils'
 require 'sony_camera_remote_api/camera_api'
 require 'sony_camera_remote_api/packet'
+require 'sony_camera_remote_api/shelf'
 require 'core_ext/hash_patch'
 require 'httpclient'
 require 'active_support'
@@ -21,10 +22,11 @@ module SonyCameraRemoteAPI
     include SSDP
     include Utils
 
-    def_delegators :@api_manager, :apis, :method_missing, :getEvent, :getAvailableApiList,
-                   :wait_event,
-                   :get_parameter, :get_parameter!, :set_parameter, :set_parameter!, :get_current, :get_current!,
-                   :support?, :support_group?
+    def_delegators :@api_manager, :method_missing, :getEvent, :getAvailableApiList, :wait_event,
+                                  :get_parameter, :get_parameter!,
+                                  :set_parameter, :set_parameter!,
+                                  :get_current, :get_current!,
+                                  :support?, :parameters, :apis
 
     attr_reader :endpoints
 
@@ -41,8 +43,9 @@ module SonyCameraRemoteAPI
     # @param [String, IO, Array<String, IO>] log_file   file name or stream to output log.
     # @param [Boolean] finalize   If true, stopRecMode API is called in the destructor.
     #   As far as I know, we don't have any trouble even if we never call stopRecMode.
-    def initialize(endpoints: nil, reconnect_by: nil, log_file: $stdout, finalize: false)
-      output_to log_file if log_file.present?
+    def initialize(endpoints: nil, reconnect_by: nil, log_file: $stdout, log_level: Logger::INFO, finalize: false)
+      set_output log_file
+      set_level  log_level
       @endpoints = endpoints || ssdp_search
       @reconnect_by = reconnect_by
       @api_manager = CameraAPIManager.new @endpoints, reconnect_by: @reconnect_by
@@ -102,7 +105,6 @@ module SonyCameraRemoteAPI
     #   * Single     : take a single picture
     #   * Burst      : take 10 pictures at a time
     #   * MotionShot : take 10 pictures and render the movement into a single picture
-    # @param [Boolean]  focus     Flag to focus on before capturing.
     # @param [Boolean]  transfer  Flag to transfer the postview image.
     # @param [String]   filename  Name of image file to be transferred. If not given, original name is used.
     #    Only available in Single/MotionShot shooting mode.
@@ -111,17 +113,16 @@ module SonyCameraRemoteAPI
     # @param [String]   dir       Directory where image file is saved. If not given, current directory is used.
     # @return [String, Array<String>, nil]  Filename of the transferred image(s). If 'transfer' is false, returns nil.
     # @example
-    #   # Capture single still image and save it as 'a.jpg' to 'image' directory
-    #   change_function_to_shoot('still', 'Single')
-    #   capture_still
-    #   capture_still(filename: 'a.jpg', dir: 'image')
+    #   # Initialize
+    #   cam = SonyCameraRemoteAPI::Camera.new
+    #   # Capture a single still image, and then save it as images/TEST.JPG.
+    #   cam.change_function_to_shoot 'still', 'Single'
+    #   cam.capture_still filename: 'TEST.JPG', dir: 'images'
     #
-    #   # Capture 10 images by burst shooting mode and save them as 'TEST_0.jpg', ... 'TEST_9.jpg'.
-    #   change_function_to_shoot('still', 'Burst')
-    #   capture_still
-    #   capture_still(prefix: 'TEST')
-    def capture_still(focus: true, transfer: true, filename: nil, prefix: nil, dir: nil)
-      act_focus if focus
+    #   # Capture 10 images by burst shooting and save them as 'TEST_0.jpg', ... 'TEST_9.jpg'.
+    #   cam.change_function_to_shoot 'still', 'Burst'
+    #   cam.capture_still prefix: 'TEST'
+    def capture_still(transfer: true, filename: nil, prefix: nil, dir: nil)
       wait_event { |r| r[1]['cameraStatus'] == 'IDLE' }
       log.info 'Capturing...'
       postview_url = ''
@@ -151,15 +152,16 @@ module SonyCameraRemoteAPI
     # @note You have to set shooting mode to 'still' and continuous shooting mode to following modes:
     #   * Continuous          : take pictures continuously until stopped.
     #   * Spd Priority Cont.  : take pictures continuously at a rate faster than 'Continuous'.
-    # @param [Boolean]  focus   Flag to focus on before capturing.
     # @return [void]
-    # @example Do continuous shooting and transfer:
-    #   change_function_to_shoot('still', 'Continuous')
-    #   start_continuous_shooting
+    # @example
+    #   # Initialize
+    #   cam = SonyCameraRemoteAPI::Camera.new
+    #   # Start continuous shooting and transfer all images.
+    #   cam.change_function_to_shoot('still', 'Continuous')
+    #   cam.start_continuous_shooting
     #   ...
-    #   stop_continuous_shooting(transfer: true)
-    def start_continuous_shooting(focus: true)
-      act_focus if focus
+    #   cam.stop_continuous_shooting(transfer: true)
+    def start_continuous_shooting
       wait_event { |r| r[1]['cameraStatus'] == 'IDLE' }
       startContShooting
       wait_event { |r| r[1]['cameraStatus'] == 'StillCapturing' }
@@ -205,11 +207,14 @@ module SonyCameraRemoteAPI
     # To stop recording, call stop_movie_recording method.
     # @note You have to set shooting mode to 'movie' before calling this method.
     # @return [void]
-    # @example Record movie and transfer:
-    #   change_function_to_shoot('movie')
-    #   start_movie_recording
+    # @example
+    #   # Initialize
+    #   cam = SonyCameraRemoteAPI::Camera.new
+    #   # Record movie and transfer it.
+    #   cam.change_function_to_shoot('movie')
+    #   cam.start_movie_recording
     #   ...
-    #   stop_movie_recording(transfer: true)
+    #   cam.stop_movie_recording(transfer: true)
     def start_movie_recording
       wait_event { |r| r[1]['cameraStatus'] == 'IDLE' }
       startMovieRec
@@ -238,13 +243,16 @@ module SonyCameraRemoteAPI
     # To stop recording, call stop_interval_recording method.
     # @note You have to set shooting mode to 'intervalstill' before calling this method.
     # @return [void]
-    # @example Do interval still recording:
-    #   change_function_to_shoot('intervalstill')
-    #   start_interval_recording
+    # @example
+    #   # Initialize
+    #   cam = SonyCameraRemoteAPI::Camera.new
+    #   # Start interval still recording (does not transfer).
+    #   cam.change_function_to_shoot('intervalstill')
+    #   cam.start_interval_recording
     #   ...
-    #   stop_interval_recording(transfer: true)
+    #   cam.stop_interval_recording
     def start_interval_recording
-      act_focus
+      wait_event { |r| r[1]['cameraStatus'] == 'IDLE' }
       startIntervalStillRec
       wait_event { |r| r[1]['cameraStatus'] == 'IntervalRecording' }
       log.info 'Started interval still recording.'
@@ -272,11 +280,14 @@ module SonyCameraRemoteAPI
     # To stop recording, call stop_loop_recording method.
     # @note You have to set shooting mode to 'looprec' before calling this method.
     # @return [void]
-    # @example Typical usage:
-    #   change_function_to_shoot('looprec')
-    #   start_loop_recording
+    # @example
+    #   # Initialize
+    #   cam = SonyCameraRemoteAPI::Camera.new
+    #   # Start loop movie recording (does not transfer).
+    #   cam.change_function_to_shoot('looprec')
+    #   cam.start_loop_recording
     #   ...
-    #   stop_loop_recording(transfer: true)
+    #   cam.stop_loop_recording
     def start_loop_recording
       wait_event { |r| r[1]['cameraStatus'] == 'IDLE' }
       startLoopRec
@@ -308,9 +319,11 @@ module SonyCameraRemoteAPI
     # @param [Fixnum] relative    Relative percecntage to current position of the lense.
     # @return [Array<Fixnum>]     Array of initial zoom position and current zoom position.
     # @example
-    #   act_zoom(absolute: 0)     # zoom out to the wide-end
-    #   act_zoom(absolute: 100)   # zoom in to the tele-end
-    #   act_zoom(relative: -50)   # zoom out by -50 from the current position
+    #   # Initialize
+    #   cam = SonyCameraRemoteAPI::Camera.new
+    #   cam.act_zoom(absolute: 0)     # zoom out to the wide-end
+    #   cam.act_zoom(absolute: 100)   # zoom in to the tele-end
+    #   cam.act_zoom(relative: -50)   # zoom out by -50 from the current position
     def act_zoom(absolute: nil, relative: nil)
       # Check arguments
       return if [relative, absolute].none?
@@ -349,16 +362,22 @@ module SonyCameraRemoteAPI
     end
 
 
-    # Act focus, which is the same as half-pressing shutter button.
-    # If already focued, this method does nothing unless 'force' parameter specified as true.
-    # @param [Boolean] force Re-forcus if the camera has already focused.
+    # Do focus, which is the same as half-pressing the shutter button.
     # @return [Boolean] +true+ if focus succeeded, +false+ if failed.
     # @example
-    #   # Try to focus on and succeeded.
-    #   act_focus     #=> true
-    def act_focus(force: false)
+    #   # Initialize
+    #   cam = SonyCameraRemoteAPI::Camera.new
+    #   # Focus function is available only 'still' shoot mode
+    #   cam.change_function_to_shoot 'still'
+    #   # Capture forever only when focus succeeded.
+    #   loop do
+    #     if cam.act_focus
+    #       cam.capture_still
+    #     end
+    #   end
+    def act_focus
       return false unless support? :actHalfPressShutter
-      return true  unless needs_focus?(force: force)
+      cancel_focus
       actHalfPressShutter
       rsp = wait_event { |r| ['Focused', 'Failed'].include? r[35]['focusStatus'] }
       if rsp[35]['focusStatus'] =='Focused'
@@ -373,24 +392,23 @@ module SonyCameraRemoteAPI
     end
 
 
-    # Act touch focus, by which we can specify the focus position.
-    # The focus position is expressed by percentage to the origin of coordinates, which is upper left of liveview images.
-    # If already focued, this method does nothing unless 'force' parameter specified as true.
+    # Do touch focus, by which we can specify the focus position.
     # @note Tracking focus and Touch focus is exclusive function.
     #   Tracking focus is disabled automatically by calling this method.
     # @param [Fixnum] x   Percentage of X-axis position.
     # @param [Fixnum] y   Percentage of Y-axis position.
-    # @param [Boolean] force Re-forcus if the camera has already focused.
     # @return [Boolean]   AFType ('Touch' or 'Wide') if focus succeeded. nil if failed.
     # @see Touch AF position parameter in API reference
     # @example
-    #   # Try to focus on bottom-left position and succeeded with 'Wide' type focus.
-    #   act_touch_focus(10, 90)     #=> 'Wide'
-    #   # Try to focus on upper-right position but failed.
-    #   act_touch_focus(90, 10)     #=> nil
-    def act_touch_focus(x, y, force: false)
+    #   # Initialize
+    #   cam = SonyCameraRemoteAPI::Camera.new
+    #   # Try to focus on upper-middle position.
+    #   if cam.act_touch_focus(50, 10)
+    #     cam.capture_still
+    #   end
+    def act_touch_focus(x, y)
       return false unless support? :setTouchAFPosition
-      return true  unless needs_focus?(force: force)
+      cancel_focus
       set_parameter! :TrackingFocus, 'Off'
 
       x = [[x, 100].min, 0].max
@@ -407,21 +425,32 @@ module SonyCameraRemoteAPI
     end
 
 
-    # Act trackig focus, by which the focus position automatically track the object.
+    # Do tracking focus, by which the focus position automatically track the object.
     # The focus position is expressed by percentage to the origin of coordinates, which is upper left of liveview images.
-    # If already focued, this method does nothing unless 'force' parameter specified as true.
     # @param [Fixnum] x   Percentage of X-axis position.
     # @param [Fixnum] y   Percentage of Y-axis position.
-    # @param [Boolean] force Re-forcus if the camera has already focused.
     # @return [Boolean] +true+ if focus succeeded, +false+ if failed.
     # @example
-    #   # Act tracking focus from the center position, and succeeded to start tracking.
-    #   act_tracking_focus(50, 50)    #=> true
-    def act_tracking_focus(x, y, force: false)
-      return false unless support_group? :TrackingFocus
-      return true  unless needs_focus?(force: force)
+    #   # Initialize
+    #   cam = SonyCameraRemoteAPI::Camera.new
+    #   cam.change_function_to_shoot 'still'
+    #   # Start tracking focus from the center position
+    #   if cam.act_tracking_focus(50, 50)
+    #     th = cam.start_liveview_thread do |img, info|
+    #       info.frames.each do |f|
+    #         # Get tracking focus position from the liveview frame info
+    #         puts "top-left:     (#{f.top_left.x}, #{f.top_left.y})"
+    #         puts "bottom-right: (#{f.bottom_right.x}, #{f.bottom_right.y})"
+    #       end
+    #     end
+    #     th.join
+    #   end
+    def act_tracking_focus(x, y)
+      return false unless support? :TrackingFocus
+      cancel_focus
       set_parameter :TrackingFocus, 'On'
 
+
       x = [[x, 100].min, 0].max
       y = [[y, 100].min, 0].max
       actTrackingFocus(['xPosition': x, 'yPosition': y]).result
@@ -438,14 +467,35 @@ module SonyCameraRemoteAPI
 
     # Return whether the camera has focused or not.
     # @return [Boolean] +true+ if focused, +false+ otherwise.
+    # @see act_focus
+    # @see act_touch_focus
     def focused?
       result = getEvent(false).result
       result[35] && result[35]['focusStatus'] == 'Focused'
     end
 
 
-    # Cancel all type of focuses (half press, touch focus, tracking focus).
+    # Return whether the camera is tracking an object for tracking focus.
+    # @return [Boolean] +true+ if focused, +false+ otherwise.
+    # @see act_tracking_focus
+    def tracking?
+      result = getEvent(false).result
+      result[54] && result[54]['trackingFocusStatus'] == 'Tracking'
+    end
+
+
+    # Cancel focus If camera has been focused.
     # @return [void]
+    # @example
+    #   # Initialize
+    #   cam = SonyCameraRemoteAPI::Camera.new
+    #   cam.change_function_to_shoot 'still', 'Single'
+    #   # Try to focus on upper-middle position.
+    #   if cam.act_tracking_focus(50, 10)
+    #     puts cam.focused?
+    #     cam.capture_still
+    #     puts cam.focused?
+    #   end
     def cancel_focus
       result = getEvent(false).result
       # Canceling tracking/touch focus should be preceded for half-press
@@ -468,15 +518,27 @@ module SonyCameraRemoteAPI
     # Starts a new thread that downloads streamed liveview images.
     # This liveview thread continues downloading unless the one of the following conditions meets:
     # The both hook method is called called each time after a liveview image or frame is downloaded.
-    # @param [String] size      The liveview size.
-    # @param [Fixnum] time      Time in seconds until finishing liveview streaming.
+    # @param [String] size  The liveview size.
+    # @param [Fixnum] time  Time in seconds until finishing liveview streaming.
     # @yield [LiveviewImage, LiveviewFrameInformation] The block called every time a liveview image is downloaded.
     # @yieldparam [LiveviewImage] liveview image of each frame.
     # @yieldparam [LiveviewFrameInformation] liveview frame information of each frame.
     #   If liveview frame information is not supported, nil is always given.
     # @return [Thread] liveview downloading thread object
+    # @example
+    #   # Initialize
+    #   cam = SonyCameraRemoteAPI::Camera.new
+    #   cam.change_function_to_shoot 'still', 'Single'
+    #
+    #   # Start liveview streaming
+    #   th = cam.start_liveview_thread do |img|
+    #     filename = "liveview/#{img.sequence_number}.jpg"
+    #     File.write filename, img.jpeg_data
+    #     puts "wrote #{filename}."
+    #   end
+    #   th.join
     def start_liveview_thread(size: nil, time: nil)
-      liveview_url = init_liveview size: size
+      liveview_url, frame_info_enabled = init_liveview size: size
       log.debug "liveview URL: #{liveview_url}"
 
       th = Thread.new do
@@ -512,14 +574,18 @@ module SonyCameraRemoteAPI
                       log.debug "  sequence  : #{obj.sequence_number}"
                       log.debug "  data_size : #{obj.payload.payload_data_size_wo_padding}"
                       log.debug "  pad_size  : #{obj.payload.padding_size}"
-                      block_time = Benchmark.realtime do
-                        yield(LiveviewImage.new(obj), frame_info)
+                      if frame_info_enabled && frame_info.nil?
+                        log.debug 'frame info is not present. skipping...'
+                      else
+                        block_time = Benchmark.realtime do
+                          yield(LiveviewImage.new(obj), frame_info)
+                        end
+                        log.debug "block time     : #{format('%.2f', block_time*1000)} ms."
                       end
-                      log.info "block time     : #{format('%.2f', block_time*1000)} ms."
                       count += 1
                     when 0x02
                       # When payload is liveview frame information
-                      log.info "frame count = #{obj.payload.frame_count}"
+                      log.debug "frame count = #{obj.payload.frame_count}"
                       if obj.payload.frame_count > 0
                         obj.payload.frame_data.each do |d|
                           log.debug "  category     : #{d.category}"
@@ -573,15 +639,27 @@ module SonyCameraRemoteAPI
     #   Unlike the one of request parameter of getContentList API, you can specify over 100.
     # @return [Array<Hash>]   Content informations
     # @see getContentList API in the API reference.
-    # @example Typical usage:
-    #   change_function_to_transfer
+    # @example
+    #   # Initialize
+    #   cam = SonyCameraRemoteAPI::Camera.new
+    #   cam.change_function_to_transfer
+    #
+    #   # Get all contents
+    #   contents = cam.get_content_list
+    #   # Get still contents created on 2016/8/1
+    #   contents = cam.get_content_list(type: 'still', date: '20160801')
+    #   # Get 3 oldest movie contents
+    #   contents = cam.get_content_list(type: ['movie_xavcs', 'movie_mp4'], sort: 'ascending', count: 3)
     #
-    #   # Get all contents in the storage
-    #   get_content_list
-    #   # Get still contents captured on 2016/8/1
-    #   get_content_list(type: 'still', date: '20160801')
-    #   # Get 3 oldest XAVC-S movie contents
-    #   get_content_list(type: 'movie_xavcs', sort: 'ascending', count: 3)
+    #   # Get filenames and URL of each content
+    #   contents.each do |c|
+    #     filename = c['content']['original'][0]['fileName']
+    #     url = c['content']['original'][0]['url']
+    #     puts "#{filename}, #{url}"
+    #   end
+    #
+    #   # Transfer contents
+    #   cam.transfer_contents(contents)
     def get_content_list(type: nil, date: nil, sort: 'descending', count: nil)
       type = Array(type) if type.is_a? String
 
@@ -633,14 +711,26 @@ module SonyCameraRemoteAPI
     # @param [Fixnum] date_count            Number of dates to get.
     # @param [Fixnum] content_count         Number of contents to get
     # @return [Array< Array<String, Fixnum> >]  Array of pairs of a date in format of 'YYYYMMDD' and a number of contents of the date.
-    # @example Typical usage:
-    #   change_function_to_transfer
+    # @example
+    #   # Initialize
+    #   cam = SonyCameraRemoteAPI::Camera.new
+    #   cam.change_function_to_transfer
+    #
     #   # Get all dates and the number of contents of the date
-    #   get_date_list
-    #   # Get 5 newest dates that contains at least one MP4 and XAVC-S movie content.
-    #   get_date_list(type: ['movie_mp4','movie_xavcs'], date_count: 5)
+    #   dates = cam.get_date_list
+    #   # Get 5 newest dates that contains at least one XAVC-S movie content.
+    #   dates = cam.get_date_list(type: 'movie_xavcs', date_count: 5)
     #   # Get all dates that contains at least 10 still contents.
-    #   get_date_list(type: 'still', content_count: 10)
+    #   dates = cam.get_date_list(type: 'still', content_count: 10)
+    #
+    #   dates.each do |date, count|
+    #     # Get date and its content count
+    #     puts "#{date['title']}, #{count}"
+    #     # Get contents of each date
+    #     contents = cam.get_content_list date: date['title']
+    #     # Transfer contents
+    #     cam.transfer_contents contents
+    #   end
     def get_date_list(type: nil, sort: 'descending', date_count: nil, content_count: nil)
       type = Array(type) if type.is_a? String
 
@@ -677,10 +767,9 @@ module SonyCameraRemoteAPI
     # @param [Array<Hash>] contents     Array of content information, which can be obtained by get_content_list
     # @param [Array<String>] filenames  Array of filename strings
     # @param [String] size              Content size. available values are 'original', 'large', 'small', 'thumbnail'.
-    # @example Typical usage:
-    #   change_function_to_transfer
-    #   contents = get_content_list(type: 'still', count: 10)     # get 10 newest still contents
-    #   transfer_contents(contents)                             # transfer them
+    # @see get_content_list
+    # @see get_date_list
+    # @todo If 'contents' is directory (date), get all contents of the directory.
     def transfer_contents(contents, filenames=[], dir: nil, size: 'original')
       if SIZE_LIST.exclude?(size)
         log.error "#{size} is invalid for size option!"
@@ -730,10 +819,14 @@ module SonyCameraRemoteAPI
     # Delete content(s) of camera storage.
     # @note You have to set camera function to 'Contents Transfer' before calling this method.
     # @param [Array<Hash>] contents array of content hashes, which can be obtained by get_content_list
-    # @example Typical usage:
-    #   change_function_to_transfer
-    #   contents = get_content_list(type: still, count: 10)     # get 10 newest still contents
-    #   delete_contents(contents)                               # delete them
+    # @example
+    #   # Initialize
+    #   cam = SonyCameraRemoteAPI::Camera.new
+    #   cam.change_function_to_transfer
+    #
+    #   # Delete 10 newest still contents
+    #   contents = cam.get_content_list(type: 'still', count: 10)
+    #   cam.delete_contents(contents)
     def delete_contents(contents)
       contents = [contents].compact unless contents.is_a? Array
       count = contents.size
@@ -935,20 +1028,15 @@ module SonyCameraRemoteAPI
     end
 
 
-    def needs_focus?(force: false)
-      if force
-        cancel_focus
-        true
-      else
-        ! focused?
-      end
-    end
-
-
     # Initialize and start liveview
     def init_liveview(size: nil)
       # Enable liveview frame information if available
-      setLiveviewFrameInfo!([{'frameInfo' => true}])
+      rsp = setLiveviewFrameInfo!([{'frameInfo' => true}])
+      if rsp && rsp.result
+        frame_info_enabled = true
+      else
+        frame_info_enabled = false
+      end
 
       if size
         # need to stop liveview when the liveview size is changed
@@ -957,9 +1045,9 @@ module SonyCameraRemoteAPI
         unless available.include?(size)
           raise IllegalArgument, new, "The value '#{size}' is not available for parameter 'LiveviewSize'. current: #{current}, available: #{available}"
         end
-        startLiveviewWithSize([size]).result[0]
+        [ startLiveviewWithSize([size]).result[0], frame_info_enabled ]
       else
-        startLiveview.result[0]
+        [ startLiveview.result[0], frame_info_enabled ]
       end
     end
 
@@ -1041,4 +1129,4 @@ module SonyCameraRemoteAPI
       reconnect_and_retry(retrying: false, &block)
     end
   end
-end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sony_camera_remote_api
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.2.0
 platform: ruby
 authors:
 - kota65535
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-09-19 00:00:00.000000000 Z
+date: 2016-09-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler