Interface Cups

All Superinterfaces:
Library
public interface Cups extends Library
Bindings for the CUPS (Common UNIX Printing System) API defined in <cups/cups.h>.

CUPS provides a portable printing layer for UNIX-based operating systems. It uses the Internet Printing Protocol (IPP) as the basis for managing print jobs, queues, and printers.

Reference: CUPS Programming Manual

See Also:

  • Field Details

    • INSTANCE

      static final Cups INSTANCE

    • IPP_PRINTER_IDLE

      static final int IPP_PRINTER_IDLE
      The printer is idle and ready to accept jobs.
      See Also:

    • IPP_PRINTER_PROCESSING

      static final int IPP_PRINTER_PROCESSING
      The printer is currently processing a job.
      See Also:

    • IPP_PRINTER_STOPPED

      static final int IPP_PRINTER_STOPPED
      The printer is stopped (paused or has an error).
      See Also:

    • CUPS_PRINTER_CLASS

      static final int CUPS_PRINTER_CLASS
      Printer class (group of printers).
      See Also:

    • CUPS_PRINTER_REMOTE

      static final int CUPS_PRINTER_REMOTE
      Remote printer or class.
      See Also:

    • CUPS_PRINTER_BW

      static final int CUPS_PRINTER_BW
      Can do B&W printing.
      See Also:

    • CUPS_PRINTER_COLOR

      static final int CUPS_PRINTER_COLOR
      Can do color printing.
      See Also:

    • CUPS_PRINTER_DUPLEX

      static final int CUPS_PRINTER_DUPLEX
      Can do two-sided printing.
      See Also:

    • CUPS_PRINTER_STAPLE

      static final int CUPS_PRINTER_STAPLE
      Can staple output.
      See Also:

    • CUPS_PRINTER_COPIES

      static final int CUPS_PRINTER_COPIES
      Can do copies in hardware.
      See Also:

    • CUPS_PRINTER_COLLATE

      static final int CUPS_PRINTER_COLLATE
      Can quickly collate copies.
      See Also:

    • CUPS_PRINTER_PUNCH

      static final int CUPS_PRINTER_PUNCH
      Can punch output.
      See Also:

    • CUPS_PRINTER_COVER

      static final int CUPS_PRINTER_COVER
      Can cover output.
      See Also:

    • CUPS_PRINTER_BIND

      static final int CUPS_PRINTER_BIND
      Can bind output.
      See Also:

    • CUPS_PRINTER_SORT

      static final int CUPS_PRINTER_SORT
      Can sort output.
      See Also:

    • CUPS_PRINTER_SMALL

      static final int CUPS_PRINTER_SMALL
      Can print on Letter/Legal/A4-size media.
      See Also:

    • CUPS_PRINTER_MEDIUM

      static final int CUPS_PRINTER_MEDIUM
      Can print on Tabloid/B/C/A3/A2-size media.
      See Also:

    • CUPS_PRINTER_LARGE

      static final int CUPS_PRINTER_LARGE
      Can print on D/E/A1/A0-size media.
      See Also:

    • CUPS_PRINTER_VARIABLE

      static final int CUPS_PRINTER_VARIABLE
      Can print on rolls and custom-size media.
      See Also:

    • CUPS_PRINTER_DEFAULT

      static final int CUPS_PRINTER_DEFAULT
      Default printer on network.
      See Also:

    • CUPS_PRINTER_FAX

      static final int CUPS_PRINTER_FAX
      Fax queue.
      See Also:

    • CUPS_PRINTER_REJECTING

      static final int CUPS_PRINTER_REJECTING
      Printer is rejecting jobs.
      See Also:

    • CUPS_PRINTER_NOT_SHARED

      static final int CUPS_PRINTER_NOT_SHARED
      Printer is not shared. @since CUPS 1.2
      See Also:

    • CUPS_PRINTER_AUTHENTICATED

      static final int CUPS_PRINTER_AUTHENTICATED
      Printer requires authentication. @since CUPS 1.2
      See Also:

    • CUPS_PRINTER_COMMANDS

      static final int CUPS_PRINTER_COMMANDS
      Printer supports maintenance commands. @since CUPS 1.2
      See Also:

    • CUPS_PRINTER_DISCOVERED

      static final int CUPS_PRINTER_DISCOVERED
      Printer was discovered (not configured locally). @since CUPS 1.2
      See Also:

    • IPP_JSTATE_PENDING

      static final int IPP_JSTATE_PENDING
      Job is waiting to be printed.
      See Also:

    • IPP_JSTATE_HELD

      static final int IPP_JSTATE_HELD
      Job has been held for printing.
      See Also:

    • IPP_JSTATE_PROCESSING

      static final int IPP_JSTATE_PROCESSING
      Job is currently printing.
      See Also:

    • IPP_JSTATE_STOPPED

      static final int IPP_JSTATE_STOPPED
      Job has been stopped.
      See Also:

    • IPP_JSTATE_CANCELED

      static final int IPP_JSTATE_CANCELED
      Job has been canceled.
      See Also:

    • IPP_JSTATE_ABORTED

      static final int IPP_JSTATE_ABORTED
      Job has been aborted due to an error.
      See Also:

    • IPP_JSTATE_COMPLETED

      static final int IPP_JSTATE_COMPLETED
      Job has completed successfully.
      See Also:

    • CUPS_WHICHJOBS_ALL

      static final int CUPS_WHICHJOBS_ALL
      Return all jobs regardless of state.
      See Also:

    • CUPS_WHICHJOBS_ACTIVE

      static final int CUPS_WHICHJOBS_ACTIVE
      Return active (pending, processing, held) jobs.
      See Also:

    • CUPS_WHICHJOBS_COMPLETED

      static final int CUPS_WHICHJOBS_COMPLETED
      Return completed (stopped, canceled, aborted, completed) jobs.
      See Also:

  • Method Details

    • cupsGetDests

      int cupsGetDests(PointerByReference dests)
      Gets all available destinations (printers and classes) from the default server.

      The returned list includes options containing printer attributes. Use cupsGetOption(String, int, Pointer) to retrieve specific attribute values from a destination's options.

      Use cupsFreeDests(int, Pointer) to free the returned destination list.

      Parameters:
      dests - pointer to receive the destination array
      Returns:
      the number of destinations
      See Also:

    • cupsGetDests2

      int cupsGetDests2(Pointer http, PointerByReference dests)
      Gets all available destinations (printers and classes) from the specified server.

      Pass null for the http parameter to use the default server connection (equivalent to CUPS_HTTP_DEFAULT).

      Use cupsFreeDests(int, Pointer) to free the returned destination list.

      Parameters:
      http - connection to server or null for the default connection
      dests - pointer to receive the destination array
      Returns:
      the number of destinations
      Since:
      CUPS 1.1.21
      See Also:

    • cupsFreeDests

      void cupsFreeDests(int num_dests, Pointer dests)
      Frees the memory used by a destination array returned by cupsGetDests(PointerByReference) or cupsGetDests2(Pointer, PointerByReference).
      Parameters:
      num_dests - number of destinations
      dests - pointer to the destination array
      See Also:

    • cupsGetDest

      Pointer cupsGetDest(String name, String instance, int num_dests, Pointer dests)
      Gets the named destination from a destination list.

      Use cupsGetDests(PointerByReference) or cupsGetDests2(Pointer, PointerByReference) to get the list, then call this function to find a specific destination by name.

      Parameters:
      name - destination name or null for the default destination
      instance - instance name or null
      num_dests - number of destinations in the list
      dests - pointer to the destination array
      Returns:
      pointer to the matching destination or null if not found
      See Also:

    • cupsGetNamedDest

      Pointer cupsGetNamedDest(Pointer http, String name, String instance)
      Gets options for the named destination, optimized for retrieving a single destination.

      This function is preferred over cupsGetDests2(Pointer, PointerByReference) followed by cupsGetDest(String, String, int, Pointer) when you know the destination name or want the default destination.

      The returned destination must be freed using cupsFreeDests(int, Pointer) with a num_dests value of 1.

      Parameters:
      http - connection to server or null for the default connection
      name - destination name or null for the default destination
      instance - instance name or null
      Returns:
      pointer to the destination or null if not found
      Since:
      CUPS 1.4
      See Also:

    • cupsGetDefault

      String cupsGetDefault()
      Gets the default printer name.
      Returns:
      the default printer name or null if no default is set
      See Also:

    • cupsGetOption

      String cupsGetOption(String name, int num_options, Pointer options)
      Gets an option value from a destination's options array.

      Common option names include "printer-info", "printer-state", "printer-make-and-model", "printer-type", "printer-state-reasons", "printer-is-accepting-jobs", and "printer-uri-supported".

      Parameters:
      name - option name to look up
      num_options - number of options in the array
      options - pointer to the options array
      Returns:
      the option value or null if not found
      See Also:

    • cupsAddOption

      int cupsAddOption(String name, String value, int num_options, PointerByReference options)
      Adds an option to an options array.

      If the named option already exists, its value is replaced.

      Parameters:
      name - option name
      value - option value
      num_options - current number of options
      options - pointer to the options array (updated on return)
      Returns:
      the new number of options
      See Also:

    • cupsFreeOptions

      void cupsFreeOptions(int num_options, Pointer options)
      Frees the memory used by an options array.
      Parameters:
      num_options - number of options
      options - pointer to the options array
      See Also:

    • cupsGetJobs2

      int cupsGetJobs2(Pointer http, PointerByReference jobs, String name, int myjobs, int whichjobs)
      Gets the jobs from the specified server.

      Use cupsFreeJobs(int, Pointer) to free the returned job array.

      Parameters:
      http - connection to server or null for the default connection
      jobs - pointer to receive the job array
      name - destination name or null for all destinations
      myjobs - 0 for all users' jobs, 1 for only the current user's jobs
      whichjobs - one of CUPS_WHICHJOBS_ALL, CUPS_WHICHJOBS_ACTIVE, or CUPS_WHICHJOBS_COMPLETED
      Returns:
      the number of jobs
      Since:
      CUPS 1.1.21
      See Also:

    • cupsFreeJobs

      void cupsFreeJobs(int num_jobs, Pointer jobs)
      Frees the memory used by a job array returned by cupsGetJobs2(Pointer, PointerByReference, String, int, int).
      Parameters:
      num_jobs - number of jobs
      jobs - pointer to the job array
      See Also:

    • cupsCancelJob

      int cupsCancelJob(String name, int job_id)
      Cancels a job on a destination.
      Parameters:
      name - destination name
      job_id - the job ID to cancel
      http - connection to server or null for the default connection
      Returns:
      0 on success, non-zero on failure
      See Also:

    • cupsServer

      String cupsServer()
      Returns the hostname or address of the current CUPS server.

      The default server comes from the CUPS_SERVER environment variable, then ~/.cups/client.conf, and finally /etc/cups/client.conf. If not set, the default is "localhost" or a domain socket path.

      Returns:
      the server name
      See Also:

    • cupsSetServer

      void cupsSetServer(String server)
      Sets the default CUPS server name and port.

      The server string can be a fully-qualified hostname, a numeric IPv4 or IPv6 address, or a domain socket pathname. Hostnames and numeric IP addresses can optionally be followed by a colon and port number. Pass null to restore the default server.

      Parameters:
      server - server name or null to restore default
      See Also:

    • cupsUser

      String cupsUser()
      Returns the current user's name as known to CUPS.

      Note: The current user name is tracked separately for each thread.

      Returns:
      the user name
      See Also:

    • cupsSetUser

      void cupsSetUser(String user)
      Sets the default user name for CUPS operations.

      Pass null to restore the default user name. Note: The user name is tracked per-thread.

      Parameters:
      user - user name or null to restore default
      See Also:

    • cupsLastError

      int cupsLastError()
      Returns the last IPP status code from a CUPS operation.
      Returns:
      the IPP status code

    • cupsLastErrorString

      String cupsLastErrorString()
      Returns a human-readable message for the last IPP error.
      Returns:
      the error message string