evolis-premium_sdk 1.0.0

data/lib/evolis/premium_sdk/espf.rb

@@ -0,0 +1,76 @@
+require 'evolis/premium_sdk/sdk_base'
+
+module Evolis
+  module PremiumSdk
+    class Espf < SdkBase
+
+      # Initializes the class and sets SDK host and port
+      #
+      # @param host [String] host or IP for SDK
+      # @param port [String, Fixnum] port for SDK
+      def initialize(host, port)
+        super(host, port, 'ESPF')
+      end
+
+      # Reads the value of a server parameter
+      #
+      # @param key [String] ESPF service parameter
+      # @return [String] current value
+      # @raise [Error::InvalidParamError] if the parameters supplied is not valid
+      def get_param(key)
+        raise Error::InvalidParamError.new key unless valid_param?(key)
+
+        call_rpc('GetParam', {
+            key: key
+        })
+      end
+
+      # Edits the value of server parameter
+      #
+      # @param key [String] ESPF service parameter
+      # @param value [String] value to be set
+      # @return [true] if set as planned
+      # @raise [Error::InvalidParamError] if the parameters supplied is not valid
+      def set_param(key, value)
+        raise Error::InvalidParamError.new "#{key}=#{value}" unless valid_param?(key, value)
+
+        call_rpc('SetParam', {
+            key:  key,
+            data: value
+        })
+      end
+
+      # Checks if the parameters supplied is valid
+      #
+      # @param key [String] ESPF service parameter
+      # @param value [nil, false, String] nil/false when parameter only, String to run check on value
+      # @return [true, false] true when validation succeeds and false when it does not
+      def valid_param?(key, value = nil)
+        params = value ? WRITE_PARAMS : READ_PARAMS.merge(WRITE_PARAMS)
+
+        return false unless params.has_key?(key.to_sym)
+
+        if value
+          return false if value.is_a?(String) && value.empty?
+          return false if params[key.to_sym].is_a?(Array) && !params[key.to_sym].include?(value)
+          return false if params[key.to_sym].is_a?(Regexp) && value !~ params[key.to_sym]
+        end
+
+        return true
+      end
+
+      # Parameters and values valid for setting
+      WRITE_PARAMS = {
+          'ESPFServerManager.port': /^[1-9][0-9]+$/,
+          'ESPFTcpServerConnectionSupervisor.receivetimeout': /^[1-9][0-9]*$/,
+          'ESPFServerManager.tcpenabled': %w[true false]
+      }
+
+      # Parameters valid for reading
+      READ_PARAMS = {
+          'ESPFService.version': true,
+          'ESPFService.requestlanguageversion': true
+      }
+    end
+  end
+end

data/lib/evolis/premium_sdk/print.rb

