sony_camera_remote_api 0.1.1

data/lib/sony_camera_remote_api/camera_api.rb

@@ -0,0 +1,199 @@
+require 'sony_camera_remote_api/raw_api'
+require 'sony_camera_remote_api/camera_api_group'
+require 'forwardable'
+
+module SonyCameraRemoteAPI
+
+  # Camera API layer class, which enables us to handle camera APIs more friendly.
+  class CameraAPIManager
+    extend Forwardable
+    include Logging
+
+    # Default timeout for waiting camera API becomes available
+    DEFAULT_API_CALL_TIMEOUT = 8
+    # 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?
+
+
+    # Create CameraAPIManager object.
+    # @param [Hash] endpoints
+    # @param [Proc] reconnect_by
+    def initialize(endpoints, reconnect_by: nil)
+      @raw_api_manager = RawAPIManager.new endpoints
+      @api_group_manager = CameraAPIGroupManager.new self
+      @reconnect_by = reconnect_by
+    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
+    # @return [Hash]  Response of API
+    def getEvent(params = [true], **opts)
+      params = [params] unless params.is_a? Array
+      name, service, id, version = @raw_api_manager.search_method(__method__, **opts)
+      response = nil
+      reconnect_and_retry do
+        if params[0]
+          response = @raw_api_manager.call_api_async(service, name, params, id, version, opts[:timeout])
+        else
+          response = @raw_api_manager.call_api(service, name, params, id, version)
+        end
+      end
+      response
+    end
+
+
+    # getAvailableApiList API.
+    # @return [Hash]  Response of API
+    def getAvailableApiList(params = [], **opts)
+      name, service, id, version = @raw_api_manager.search_method(__method__, **opts)
+      reconnect_and_retry do
+        @raw_api_manager.call_api(service, name, params, id, version)
+      end
+    end
+
+
+    # Wait until 'getEvent' result response meets the specified condition.
+    # This method can be used to wait after calling APIs that change any camera parameters, such as 'setCameraFunction'.
+    # @yield [Array<Hash>] The block that returns +true+ or +false+ based on the condition of the response of getEvent
+    # @yieldparam [Array<Hash>] 'result' element in the response of getEvent
+    # @param [Fixnum] timeout   Timeout in seconds for changing parameter
+    # @param [Boolean] polling  This method has 3 patterns to handle long polling flag by 'polling' parameter.
+    #   * default : The first getEvent call doesn't use long polling, but then later always use long polling.
+    #   * polling = true  : Always use long polling in getEvent call
+    #   * polling = false : Never use long polling in getEvent call
+    # @raise EventTimeoutError
+    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
+      poll = polling.nil? ? false : polling
+      while true do
+        response = get_event_both(poll, timeout: timeout)
+        begin
+          break if yield(response.result)
+        rescue StandardError => e
+          # Catch all exceptions raised by given block, e.g. NoMethodError of '[]' for nil class.
+        end
+        sleep 0.1
+        if timeout
+          raise EventTimeoutError, "Timeout expired: #{timeout} sec." if Time.now - start_time > timeout
+        end
+        poll = polling.nil? ? true : polling
+        log.debug "Waiting for #{block} returns true..."
+      end
+      log.debug "OK. (#{format('%.2f', Time.now-start_time)} sec.)"
+      # pp response['result']
+      response['result']
+    end
+
+
+    # Ghost method, which handles almost API calls.
+    # If Camera API (servie type == camera) is called, call_api_safe() is used.
+    # @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
+    def method_missing(method, params = [], *args, **opts)
+      ignore_error = true if method.to_s.end_with? '!'
+      method = method.to_s.delete('!').to_sym
+      params = [params] unless params.is_a? Array
+      response = nil
+      reconnect_and_retry do
+        begin
+          name, service, id, version = @raw_api_manager.search_method(method, **opts)
+          if service == 'camera' || name == ''
+            if opts[:timeout]
+              response = call_api_safe(service, name, params, id, version, opts[:timeout], **opts)
+            else
+              response = call_api_safe(service, name, params, id, version, **opts)
+            end
+          else
+            response = @raw_api_manager.call_api(service, name, params, id, version)
+          end
+        rescue APINotSupported, APINotAvailable, IllegalArgument, HTTPClient::BadResponseError => e
+          if ignore_error
+            return nil
+          else
+            raise e
+          end
+        end
+      end
+      response
+    end
+
+
+    private
+
+    # Call getEvent without polling if getEvent with polling failed.
+    def get_event_both(poll, timeout: nil)
+      getEvent(poll, timeout: timeout)
+    rescue EventTimeoutError => e
+      getEvent(false)
+    end
+
+
+    # Execute given block. And if the block raises Error caused by Wi-Fi disconnection,
+    # Reconnect by @reconnect_by Proc and retry the given block.
+    # @param [Boolean] retrying If true, retry given block. If false, return immediately after reconnection.
+    # @param [Fixnum] num       Number of retry.
+    # @param [Proc] hook        Hook method called after reconnection.
+    def reconnect_and_retry(retrying: true, num: 1, hook: nil)
+      yield
+    rescue HTTPClient::TimeoutError, Errno::EHOSTUNREACH, Errno::ECONNREFUSED => e
+      retry_count ||= 0
+      raise e if @reconnect_by.nil? || retry_count >= num
+      log.error "#{e.class}: #{e.message}"
+      log.error 'The camera seems to be disconnected! Reconnecting...'
+      unless @reconnect_by.call
+        log.error 'Failed to reconnect.'
+        raise e
+      end
+      log.error 'Reconnected.'
+      @raw_api_manager.reset_connection
+      # For cameras that use Smart Remote Control app.
+      startRecMode! timeout: 0
+      return unless retrying
+
+      if hook
+        unless hook.call
+          log.error 'Before-retry hook failed.'
+          raise e
+        end
+      end
+      retry_count += 1
+      retry
+    end
+
+  end
+end

