ffi-cups2 0.4.0

data/lib/ffi-cups/ffi/cups.rb

@@ -0,0 +1,216 @@
+# cups.h
+# {https://www.cups.org/doc/cupspm.html Programming Manual}
+# {https://github.com/apple/cups/blob/master/cups/cups.h cups.h source}
+
+module Cups
+  extend FFI::Library
+
+  ffi_lib(Cups.libcups)
+
+  # Get the current encryption settings.
+  # @return [Integer] encryption settings
+  # {https://www.cups.org/doc/cupspm.html#cupsEncryption}
+  attach_function 'cupsEncryption', [], :int, blocking: true
+
+  # Check that the option and value are supported by the destination.
+  # @overload cupsCheckDestSupported(pointer, pointer, pointer, string, string)
+  #   @param http [Pointer]
+  #   @param destination [Pointer]
+  #   @param dinfo [Pointer]
+  #   @param option [String]
+  #   @param value [String]
+  #   @return [Integer] 1 if supported, 0 otherwise
+  # {https://www.cups.org/doc/cupspm.html#cupsCheckDestSupported}
+  attach_function 'cupsCheckDestSupported', [:pointer, :pointer, :pointer, :string, :string], :int, blocking: true
+
+  # Check that the option and value are supported by the destination.
+  # @overload cupsFindDestSupported(pointer, pointer, pointer, string)
+  #   @param http [Pointer]
+  #   @param destination [Pointer]
+  #   @param dinfo [Pointer]
+  #   @param option [String]
+  #   @return [p_ipp_attribute_t] opaque pointer to an IPP attribute
+  # {https://www.cups.org/doc/cupspm.html#cupsFindDestSupported}
+  attach_function 'cupsFindDestSupported', [:pointer, :pointer, :pointer, :string], Struct::IppAttribute.by_ref, blocking: true
+
+  # Check that the option and value are supported by the destination.
+  # @overload cupsFindDestReady(pointer, pointer, pointer, string)
+  #   @param http [Pointer]
+  #   @param destination [Pointer]
+  #   @param dinfo [Pointer]
+  #   @param option [String]
+  #   @return [p_ipp_attribute_t] opaque pointer to an IPP attribute
+  # {https://www.cups.org/doc/cupspm.html#cupsFindDestReady}
+  attach_function 'cupsFindDestReady', [:pointer, :pointer, :pointer, :string], Struct::IppAttribute.by_ref, blocking: true
+
+  # Get the supported values/capabilities for the destination.
+  # @overload cupsCopyDestInfo(pointer, pointer)
+  #   @param http [Pointer]
+  #   @param dest [Pointer]
+  #   @return [Pointer] Destination information
+  # {https://www.cups.org/doc/cupspm.html#cupsCopyDestInfo}
+  attach_function 'cupsCopyDestInfo', [:pointer, :pointer], :pointer, blocking: true
+
+  # Get the named destination from the list.
+  # @overload cupsGetDest(string, string, int, pointer)
+  #   @param name [String]
+  #   @param instance [String] instance name or NULL
+  #   @param num_dests [Integer] number of destinations
+  #   @param destinations [Pointer]
+  #   @return [Pointer, NULL] destination or NULL
+  # {https://www.cups.org/doc/cupspm.html#cupsGetDest}
+  attach_function 'cupsGetDest', [:string, :string, :int, :pointer], :pointer, blocking: true
+
+  # Get the list of destinations from the specified server.
+  # @overload cupsGetDests2(pointer, pointer)
+  #   @param pointer [Pointer] to http connection for server or CUPS_HTTP_DEFAULT
+  #   @param pointer [Pointer] to destinations
+  #   @return [Integer] number of destinations
+  # {https://www.cups.org/doc/cupspm.html#cupsGetDests2}
+  attach_function 'cupsGetDests2', [:pointer, :pointer], :int, blocking: true
+
+  # Free the memory used by the list of destinations.
+  # @overload cupsFreeDests(int, pointer)
+  #   @param number [Integer] of destinations
+  #   @param pointer [Pointer] to destinations
+  # {https://www.cups.org/doc/cupspm.html#cupsFreeDests}
+  attach_function 'cupsFreeDests', [:int, :pointer], :void, blocking: true
+
+  # Prints a File
+  # @overload cupsPrintFile(string, string, string, int, pointer)
+  #   @param name [String] of the printer
+  #   @param name [String] of the file
+  #   @param title [String] of the job
+  #   @param number [Integer] of options
+  #   @param pointer [Pointer] to a CupsOptionS struct
+  #   @return [Integer] job number or 0 on error
+  attach_function 'cupsPrintFile', [ :string, :string, :string, :int, :pointer ], :int, blocking: true
+
+  # Prints a file from a specific connection
+  # @overload cupsPrintFile2(pointer, string, string, string, int, pointer)
+  #   @param pointer [Pointer] to an http connection
+  #   @param name [String] of the printer
+  #   @param name [String] of the file
+  #   @param title [String] of the title
+  #   @param number [Integer] of options
+  #   @param pointer [Pointer] to a CupsOptionS struct
+  #   @return [Integer] number of the job or 0 on error
+  attach_function 'cupsPrintFile2', [ :pointer, :string, :string, :string, :int, :pointer ], :int, blocking: true
+
+  # Returns the last error in string format
+  # @return [String] error
+  attach_function 'cupsLastErrorString', [], :string, blocking: true
+
+  # Cancel a job on a destination.
+  # @overload cupsCancelDestJob(string, int)
+  #   @param connection [Pointer] to a http server
+  #   @param pointer [Pointer] to a destination
+  #   @param id [Integer] of the job
+  #   @return [Integer] IPP status
+  # {https://www.cups.org/doc/cupspm.html#cupsCancelDestJob}
+  attach_function 'cupsCancelDestJob', [:string, :int], :void, blocking: true
+
+  # Cancel a job on a destination name
+  # @overload cupsCancelJob(string, int)
+  #   @param name [String] of the destination
+  #   @param id [Ingeger] of the job
+  #   @return [Integer] 1 if canceled, 0 otherwise
+  attach_function 'cupsCancelJob', [:string, :int], :int, blocking: true
+
+  # Cancel a job on a destination
+  # @overload cupsCancelJob2(pointer, string, int)
+  #   @param pointer [Pointer] of the http connection
+  #   @param name [String] of the destination
+  #   @param id [Ingeger] of the job
+  #   @param purge [Integer] 1 to purge, 0 to cancel
+  #   @return [Enum] Cups::Enun::IPP::Status
+  attach_function 'cupsCancelJob2', [:pointer, :string, :int, :int], Cups::Enum::IPP::Status, blocking: true
+
+  # Get the jobs from a connection
+  # @overload cupsGetJobs2(pointer, pointer, string, int, int)
+  #   @param pointer [Pointer] to a http connection object
+  #   @param pointer [Pointer] to Cups::Struct::Job
+  #   @param name [String] of the printer
+  #   @param number [Integer] of type of job (0 == all users, 1 == mine)
+  #   @param which [Integer] jobs (CUPS_WHICHJOBS_ALL, CUPS_WHICHJOBS_ACTIVE, or CUPS_WHICHJOBS_COMPLETED)
+  #   @return [Integer] number of jobs
+  # {https://www.cups.org/doc/cupspm.html#cupsGetJobs2}
+  attach_function 'cupsGetJobs2', [:pointer, :pointer, :string, :int, :int], :int, blocking: true
+
+  # Get the jobs
+  # @overload cupsGetJobs(pointer, string, int, int)
+  #   @param pointer [Pointer] to Cups::Struct::Job to populate
+  #   @param name [String] of the printer
+  #   @param number [Integer] of type of job (0 == all users, 1 == mine)
+  #   @param which [Integer] jobs (CUPS_WHICHJOBS_ALL, CUPS_WHICHJOBS_ACTIVE, or CUPS_WHICHJOBS_COMPLETED)
+  #   @return [Integer] number of jobs
+  attach_function 'cupsGetJobs', [:pointer, :string, :int, :int], :int, blocking: true
+
+  # Free memory used by job data.
+  # @overload cupsFreeJobs(int, pointer)
+  #   @param number [Integer] of jobs
+  #   @param pointer [Pointer] to the first Cups::Struct::Job to free
+  # {https://www.cups.org/doc/cupspm.html#cupsFreeJobs}
+  attach_function 'cupsFreeJobs', [:int, :pointer ], :void, blocking: true
+
+  # Create a job on a destination.
+  # @overload cupsCreateJob(pointer, string, string, int, pointer)
+  #   @param pointer [Pointer] to http connection to server or CUPS_HTTP_DEFAULT
+  #   @param name [String] of the printer
+  #   @param title [String] of the job
+  #   @param number [Integer] of options
+  #   @param pointer [Pointer] to a Cups::Struct::Option object
+  #   @return [Integer] job number or 0 on error
+  attach_function 'cupsCreateJob', [:pointer, :string, :string, :int, :pointer], :int, blocking: true
+
+  # Start a document
+  # @overload cupsStartDocument(pointer, string, int, string, string, int)
+  #   @param pointer [Pointer] to http connection to server or CUPS_HTTP_DEFAULT
+  #   @param name [String] of the printer
+  #   @param id [Integer] of the job
+  #   @param name [String] of the document
+  #   @param mime_type [String] format of the document
+  #   @param number [Integer] of the last document (1 for last document in job, 0 otherwise)
+  #   @return [Cups::Enum::HTTP::Status] HttpStatus
+  # {https://www.cups.org/doc/cupspm.html#submitting-a-print-job}
+  attach_function 'cupsStartDocument', [:pointer, :string, :int, :string, :string, :int], Cups::Enum::HTTP::Status, blocking: true
+
+  # @overload cupsWriteRequestData(pointer, pointer, bytesize)
+  #   @param pointer [Pointer] to http connection to server or CUPS_HTTP_DEFAULT
+  #   @param data [Pointer] in a character string pointer
+  #   @param length [Byte] of data
+  #   @return [Cups::Enum::HTTP::Status] HttpStatus
+  attach_function 'cupsWriteRequestData', [:pointer, :pointer, :size_t], Cups::Enum::HTTP::Status, blocking: true
+
+  # @overload cupsFinishDocument(pointer, string)
+  #   @param pointer [Pointer] to http connection to server or CUPS_HTTP_DEFAULT
+  #   @param name [String] of the printer
+  #   @return [Cups::Enum::IPP::Status] IppStatus
+  attach_function 'cupsFinishDocument', [:pointer, :string], Cups::Enum::IPP::Status, blocking: true
+
+  # Add an option to an option array.
+  # @overload cupsAddOption(string, string, int, pointer)
+  #   @param name [String] of option
+  #   @param value [String] of option
+  #   @param number [Integer] of options
+  #   @param pointer [Pointer] to options
+  #   @return [Integer] number of options
+  # {https://www.cups.org/doc/cupspm.html#cupsAddOption}
+  attach_function 'cupsAddOption', [:string, :string, :int, :pointer], :int, blocking: true
+
+  # Free all memory used by options.
+  # @overload cupsFreeOptions(int, pointer)
+  #   @param number [Integer] of options
+  #   @param pointer [Pointer] to options
+  # {https://www.cups.org/doc/cupspm.html#cupsFreeOptions}
+  attach_function 'cupsFreeOptions', [:int, :pointer], :void, blocking: true
+
+  # Get the destination profile matching the given printer name string.
+  #
+  # @param http [FFI::Pointer] Connection token handle, or NULL to utilize default standard behaviors.
+  # @param name [String] The explicit destination name string targeting verification.
+  # @param instance [String, nil] The specific profile instance context name, or nil for standard configurations.
+  # @return [FFI::Pointer] Explicit pointer targeting a filled out `cups_dest_t` entry structure block, or NULL.
+  attach_function :cupsGetNamedDest, [:pointer, :string, :string], :pointer
+
+end