@@ -0,0 +1,95 @@
+require 'evolis/premium_sdk/sdk_base'
+
+module Evolis
+  module PremiumSdk
+    class Print < SdkBase
+
+      # Initializes the class and sets SDK host and port
+      #
+      # @param host [String] host or IP for SDK
+      # @param port [String, Fixnum] port for SDK
+      def initialize(host, port)
+        super(host, port, 'PRINT')
+      end
+
+      # Initiates a printing session
+      #
+      # @param device [String] printer name
+      # @return [String] session id
+      def begin(device)
+        self.active_session = call_rpc('Begin', {
+            device: device
+        })
+      end
+
+      # Sets the printing parameters
+      #
+      # @param data [String, Array] print settings as "setting=value;setting2=value2"
+      #   or ["setting=value","setting2"="value2"]
+      # @return [true] if set successful
+      # @raise [Error::NoActiveSessionError] if no active session
+      # @raise [Error::InvalidPrintSettingError] on invalid print settings
+      def set(data)
+        raise Error::NoActiveSessionError.new          unless active_session?
+        raise Error::InvalidPrintSettingError.new data unless valid_settings?(data)
+
+        data = data.join(';') if data.is_a?(Array)
+        call_rpc('Set', {
+            session: self.active_session,
+            data:    data
+        })
+      end
+
+      # Defines the graphic data to be printed
+      # @note Can only be run once per card side and panel type
+      #
+      # @param data [String] base64 encoded bitmap information, must start with `base64`
+      # @param face [String] card face to print on, `front` or `back`
+      # @param panel [String] panel type to print, `color`, `resin` or `varnish`
+      # @return [true] if added successful
+      # @raise [Error::NoActiveSessionError] if no active session
+      # @raise [Error::NoSuchFaceError] when face is not recognized
+      # @raise [Error::NoSuchPanelError] on unknown panel type
+      # @raise [Error::Base64FormatError] if data does not validate to base64 format
+      def set_bitmap(data, face = 'front', panel = 'color')
+        raise Error::NoActiveSessionError.new   unless active_session?
+        raise Error::NoSuchFaceError.new face   unless %w[front back].include?(face.downcase)
+        raise Error::NoSuchPanelError.new panel unless %w[color resin varnish].include?(panel.downcase)
+        raise Error::Base64FormatError.new data unless valid_base64?(data)
+
+        call_rpc('SetBitmap', {
+            session: self.active_session,
+            face:    face,
+            panel:   panel,
+            data:    data
+        })
+      end
+
+      # Launches a printing job
+      # @note When calling the `print`, the `get_event` method from the `Supervision` service must be polled on a
+      #   regular basis. If an event is identified, an action must be taken so that the print job can be finalized.
+      #
+      # @return [true] if started printing
+      # @raise [Error::NoActiveSessionError] if no active session
+      def print
+        raise Error::NoActiveSessionError.new unless active_session?
+
+        call_rpc('Print', {
+            session: self.active_session
+        })
+      end
+
+      # Ends the session
+      #
+      # @return [true] if ended session
+      # @raise [Error::NoActiveSessionError] if no active session
+      def end
+        raise Error::NoActiveSessionError.new unless active_session?
+
+        call_rpc('End', {
+            session: self.active_session
+        })
+      end
+    end
+  end
+end

data/lib/evolis/premium_sdk/rpc_client.rb

@@ -0,0 +1,125 @@
+require 'multi_json'
+require 'socket'
+require 'evolis/premium_sdk/error'
+
+module Evolis
+  module PremiumSdk
+    class RpcClient
+      # JSON-RPC version number
+      JSON_RPC_VERSION = '2.0'
+
+      # @return [Hash] the last request made to the API
+      attr_reader :request
+
+      # @return [Hash] the last response from API
+      attr_reader :response
+
+      # @return [String] randomly generated number between 10 and 12 digits
+      def self.make_id
+        String rand(10**12)
+      end
+
+      # Initializes the class and sets API host and port
+      #
+      # @param host [String] host or IP for API
+      # @param port [String, Fixnum] port for API
+      def initialize(host, port)
+        @host = host
+        @port = port
+      end
+
+      # Make call to API and process response
+      #
+      # @param method [String] request method
+      # @param args [Hash, Array, String] data sent as request
+      # @return [Hash, Array, String] the data in the format received from server
+      # @raise [Error::InvalidJSON] if data from server is not valid JSON
+      def call(method, args)
+        resp = send_single_request(method.to_s, args)
+
+        begin
+          data = MultiJson.decode(resp)
+        rescue
+          raise Error::InvalidJSON.new(resp)
+        end
+
+        return process_single_response(data)
+
+      rescue Exception, StandardError => e
+        e.extend(Error) unless e.is_a?(Error)
+        raise e
+      end
+
+      # The method that does the actual sending of data to API
+      #
+      # @param method [String] request method
+      # @param args [Hash, Array, String] data sent as request
+      # @return [Hash] response from server in JSON format (Hash)
+      # @raise [Error::InvalidResponse] on empty response from server, or no response
+      def send_single_request(method, args)
+        @request = MultiJson.encode({
+                                        jsonrpc:  JSON_RPC_VERSION,
+                                        method:   method,
+                                        params:   args,
+                                        id:       self.class.make_id
+                                    })
+
+        begin
+          socket = TCPSocket.open(@host, @port)
+          socket.write(@request)
+          socket.close_write
+          resp = socket.read
+        ensure
+          socket.close if socket
+        end
+
+        raise Error::InvalidResponse.new if resp.nil? || resp.empty?
+
+        return @response = resp
+      end
+
+      # Process and validate response from API
+      #
+      # @param data [Hash] response from API
+      # @return [Hash, Array, String] from result key in response
+      # @raise [Error::InvalidResponse] if response does not validate
+      # @raise [Error::ServerError] on response with error key
+      def process_single_response(data)
+        raise Error::InvalidResponse.new unless valid_response?(data)
+
+        if !!data['error']
+          code = data['error']['code']
+          msg = data['error']['message']
+          raise Error::ServerError.new(code, msg)
+        end
+
+        return data['result']
+      end
+
+      # Validates tje response from API
+      #
+      # @param data [Hash] response from API
+      # @return [true, false] true if valid or false when invalid
+      def valid_response?(data)
+        return false unless data.is_a?(Hash)
+        return false if data['jsonrpc'] != JSON_RPC_VERSION
+        return false unless data.has_key?('id')
+        return false if data.has_key?('error') && data.has_key?('result')
+
+        if data.has_key?('error')
+          if !data['error'].is_a?(Hash) || !data['error'].has_key?('code') || !data['error'].has_key?('message')
+            return false
+          end
+
+          if !data['error']['code'].is_a?(Fixnum) || !data['error']['message'].is_a?(String)
+            return false
+          end
+        end
+
+        return true
+      rescue
+        return false
+      end
+    end
+  end
+end

