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 printers List 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.

Read (.cups.default_dest)

Write (.cups.default_dest, string)

PPD files

Status of current database

Read (.cups.ppd.changed)

Database creation

Write (.cups.ppd.createdb, true)

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

Read (.cups.ppd.options, [ filename, changed_options ])

filename

changed_options

$[
"charset" : string, // isolatin2, ...
"ppd" :  // list of options
  [
    $[
      "name"      : "Readable name of option",
      "option"    : "optionname",
      "default"   : "optionname of default option",
      "marked"    : "optionname of currently marked option",
      "type"      : "boolean" | "pickone" | "pickmany",
      $[
        "valuename" : _("Readable name of value"),
        "valuename" : _("..."),
        // there may be suboptions
        "valuename:sub" : [ //list of options (suboptions)
                          ],
        ...
      ],
    ],
    ...
  ]
];

Write

Common options

Read (.cups.ppd.common_options, [ filename, changed_options ])

filename

changed_options

[  // list of options
  $[ 
    "name"      : _("Readable name of option"),
    "option"    : "optionname",
    "default"   : "optionname of default option",
    "marked"    : "optionname of currently marked option",
    "type"      : "boolean" | "pickone" | "pickmany", 
    $[
      "valuename" : _("Readable name of value"),
      "valuename" : "...",
      // in theory there may be suboptions too but there are none
      "valuename:sub" : [ //list of options (suboptions)
                        ],
      ...
    ],
  ],
  $[
    "name"      : "Readable name of option",
    "option"    : "optionname",
    "default"   : "optionname of default option",
    "marked"    : "optionname of currently marked option",
    "type"      : "slider" | "int",
    "lowermargin" : integer,
    "uppermargin" : integer,
  ],
  $[
    "name"      : "Readable name of option",
    "option"    : "optionname",
    "default"   : "optionname of default option",
    "marked"    : "optionname of currently marked option",
    "type"      : "yseno",
  ],
  ...
];

Write

Complete Read paths table

Path	Type	Result
`.cups.printers`	YCPList	all printers
`.cups.classes`	YCPList	all classes
`.cups.default_dest`	YCPString	default destination
`.cups.ppd.changed`	YCPBoolean	has ppd db changed since last creation?
`.cups.ppd.options`	YCPMap	options
`.cups.ppd.common_options`	YCPMap	common options

Complete Write paths table

Path	Result
`.cups.printers`	all printers
`.cups.classes`	all classes
`.cups.default_dest`	default destination
`.cups.ppd.createdb`	triggers db breation

Former documentation

cups.txt
ppd.txt

Petr Blahos <pblahos@suse.cz>