data/lib/sony_camera_remote_api/camera_api_group.rb

@@ -0,0 +1,281 @@
+require 'sony_camera_remote_api/camera_api'
+
+module SonyCameraRemoteAPI
+  # Camera API group sublayer class, which is included in Camera API layer class.
+  # This class handles API groups that get/set specific parameters of the camera.
+  class CameraAPIGroupManager
+    include Logging
+    include Utils
+
+    # APIGroup class.
+    # One API group object represents one camera parameter.
+    class APIGroup
+
+      # Create API group object.
+      # @param [Symbol] param_symbol      API Group name
+      # @param [Proc] supported_accessor  Get the supported values from getSupportedXXX raw response.
+      # @param [Proc] available_accessor  Get the available values from getAvailableXXX raw response.
+      # @param [Proc] get_accessor        Get the current value from getXXX raw response.
+      # @param [Proc] set_accessor        Set given value to setXXX request.
+      # @param [Proc] start_condition     Wait until given condition before accessing parameter.
+      # @param [Proc] preprocess_value    Convert given value and arguments into the internal format to be compared.
+      # @param [Proc] check_equality      Compare given value and current one to judge whether new value should be set or not.
+      # @param [Proc] check_availability  Compare given value and avialable ones to judge whether new value is available.
+      # @param [Proc] end_condition       Wait until given condition after changing parameter.
+      def initialize(param_symbol, supported_accessor, available_accessor, get_accessor, set_accessor,
+                     start_condition: nil,
+                     preprocess_value: nil,
+                     check_equality: method(:default_check_equality),
+                     check_availability: method(:default_check_availability),
+                     end_condition: nil
+                     )
+        @param_str = param_symbol.to_s
+        @supported = ('getSupported' + @param_str).to_sym
+        @supported_accessor = supported_accessor
+        @available = ('getAvailable' + @param_str).to_sym
+        @available_accessor = available_accessor
+        @get = ('get' + @param_str).to_sym
+        @get_accessor = get_accessor
+        @set = ('set' + @param_str).to_sym
+        @set_accessor = set_accessor
+        @start_condition = start_condition
+        @preprocess_value = preprocess_value
+        @check_equality = check_equality
+        @check_availability = check_availability
+        @end_condition = end_condition
+      end
+
+      # Get suported values of this parameter through the defined accessor
+      # @param [CameraAPIManager] api_manager
+      # @param [Array<Hash>] condition
+      def supported_values(api_manager, condition, **opts)
+        raw_result = api_manager.send(@supported, **opts)['result']
+        { supported: @supported_accessor.call(raw_result, condition) }
+      end
+
+      # Get available values of this parameter through the defined accessor
+      # @param [CameraAPIManager] api_manager
+      # @param [Array<Hash>] condition
+      def available_values(api_manager, condition, **opts)
+        raw_result = api_manager.send(@available, **opts)['result']
+        { available: @available_accessor.call(raw_result, condition) }
+      end
+
+      # Get current values of this parameter through the defined accessor
+      def current_value(api_manager, condition, **opts)
+        raw_result = api_manager.send(@get, **opts)['result']
+        { current: @get_accessor.call(raw_result, condition) }
+      end
+
+      # If start_condition is defined, wait until the condition satisfies.
+      # @param [CameraAPIManager] api_manager
+      def start_condition(api_manager, **opts)
+        if @start_condition
+          api_manager.wait_event { |r| @start_condition.call(r) }
+        end
+      end
+
+      # Preprocess given value and arguments to the value which can be compared.
+      # @param [Object] value
+      # @param [Array] args
+      # @param [Array<Hash>] condition
+      def preprocess_value(value, args, condition)
+        if @preprocess_value
+          @preprocess_value.call(value, args, condition)
+        else
+          value
+        end
+      end
+
+      def is_available?(value, available_values, condition)
+        @check_availability.call(value, available_values, condition)
+      end
+
+
+      def eq_current?(value, current_value, condition)
+        @check_equality.call(value, current_value, condition)
+      end
+
+      # @param [CameraAPIManager] api_manager
+      # @param [Object] value
+      # @param [Array] availables
+      # @param [Array<Hash>] condition
+      def set_value(api_manager, value, availables, condition)
+        api_manager.send(@set, @set_accessor.call(value, availables, condition))
+        if @end_condition
+          condition_block = (@end_condition.curry)[value]
+          api_manager.wait_event &condition_block
+        end
+        { current: value }
+      end
+
+      private
+
+      def default_check_availability(value, available_values, condition)
+        available_values.include? value
+      end
+
+      def default_check_equality(value, current_value, condition)
+        current_value == value
+      end
+
+    end
+
+
+    # Create CameraAPIManager object.
+    # @param [CameraAPIManager] camera_api_manager
+    def initialize(camera_api_manager)
+      @api_manager = camera_api_manager
+      @api_groups = make_api_group_list camera_api_manager.apis
+    end
+
+
+    # Get current value of a camera parameter.
+    # @param [Symbol] group_name Parameter name
+    # @return [Object] current value
+    # @raise APINotSupported, APINotAvailable, IllegalArgument
+    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
+    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.
+    # @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
+    def get_parameter(group_name, available: true, supported: true, **opts)
+      result = { current: nil, available: [], supported: [] }
+      begin
+        grp = search_group group_name
+      rescue APIForbidden, APINotSupported => e
+        raise e.class.new(result), e.message
+      end
+      condition = grp.start_condition(@api_manager)
+      begin
+        result.merge! grp.current_value(@api_manager, condition, **opts)
+      rescue APINotAvailable, IllegalArgument => e
+        raise e.class.new(result), e.message
+      end
+      begin
+        # Timeout is set shorter than usual for getting hardware-affected parameter.
+        result.merge! grp.available_values(@api_manager, condition, timeout: 1, **opts) if available
+        result.merge! grp.supported_values(@api_manager, condition, timeout: 1, **opts) if supported
+      rescue APINotAvailable, IllegalArgument => e
+        # Comes here if the parameter is hardware-affected.
+      end
+      result
+    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.
+    def get_parameter!(group_name, **opts)
+      get_parameter(group_name, **opts)
+    rescue APIForbidden, APINotSupported, APINotAvailable, IllegalArgument => e
+      log.error e.message
+      e.object
+    rescue HTTPClient::BadResponseError => e
+      log.error e.message
+    end
+
+
+    # Set a 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
+    def set_parameter(group_name, value, *args, **opts)
+      result = { current: nil, available: [], old: nil }
+      begin
+        grp = search_group group_name
+      rescue APIForbidden, APINotSupported => e
+        raise e.class.new(result), e.message
+      end
+
+      condition = grp.start_condition(@api_manager)
+      begin
+        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
+        # If not, check if the value is available.
+        result.merge! grp.available_values(@api_manager, condition, **opts)
+        if grp.is_available? value, result[:available], condition
+          # Save current value and call set API.
+          result[:old] = result[:current]
+          result.merge! grp.set_value(@api_manager, value, result[:available], condition)
+        else
+          # If the value is not available, raise error.
+          raise IllegalArgument.new, "The value '#{value}' is not available for parameter '#{group_name}'. current: #{result[:current]}, available: #{result[:available]}"
+        end
+      rescue APINotAvailable, IllegalArgument => e
+        raise e.class.new(result), e.message
+      end
+      result
+    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.
+    def set_parameter!(group_name, value, **opts)
+      set_parameter(group_name, value, **opts)
+    rescue APIForbidden, APINotSupported, APINotAvailable, IllegalArgument => e
+      log.error e.message
+      e.object
+    rescue HTTPClient::BadResponseError => e
+      log.error e.message
+    end
+
+
+    # Returns whether the parameter is supported or not.
+    # @return [Boolean] +true+ if the parameter is supported, false otherwise.
+    def support_group?(group_name)
+      @api_groups.key? group_name
+    end
+
+
+    private
+
+    # Make API Group hash list from APIInfo list.
+    # @param [Array<APIInfo>] apis
+    # @return [Hash<Symbol, APIGroup>]
+    def make_api_group_list(apis)
+      api_names = apis.values.map { |a| a.name }
+      setters = api_names.select { |k| k =~ /^getAvailable/ }
+      api_groups = {}
+      setters.map do |s|
+        group_name = s.gsub(/^getAvailable/, '')
+        members = [ "get#{group_name}", "getAvailable#{group_name}", "getSupported#{group_name}" ]
+        result = members.map { |m| api_names.include?(m) }
+        api_groups[group_name.to_sym] = @@api_groups_all[group_name.to_sym] if result.all?
+      end
+      api_groups
+    end
+
+    # @param [Symbol] group_name
+    def search_group(group_name)
+      if support_group? group_name
+        return @api_groups[group_name]
+      else
+        raise APINotSupported.new, "Parameter '#{group_name}' is not supported!"
+      end
+    end
+
+    require 'sony_camera_remote_api/camera_api_group_def'
+
+  end
+end