Cups agent description


Purpose

The Cups agent is part of YaST2 SCR, the system configuration repository, used to access configuration data on the target system. The general SCR API allows Read() and Write() access to get and change data.
It is used to read and write printers and classes, to create database of printers and to read ppd files.

Implementation

Printers

List of printers is obtained from file /etc/cups/printers.conf but informations here are not suffitient. PPD file name is obtained via cupsGetPPD and options via cupsGetDests. Printers are written via ipp calls. Their options are written via cupsSetDest.
TODO: do not read printers from file but using ipp calls.

Classes

Classes are read and written via ipp calls. For manipulating their options we use cupsGet/SetDests

Default destination

Read and written via dests and cupsSetDests.

Database of printers

Number of ppd files present on system can be big. Processing ppd files each time cups configuration tool is invoked would take too much time (minutes) hence we create index of all ppd files. This file is used for creation of list of vendors and printers and for printer autodetection.

Options

We must deliver an encoding of ppd file to YaST2 because YaST2 works in utf-8 and we need to recode. Encoding is saved in ppd file so this is no problem.
Agent understands and processes suboptions that can be stated in ppd file using UIConstraints. Example:
*UIConstraints: *Option1 *Option0 value6
*UIConstraints: *Option1 *Option0 value7

*OpenUI *Option0/drivers (using macro 'bjc6100'): PickOne
*DefaultOption0: value0
*Option0 value0/monochrome or color driver 'bjc600' at '360x360' dpi: ""
*Option0 value6/color driver 'uniprint' at '360x360' dpi (using 'bjc6000a1.upp'): ""
*Option0 value7/color driver 'uniprint' at '720x720' dpi (using 'bjc6000b1.upp'): ""
*CloseUI: *Option0

*OpenUI *Option1/'bits per pixel' settings for the driver 'bjc600': PickOne
*DefaultOption1: value1
*Option1 value1/monochrome printing (using '-dBitsPerPixel=1'): ""
*Option1 value2/color printing (using '-dBitsPerPixel=8'): ""
*CloseUI: *Option1
Constraints say that that Option1 can not be used when Option0 value6 or Option0 value7 is used. Hence Option1 can be used only if Option0 value0 is selected. Option1 is suboption of Option0 value0.

Common Options

Common options are hardcoded in cups. They are described in http://www.cups.org/sum.html#STANDARD_OPTIONS We need ppd file name for them because they contain e.g. paper sizes or whether printer is color.

Note: The complete development documentation is available in the autodocs/ directory.

Interface for modules-agent

Printers and Classes

Read (.cups.printers) --> list of printers
Write (.cups.printers, list)
Read (.cups.classes) --> list of classes
Write (.cups.classes, list)
List of printersList of classes
[
  $[ "Name"             : <string>, // printer name
     "Info"             : <string>,
     "Location"         : <string>,
     "Uri"              : <string>,
     "State"            : <string>,
     "StateMessage"     : <string>,
     "Accepting"        : <boolean>,
     "BannerStart"      : <string>,
     "BannerEnd"        : <string>,
     "AllowUsers"       : [ <string> , <string> , ... ],
     "DenyUsers"        : [ <string> , <string> , ... ],
     "ppd"              : <string>, 
     "options"          : $[ <string> : <string> , ... ]
   ],
  ...
];
.cups.classes
[
  $[ "Name"             : <string>,  // class name
     "Info"             : <string>,
     "Location"         : <string>,
     "State"            : <string>,
     "StateMessage"     : <string>,
     "Accepting"        : <boolean>,
     "BannerStart"      : <string>,
     "BannerEnd"        : <string>,
     "Printers"         : [ <string> , <string> , ... ],
     "AllowUsers"       : [ <string> , <string> , ... ],
     "DenyUsers"        : [ <string> , <string> , ... ],
     "ppd"              : <string>, 
     "options"          : $[ <string> : <string> , ... ] 
  ],
  ...
];
ppd is file name of ppd file assotiated with the printer/class. (note that ppd file for class has no sense, but cups supports it).
options is list of pairs option:value
AllowUsers and DenyUsers are mutually exclusive. There can not be both AllowUsers and DenyUsers specified.

Default destination can be printer or class.

PPD files

Status of current database Database creation This sequence ensures reading of fresh database:
        if (SCR (`Read (.cups.ppd.changed)))
            SCR (`Write (.cups.ppd.createdb, true));
        map printers_db = SCR (`Read (.target.ycp, "/var/lib/YaST2/ppd_db.ycp"));
Example of database:
$[
  "VENDOR" : 
  $[
    "MODEL" :
    $[  // drivers for that model
      "model nick" :
        [
          "ppd file name",
          "1284 vendor id",
          "1284 model id"
        ]
    ]
  ],
  "CANON" : $[
    "BJC-6100" : $[
      "Canon BJC-6100, Foomatic + stp-4.0" : [
        "/usr/share/cups/model/Canon/BJC-6100-stp.ppd",
        "",
        ""
      ],
      "Canon BJC-6100, SuSE" : [
        "/usr/share/cups/model/suse/Canon/BJC-6100.ppd",
        "Canon",
        "BJC-6100"
      ]
    ]
  ],
]
Options Common options

Complete Read paths table

PathTypeResult
.cups.printersYCPList all printers
.cups.classesYCPList all classes
.cups.default_destYCPString default destination
.cups.ppd.changedYCPBoolean has ppd db changed since last creation?
.cups.ppd.optionsYCPMap options
.cups.ppd.common_optionsYCPMap common options

Complete Write paths table

PathResult
.cups.printersall printers
.cups.classesall classes
.cups.default_destdefault destination
.cups.ppd.createdbtriggers db breation

Former documentation

cups.txt
ppd.txt

Petr Blahos <pblahos@suse.cz>