data/lib/evolis/premium_sdk/sdk_base.rb

@@ -0,0 +1,153 @@
+require 'evolis/premium_sdk/rpc_client'
+
+module Evolis
+  module PremiumSdk
+    class SdkBase
+      # @return [String] returns the active session
+      attr_accessor :active_session
+
+      # Initalizes the class, sets default options
+      #
+      # @param host [String] host or ip to Premium SDK API
+      # @param port [String, Fixnum] port to Premium SDK API
+      # @param service [String] servicename, used only internally (e.g. CMD or PRINT)
+      def initialize(host, port, service)
+        @rpc = RpcClient.new(host, port)
+        @service = service
+      end
+
+      # Makes the call to the API and returns results
+      #
+      # @param method [String] method name for the service
+      # @param args [String] arguments and parameters to send to service
+      # @return [String] returns result parameter from the response
+      # @return [true] if result is "OK"
+      def call_rpc(method, args)
+        method = sanitize_parameters(method)
+        args   = sanitize_parameters(args)
+        resp   = @rpc.call("#{@service}.#{method}", args)
+
+        return true if resp == 'OK'
+        return resp
+      end
+
+      # Method to lookup the full response
+      # @return [Hash] full json response
+      # @return [nil] before first response
+      def response
+        @rpc.response
+      end
+
+      # Method to lookup the full request
+      # @return [Hash] full json request
+      # @return (nil) before first request
+      def request
+        @rpc.request
+      end
+
+      # Settings and their values allowed to be used when getting and setting settings for print
+      SETTINGS = {
+          GDuplexMode: %w[SIMPLEX DUPLEX_CC DUPLEX_CM DUPLEX_MC DUPLEX_MM],
+          GInputTray: %w[FEEDER AUTO MANUAL PRINTER],
+          GOutputTray: %w[HOPPER REAR PRINTER],
+          GRejectBox: %w[DEFAULTREJECT HOPPER PRINTER],
+          GRibbonType: %w[RC_YMCKO RC_YMCKOS RC_YMCKOK RC_YMCKOKOS RM_KO RM_KBLACK RM_KWHITE RM_KRED RM_KGREEN RM_KBLUE RM_KSCRATCH RM_KMETALSILVER RM_KMETALGOLD RM_KSIGNATURE RM_KWAX RM_KPREMIUM RM_HOLO],
+          GShortPanelManagement: %w[AUTO CUSTOM OFF],
+          GSmoothing: %w[STDSMOOTH ADVSMOOTH NOSMOOTH],
+          IGStrictPageSetup: %w[ON OFF],
+          FBlackManagement: %w[NOBLACKPOINT ALLBLACKPOINT TEXTINBLACK],
+          BBlackManagement: %w[NOBLACKPOINT ALLBLACKPOINT TEXTINBLACK],
+          FColorBrightness: (1..20).to_a.map! { |i| "VAL#{i}" },
+          BColorBrightness: (1..20).to_a.map! { |i| "VAL#{i}" },
+          FColorContrast: (1..20).to_a.map! { |i| "VAL#{i}" },
+          BColorContrast: (1..20).to_a.map! { |i| "VAL#{i}" },
+          FHalftoning: %w[THRESHOLD FLOYD DITHERING CLUSTERED_DITHERING],
+          BHalftoning: %w[THRESHOLD FLOYD DITHERING CLUSTERED_DITHERING],
+          FMonochromeContrast: (1..20).to_a.map! { |i| "VAL#{i}" },
+          BMonochromeContrast: (1..20).to_a.map! { |i| "VAL#{i}" },
+          FOverlayContrast: (1..20).to_a.map! { |i| "VAL#{i}" },
+          BOverlayContrast: (1..20).to_a.map! { |i| "VAL#{i}" },
+          FOverlayManagement: %w[NOVARNISH FULLVARNISH BMPVARNISH],
+          BOverlayManagement: %w[NOVARNISH FULLVARNISH BMPVARNISH],
+          FPageRotate180: %w[ON OFF],
+          BPageRotate180: %w[ON OFF],
+          GMagCoercivity: %w[OFF LOCO HICO],
+          GMagT1Encoding: %w[ISO1 ISO2 ISO3 SIPASS C2 JIS2 C4 NONE],
+          GMagT2Encoding: %w[ISO1 ISO2 ISO3 SIPASS C2 JIS2 C4 NONE],
+          GMagT3Encoding: %w[ISO1 ISO2 ISO3 SIPASS C2 JIS2 C4 NONE],
+          Track1Data: String,
+          Track2Data: String,
+          Track3Data: String,
+          Resolution: %w[DPI300 DPI600300 DPI1200300],
+          IShortPanelShift: /^[0-9]+$/,
+          Passthrough: String,
+          RawData: String,
+      }
+
+      # Checks if settings supplied are valid
+      #
+      # @param settings [String, Array] setting and value,
+      #   as "setting=value;setting2=value2" or ["setting=value","setting2=value2"]
+      # @param key_only [true, false] used for checking if only setting without value. Set to true for setting only.
+      # @return [true, false] true if valid settings, false if not
+      def valid_settings?(settings, key_only = false)
+        settings = settings.split(';') if settings.include?(';')
+        settings = [settings] unless settings.is_a?(Array)
+
+        settings.each do |pair|
+          if key_only
+            setting = pair
+          else
+            return false unless pair.include?('=')
+            setting, value = pair.split('=')
+          end
+
+          return false unless SETTINGS.has_key?(setting.to_sym)
+
+          unless key_only
+            return false if !value
+            return false if value.is_a?(String) && value.empty?
+            return false if SETTINGS[setting.to_sym].is_a?(Array) && !SETTINGS[setting.to_sym].include?(value)
+            return false if SETTINGS[setting.to_sym].is_a?(Class) && !value.is_a?(SETTINGS[setting.to_sym])
+            return false if SETTINGS[setting.to_sym].is_a?(Regexp) && value.is_a?(String) && value !~ SETTINGS[setting.to_sym]
+          end
+
+          return true
+        end
+      end
+
+      # Basic checking for valid base64 string, as used in the SDK
+      #
+      # @param string [String] the base64 encoded data
+      # @return [true, false] true if valid base64 string, false if not
+      def valid_base64?(string)
+        return false unless string.is_a?(String)
+        return false unless string.start_with?('base64:')
+
+        return true
+      end
+
+      # Checks if there is an active session
+      # @return [true, false] true if exist, false if not
+      def active_session?
+        return false unless self.active_session
+        return false if self.active_session == nil
+        return false unless self.active_session.is_a?(String)
+        return false if self.active_session.empty?
+
+        return true
+      end
+
+      # Sanitizes parameters so they're not anything other than a String
+      #
+      # @param param [Any type] parameters to be sanitized
+      # @return [Hash, Array, String] Hash and Array get sanitized and returned as Hash and Array,
+      #   everything else becomes a String
+      def sanitize_parameters(param)
+        return param.map { |p| String(p) }                      if param.is_a?(Array)
+        return param.map { |k, v| [String(k), String(v)] }.to_h if param.is_a?(Hash)
+        return String(param)
+      end
+    end
+  end
+end