data/lib/ffi-cups/ffi/http.rb

@@ -0,0 +1,40 @@
+module Cups
+  module Http
+    extend FFI::Library
+    
+    ffi_lib(Cups.libcups)
+
+    # @overload httpConnectEncrypt(string, int, int)
+    #   @param hostname [String]
+    #   @param port [int]
+    #   @param encryption_settings [int]
+    #   @return [Pointer] pointer to a http_t object
+    # @deprecated Please use httpConnect2 instead
+    attach_function 'httpConnectEncrypt', [ :string, :int, :int], :pointer, blocking: true
+
+    # @overload httpClose(pointer)
+    #   @param pointer [Pointer] to a http_t object
+    attach_function 'httpClose', [ :pointer ], :void, blocking: true
+
+    # Get a list of addresses for a hostname.
+    # @overload httpAddrGetList(string, int, string)
+    #   @param hostname [String]
+    #   @param family [Integer]
+    #   @param port [String]
+    #   @return [Pointer] List of addresses or NULL
+    attach_function 'httpAddrGetList', [:string, :int, :string], :pointer, blocking: true
+
+    # Connect to a HTTP server.
+    # @overload httpConnect2(string, int, pointer, int, int, int, int, pointer)
+    #   @param hostname [String]
+    #   @param port [Integer]
+    #   @param addrlist [Pointer] can be NULL
+    #   @param family [Integer] (AF_UNSPEC=0)
+    #   @param encryption_settings [Integer] from Cups.cupsEncryption()
+    #   @param blocking [Integer]
+    #   @param msec [Integer] use 5000 or less
+    #   @param cancel[Pointer] integer pointer, can be NULL
+    #   @return [Pointer] http_t object
+    attach_function 'httpConnect2', [:string, :int, :pointer, :int, :int, :int, :int, :pointer], :pointer, blocking: true
+  end
+end

