=====Contents=====

  * [[https://www.linuxfoundation.org/#CUPS_.28in_progress.29|1 CUPS (in progress)]]
    * [[https://www.linuxfoundation.org/#Description|1.1 Description]]
      * [[https://www.linuxfoundation.org/#Specification_Overview|1.1.1 Specification Overview]]
      * [[https://www.linuxfoundation.org/#CUPS_Implementation|1.1.2 CUPS Implementation]]
    * [[https://www.linuxfoundation.org/#Candidate_Tracker_Information|1.2 Candidate Tracker Information]]
      * [[https://www.linuxfoundation.org/#Stable|1.2.1 Stable]]
      * [[https://www.linuxfoundation.org/#Versions|1.2.2 Versions]]
      * [[https://www.linuxfoundation.org/#Dependencies|1.2.3 Dependencies]]
      * [[https://www.linuxfoundation.org/#Documentation|1.2.4 Documentation]]
      * [[https://www.linuxfoundation.org/#API_Documentation|1.2.5 API Documentation]]
    * [[https://www.linuxfoundation.org/#Related_test_suites|1.3 Related test suites]]
    * [[https://www.linuxfoundation.org/#Library_analysis_data|1.4 Library analysis data]]
      * [[https://www.linuxfoundation.org/#List_of_apps_and_libraries_using_this_library|1.4.1 List of apps and libraries using this library]]
      * [[https://www.linuxfoundation.org/#Most_commonly_used_interfaces|1.4.2 Most commonly used interfaces]]
      * [[https://www.linuxfoundation.org/#Interfaces_chosen_for_LSB|1.4.3 Interfaces chosen for LSB]]
        * [[https://www.linuxfoundation.org/#CUPS_API|1.4.3.1 CUPS API]]
        * [[https://www.linuxfoundation.org/#CUPS_PPD_API|1.4.3.2 CUPS PPD API]]
        * [[https://www.linuxfoundation.org/#Interfaces_not_used_in_the_previously_listed_apps|1.4.3.3 Interfaces not used in the previously listed apps]]
      * [[https://www.linuxfoundation.org/#Candidate_Interfaces_to_be_Tested|1.4.4 Candidate Interfaces to be Tested]]
    * [[https://www.linuxfoundation.org/#Other_information|1.5 Other information]]

======  CUPS (in progress) ======
=====  Description =====

Currently most Linux distros and MacOS X use [[http://www.cups.org/|CUPS]] (Common UNIX Print System) for printing. CUPS is also available on AIX, FreeBSD, HP-UX, IRIX, NetBSD, OpenBSD, Solaris, and Tru64 UNIX. CUPS uses an extended version of the [[http://www.pwg.org/ipp/|Internet Printing Protocol (IPP)]] to send requests from the print client, such as application, to a print server.

IPP is an IEEE Standard; Solaris 10 now provides an IPP-capable print server. However, CUPS is not included in standard UNIX base systems.
====  Specification Overview ====

The application-facing API ([[http://www.cups.org/documentation.php/api-cups.html|CUPS API]] and [[http://www.cups.org/documentation.php/api-ppd.html|CUPS PPD API]]) are most likely scheduled to be included in LSB 3.2. This allows an application developer a way to access a printing system that is available on most Linux systems.
====  CUPS Implementation ====
=====  Candidate Tracker Information =====
====  Stable ====

CUPS has been adding APIs rather than deprecating them and has been fairly stable. The release of CUPS 1.1.23 was Jan 03, 2005, and the CUPS 1.2 was released May 08, 2006 with no changes to the existing API.
====  Versions ====

A quick check of CUPS versions available in the 3.2 timeframe is:

 CUPS Versions across distributions
^ Distribution ^ CUPS version^
| Debian Etch | 1.2.2|
| Fedora Core 5 | 1.2.2|
| Mandriva Free 2007 | 1.2.4|
| Redhat Enterprise Linux Client 5 | 1.2.2|
| SUSE Linux Enterprise Desktop 10 | 1.1.23|
| Ubuntu 6.06.1 | 1.2.2|
====  Dependencies ====

The following list of dependencies is required to build the full CUPS package.
<code>groff (for man pages)
jpeg (for printing images)
png (for printing images)
tiff (for printing images)
zlib (compression support for files, print jobs, and images)</code>
====  Documentation ====

[[http://www.cups.org/documentation.php|CUPS 1.2 User Documentation]]. CUPS 1.1 documentation is at the bottom of the page.
====  API Documentation ====

Included application APIs are the [[http://www.cups.org/documentation.php/api-cups.html|CUPS API]] and the [[http://www.cups.org/documentation.php/api-ppd.html|CUPS PPD API]].

Also other APIs are on the [[http://www.cups.org/documentation.php|parent web page]].
=====  Related test suites =====

CUPS has high-level tests and many unit tests. The unit tests are not complete, but Michael Sweet (the CUPS maintainer) has offered support for adding to the tests where necessary.

According to him:

Right now we have about 80% coverage of the PPD API, and I'd guess about 20% for the convenience functions.  The HTTP and IPP APIs (which would allow applications to do IPP requests) have automated tests with about 85% coverage overall.

...

For destinations:

  - cupsGetDests() returns the correct number of printers (maybe check against the "lpstat -p" output?)
  - cupsGetDest(NULL, NULL, num_dests, dests) should return a default destination unless none is set, in which case it should return NULL.  You can loop through the dests array manually to verify this.
  - cupsGetDest("name", NULL, num_dests, dests) should return the named destination with instance set to NULL.
  - cupsGetDest("name", "instance", num_dests, dests) should return the named destination and instance.
  - The list of printer names and instances should be sorted in ascending order (use strcasecmp to check)
  - Each printer should have at least the following options: job-sheets-default, printer-info, printer-is-accepting-jobs, printer-location, printer-make-and-model, printer-state, printer-type

For options, you can test the cupsAddOption, cupsGetOption, and cupsParseOptions functions for the proper functioning for various inputs.  Basically, cupsAddOption should only add non-NULL values and should never duplicate options (two adds with the same name will yield only 1 option), cupsGetOption should return the value of the named option or NULL, and cupsParseOptions() should handle parsing options in the PAPI-defined text encoding format:
<code>
     name=value
     name="value with spaces"
     name='value with spaces'
     name={name=value name=value}</code>
=====  Library analysis data =====
====  List of apps and libraries using this library ====

A list of applications that depend on CUPS was compiled from gentoo linux packaging information. (Gentoo was used because the packaging information was quickly available.)

  *  checked
<code>kdelibs
app-office/openoffice
gnustep-base/gnustep-gui
media-gfx/flphoto
net-print/libgnomecups
x11-libs/fox
x11-libs/qt
xfce-base/xfprint</code>

  *  not checked
^application^reason not checked^
|app-emulation/cedega | emulator|
|app-emulation/wine | emulator|
|app-emulation/winex-transgaming | emulator|
|app-text/acroread | have other adobe data|
|app-text/ghostscript-afpl | ghostscript-esp is part of CUPS|
|app-text/ghostscript-esp | ghostscript-esp is part of cups|
|app-text/ghostscript-gnu | ghostscript-esp is part of cups|
|dev-perl/Net-CUPS | not an application|
|gnome-base/libgnomeprint | checked libgnomecups|
|media-gfx/gimp-print | printer drivers|
|net-misc/nxclient | commercial app|
|net-misc/nxserver-freenx | commercial app|
|net-print/cups-pdf | CUPS plugin|
|net-print/fax4cups | not an application|
|net-print/foo2zjs | not an application|
|net-print/foomatic-filters | not an application|
|net-print/gqueue | not an application|
|net-print/gtklp | not an application|
|net-print/hpijs | not an application|
|net-print/hplip | not an application|
|net-print/hpoj | not an application|
|net-print/mtink | not an application|
|net-print/omni | not an application|
|net-print/xpp | not an application|
|net-wireless/bluez-utils | not an application|
|x11-libs/qt-embedded | not an application|
====  Most commonly used interfaces ====
====  Interfaces chosen for LSB ====

The client side of CUPS is contained in the[[http://www.cups.org/documentation.php/api-cups.html|CUPS API]] and the[[http://www.cups.org/documentation.php/api-ppd.html|CUPS PPD API]].

The API documentation for CUPS is on the web and an application uses interfaces from the [[http://www.cups.org/documentation.php/api-cups.html|CUPS API]] and the [[http://www.cups.org/documentation.php/api-ppd.html|CUPS PPD API]].

Since we are trying to keep the client/application API separate from the server API, we are only using a subset of the interfaces listed on those two pages.
===  CUPS API ===

The CUPS API is located in cups/cups.h and cups/language.h. Interfaces listed in the header file that aren't included are noted at the end of this section.

The interfaces in //**italics**// are new to CUPS 1.2x.

cups/cups.h
<code>cupsAddDest
cupsAddOption
cupsCancelJob
cupsEncryption
cupsFreeDests
cupsFreeJobs
cupsFreeOptions
cupsGetDefault
cupsGetDefault2
cupsGetDest
cupsGetDests
cupsGetDests2
cupsGetFd
cupsGetFile
cupsGetJobs
cupsGetJobs2
cupsGetOption
cupsGetPassword
cupsGetPPD
cupsGetPPD2
cupsLastError//**cupsLastErrorString**//
cupsMarkOptions
cupsParseOptions
cupsPrintFile
cupsPrintFile2
cupsPrintFiles
cupsPrintFiles2
cupsPutFd
cupsPutFile//**cupsRemoveOption**//
cupsServer
cupsSetDests
cupsSetDests2
cupsSetEncryption
cupsSetPasswordCB
cupsSetServer
cupsSetUser
cupsTempFd//**cupsTempFile2**//
cupsUser</code>

cups/language.h
<code>cupsLangDefault
cupsLangEncoding
cupsLangFlush
cupsLangFree
cupsLangGet</code>

\\ 

Interfaces not included in CUPS API from cups.h or lang.h
^Function ^ Reason not included^
|//**cupsBackChannelRead**// | in Filter and Backend APIs|
|//**cupsBackChannelWrite**// | in Filter and Backend APIs|
|cupsDoAuthentication | in HTTP and IPP section|
|cupsDoFileRequest | in HTTP and IPP section|
|cupsDoRequest | in HTTP and IPP section|
|cupsEncodeOptions | in HTTP and IPP section|
|//**cupsEncodeOptions2**// | in HTTP and IPP section|
|cupsGetClasses | DEPRECATED|
|cupsGetPrinters | DEPRECATED|
|//**cupsNotifySubject**// | undocumented|
|//**cupsNotifyText**// | undocumented|
|cupsTempFile | DEPRECATED|
|cupsLangString | internal interface|
===  CUPS PPD API ===

The PPD API is located in cups/ppd.h.
<code>ppdClose
ppdCollect//**ppdCollect2**//
ppdConflicts
ppdEmit//**ppdEmitAfterOrder**//
ppdEmitFd
ppdEmitJCL//**ppdEmitJCLEnd**////**ppdEmitString**//
ppdErrorString
ppdFindAttr
ppdFindChoice//**ppdFindCustomOption**////**ppdFindCustomParam**//
ppdFindMarkedChoice
ppdFindNextAttr
ppdFindOption//**ppdFirstCustomParam**////**ppdFirstOption**//
ppdIsMarked
ppdLastError//**ppdLocalize**//
ppdMarkDefaults
ppdMarkOption//**ppdNextCustomParam**////**ppdNextOption**//
ppdOpen//**ppdOpen2**//
ppdOpenFd
ppdOpenFile
ppdPageLength
ppdPageSize
ppdPageWidth
ppdSetConformance</code>
===  Interfaces not used in the previously listed apps ===

The following tables list interfaces that were not found in the gentoo applications listed above. The CUPS API functions are mostly used, but only about half of the PPD API functions are used.

\\ 
Unused API CUPS functions

Most of the CUPS API functions are used by the applications in the "gentoo list." The list shows that older versions of updated functions are always used at this time, (e.g. cupsGetDests rather than cupsGetDests2) and this could be due to slow adoption of newer functions. All three deprecated interfaces are unused. And then finally cupsLangFlush is unused, probably because a single language is used in the print job and everything is destroyed after use rather than flushed during use.
^Function^extra info^
|cupsGetClasses | DEPRECATED|
|cupsGetDefault2 | new in CUPS 1.1.21 - using cupsGetDefault|
|cupsGetDests2 | new in CUPS 1.1.21 - using cupsGetDests|
|cupsGetFile | new in CUPS 1.1.20 - using httpGet|
|cupsGetJobs2 | new in CUPS 1.1.21 - using cupsGetJobs|
|cupsGetPPD2 | new in CUPS 1.1.21 - using cupsGetPPD|
|cupsGetPrinters | DEPRECATED|
|cupsLangFlush | no need to flush the language cache?|
|cupsPrintFile2 | new in CUPS 1.1.21 - using cupsPrintFile|
|cupsPrintFiles2 | new in CUPS 1.1.21 - using cupsGetFiles|
|cupsPutFile | new in CUPS 1.1.20|
|cupsSetDests2 | new in CUPS 1.1.21 - using cupsSetDests|
|cupsSetEncryption | using cupsEncryption?|
|cupsTempFile | DEPRECATED|

Unused API PPD functions

Only 8 out of 35 PPD functions are used by the sampled applications. The parsing of PPD options is fairly straightforward and can be performed by a small subset of functions.

Functions used:
<code>ppdClose()
ppdFindAttr() CUPS 1.1.19
ppdFindOption()
ppdMarkDefaults()
ppdMarkOption()
ppdOpen()
ppdOpenFile()
ppdPageSize()</code>

Functions unused
<code>ppdCollect 
ppdConflicts 
ppdEmit 
ppdEmitFd 
ppdEmitJCL 
ppdErrorString new in CUPS 1.1.19
ppdFindChoice 
ppdFindMarkedChoice 
ppdFindNextAttr new in CUPS 1.1.19
ppdIsMarked 
ppdLastError new in CUPS 1.1.19
ppdOpenFd 
ppdPageLength 
ppdPageWidth 
ppdSetConformance new in CUPS 1.1.20</code>
====  Candidate Interfaces to be Tested ====
=====  Other information =====

A generic API for print services [[http://www.openprinting.org/moin.cgi/OpenPrinting/PAPI|PAPI]] is being developed by [[http://www.openprinting.org/|OpenPrinting Workgroup]] of the LF. However, PAPI is missing printer description infrastructure such as PPD access functions. PAPI is not included in all the mainstream Linux distros so it is not a candidate for inclusion in LSB 3.2.

The renderer in CUPS requires linking with with libcupsimage, and the licensing requires a fee or the release of the source code (Note: Easy Software Products has since retroactively changed the libcupsimage license to LGPL, allowing developers to provide drivers linked to it at no charge...) An option to CUPS renderer is the [[ftp://ftp.pwg.org/pub/pwg/fsg/vector/VectorPrinterDriverAPI-0.2en.pdf|OpenPrinting Print Driver API (PDAPI)]] that was developed by Japanese printer manufacturers. [[http://opfc.sourceforge.jp/index.html.en|[1]]]

Glue code for OpenPrinting Vector is currently included in [[http://www.cups.org/espgs/index.php|ESP Ghostscript]] (development discontinued) and in [[http://www.ghostscript.com/|GPL Ghostscript]] so it is included in the latest versions of most distros.