data/lib/ffi-cups/ffi/ipp_attribute.rb

@@ -0,0 +1,74 @@
+module Cups
+  module IppAttibute
+    extend FFI::Library
+
+    ffi_lib(Cups.libcups)
+
+    typedef Enum::IPP::Tag, :ipp_tag_t
+    typedef Enum::IPP::Res, :ipp_res_t
+
+    # Get the number of values in an attribute.
+    #
+    # @overload ippGetCount(pointer)
+    #   @param pointer [Struct::IppAttibute] to ipp_attribute_t struct
+    #   @return [Integer]
+    attach_function 'ippGetCount', [Struct::IppAttribute.by_ref], :int, blocking: true
+    attach_function 'ippGetGroupTag', [Struct::IppAttribute.by_ref], :ipp_tag_t, blocking: true
+    attach_function 'ippGetValueTag', [Struct::IppAttribute.by_ref], :ipp_tag_t, blocking: true
+    attach_function 'ippGetString', [Struct::IppAttribute.by_ref, :int, :pointer], :string, blocking: true
+    attach_function 'ippGetInteger', [Struct::IppAttribute.by_ref, :int], :int, blocking: true
+
+    # Get the attribute name.
+    #
+    # const char *ippGetName(ipp_attribute_t *attr);
+    # Parameters:
+    #   attr 	IPP attribute
+    # Return Value: Attribute name or NULL for separators
+    attach_function 'ippGetName', [Struct::IppAttribute.by_ref], :string, blocking: true
+
+    #     Get a resolution value for an attribute.
+    #
+    # int ippGetResolution(ipp_attribute_t *attr, int element, int *yres, ipp_res_t *units);
+    # Parameters:
+    #   attr 	IPP attribute
+    #   element 	Value number (0-based)
+    #   yres 	Vertical/feed resolution
+    #   units 	Units for resolution
+    #
+    # Return Value: Horizontal/cross feed resolution or 0
+    #
+    # The element parameter specifies which value to get from 0 to ippGetCount(attr) - 1.
+    attach_function 'ippGetResolution', [Struct::IppAttribute.by_ref, :int, :pointer, :pointer], :int, blocking: true
+
+    #     Get a rangeOfInteger value from an attribute.
+    #
+    # int ippGetRange(ipp_attribute_t *attr, int element, int *uppervalue);
+    # Parameters:
+    #   attr 	IPP attribute
+    #   element 	Value number (0-based)
+    #   uppervalue 	Upper value of range
+    # Return Value:
+    #   Lower value of range or 0
+    #
+    # The element parameter specifies which value to get from 0 to ippGetCount(attr) - 1.
+    attach_function 'ippGetRange', [Struct::IppAttribute.by_ref, :int, :pointer], :int, blocking: true
+
+    #     Return a string corresponding to the enum value.
+    #
+    # const char *ippEnumString(const char *attrname, int enumvalue);
+    # Parameters:
+    #   attrname 	Attribute name
+    #   enumvalue 	Enum value
+    # Return Value: Enum string
+    attach_function 'ippEnumString', [:string, :int], :string, blocking: true
+
+    #     Return the value associated with a given enum string.
+    #
+    # int ippEnumValue(const char *attrname, const char *enumstring);
+    # Parameters:
+    #   attrname 	Attribute name
+    #   enumstring 	Enum string
+    # Return Value: Enum value or -1 if unknown
+    attach_function 'ippEnumValue', [:string, :string], :int, blocking: true
+  end
+end

data/lib/ffi-cups/ffi/ppd.rb

@@ -0,0 +1,65 @@
+module Cups
+  module Ppd
+    extend FFI::Library
+    
+    ffi_lib(Cups.libcups)
+    typedef Struct::PpdFile.by_ref, :ppd_file_t
+
+    # @note This function is deprecated and will be removed in a future release of CUPS.
+    # Get the PPD file for a printer from the default server.
+    # The returned filename is stored in a static buffer and is overwritten with subsequent calls.
+    # The caller "owns" the file that is created and must unlink (delete) the returned filename.
+    #
+    # @param printer [String] The name of the printer destination.
+    # @return [String, nil] A local path string pointing to a temporary file containing the PPD data, or nil on failure.
+    # @see https://www.cups.org/doc/api-ppd.html CUPS PPD API Reference
+    attach_function :cupsGetPPD, [:string], :string
+
+    # @note This function is deprecated and will be removed in a future release of CUPS.
+    # Read a PPD file into a parsed structure memory block.
+    # Opens the specified local filename context and safely allocates a matching internal configuration handle.
+    #
+    # @param filename [String] Local filesystem path layout matching target file boundaries.
+    # @return [FFI::Pointer] Opaque pointer handle to a newly allocated `ppd_file_t` structure, or NULL if it fails.
+    # @see https://www.cups.org/doc/api-ppd.html CUPS PPD API Reference
+    attach_function :ppdOpenFile, [:string], :ppd_file_t
+
+    # @note This function is deprecated and will be removed in a future release of CUPS.
+    # Mark command-line options in a PPD file structure context.
+    # Maps IPP attributes like "media", "sides", or "print-quality" directly onto underlying physical PPD options.
+    #
+    # @param ppd [FFI::Pointer] The parsed `ppd_file_t` structural memory context handler.
+    # @param num_options [Integer] Count of command-line items mapped within option pointers array block.
+    # @param options [FFI::Pointer] Underlying pointer referencing a flat array of `cups_option_t` values.
+    # @return [Integer] Returns 1 if conflicting printer options are uncovered, 0 if mapping succeeds completely.
+    # @see https://refspecs.linuxfoundation.org/LSB_3.2.0/LSB-Printing/LSB-Printing/libcups.cupsmarkoptions.1.html Linux API Reference
+    attach_function :cupsMarkOptions, [:ppd_file_t, :int, :pointer], :int
+
+    # @note This function is deprecated and will be removed in a future release of CUPS.
+    # Free all memory space allocations consumed by a loaded PPD file descriptor layout.
+    # Once closed, pointers referencing any elements inside this memory context are invalidated.
+    #
+    # @param ppd [FFI::Pointer] The parsed `ppd_file_t` structure reference pointer returned via `ppdOpenFile`.
+    # @return [void]
+    # @see https://www.cups.org/doc/api-ppd.html CUPS PPD API Reference
+    attach_function :ppdClose, [:ppd_file_t], :void
+
+    # @note This function is deprecated and will be removed in a future release of CUPS.
+    # Return the very first structured option tracking entry recorded inside the loaded PPD file.
+    # Iterates down through the nested array layout of groups into a linear traversal abstraction loop.
+    #
+    # @param ppd [FFI::Pointer] The parsed `ppd_file_t` structure memory context.
+    # @return [FFI::Pointer] A structural pointer highlighting the first `ppd_option_t` allocation, or NULL if empty.
+    # @see https://www.cups.org/doc/api-ppd.html CUPS PPD API Reference
+    attach_function :ppdFirstOption, [:ppd_file_t], :pointer
+
+    # @note This function is deprecated and will be removed in a future release of CUPS.
+    # Return the next recorded option tracking layout context inside the active linear traversal loop.
+    # Automatically steps into adjacent options or groups tracking across structural array lines.
+    #
+    # @param ppd [FFI::Pointer] The parsed `ppd_file_t` structure memory context.
+    # @return [FFI::Pointer] A structural pointer highlighting the next concurrent `ppd_option_t`, or NULL when finalized.
+    # @see https://www.cups.org/doc/api-ppd.html CUPS PPD API Reference
+    attach_function :ppdNextOption, [:ppd_file_t], :pointer
+  end
+end

data/lib/ffi-cups/job.rb

@@ -0,0 +1,89 @@
+module Cups
+  class Job
+    attr_accessor :id, :title, :printer,
+      :format, :state, :size, :completed_time,
+      :creation_time, :processing_time
+
+    def initialize(id, title, printer)
+      @id = id
+      @title = title
+      @printer = printer
+    end
+
+    # get a updated job's state
+    # @param connection [Cups::Connection]
+    # @return [Symbol] job's state
+    def status(connection=nil)
+      job = self.class.get_job(@id, @printer, -1, connection)
+      self.state = job.state if job
+    end
+
+    # Cancel or purge a job
+    # @param connection [Cups::Connection]
+    def cancel(purge=0, connection=nil)
+      job = self.class.get_job(@id, @printer, -1, connection)
+      r = Cups.cupsCancelJob2(connection, @printer, @id, purge)
+      raise Cups.cupsLastErrorString() if r == 0
+      return r
+    end
+
+    # Get jobs by filter or destination name
+    # @param name [String]
+    # @param filter [Integer] see Constants
+    # @param connection [Cups::Connection]
+    # @return [Array] jobs
+    def self.get_jobs(name=nil, filter=-1, connection=nil)
+      p_jobs = FFI::MemoryPointer.new :pointer
+      cups_jobs = cupsGetJobs2(p_jobs, name, filter, connection)
+      jobs = []
+      cups_jobs.each do |j|
+        job = Cups::Job.new(j[:id].dup, j[:title].dup, j[:dest].dup)
+        job.format = j[:format]
+        job.state = j[:state]
+        job.size = j[:size]
+        job.completed_time = Time.at(j[:completed_time])
+        job.creation_time = Time.at(j[:creation_time])
+        job.processing_time = Time.at(j[:processing_time])
+        jobs.push(job)
+      end
+      return jobs
+    end
+
+    # Get job from id
+    # @param id [Integer]
+    # @param name [String]
+    # @param filter [Integer] see Constants
+    # @param connection [Cups::Connection]
+    # @return [Job] job object
+    def self.get_job(id, name=nil, filter=-1, connection=nil)
+      jobs = get_jobs(name, filter, connection)
+      jobs.each do |j|
+        return j if j.id == id
+      end
+      raise "Job with id: #{id} not found!"
+    end
+
+    private
+    # Wrapper {::Cups#cupsGetJobs2}
+    # @param pointer [Pointer] pointer to the jobs
+    # @param name [String] name of the destination or NULL
+    # @param filter [Integer] see Constants for more filters
+    # @param connection [Cups::Connection]
+    # @return [Array] array of job structs
+    def self.cupsGetJobs2(pointer, name=nil, filter=-1, connection=nil)
+      http = connection.nil? ? nil : connection.httpConnect2
+      num_jobs = Cups.cupsGetJobs2(http, pointer, name, 0, filter)
+      size = Cups::Struct::Job.size
+      jobs = []
+      
+      num_jobs.times do |i|
+        job = Cups::Struct::Job.new(pointer.get_pointer(0) + (size * i))
+        jobs.push(job)
+      end
+
+      Cups::Connection.close(http) if http
+      return jobs
+    end
+  end
+end
+