• 1 Querying the OpenPrinting Database
  • 1.1 Query types
  • 1.2 Modification of the output
  • 1.3 Filters
  • 1.4 Character escaping
  • 1.5 Examples
  • 1.6 Downloading PPD files

To make it easy for programs like for example printer setup tools to query the OpenPrinting database, there is a simple HTTP interface to get information from the database in text or XML format. This way a printer setup tool can for example look for downloadable driver packages.

The queries are done by simply requesting a URL describing which information is needed. This can be done via HTTP library functions in most programming languages or with “wget” out of shell scripts.

The basic query types are asking for manufacturers, printers, or drivers.

All manufacturers for which there are printers in the database get listed by

• http://openprinting.org/query.cgi?type=manufacturers

All printers in the database get listed by

• http://openprinting.org/query.cgi?type=printers

All drivers in the database get listed by

• http://openprinting.org/query.cgi?type=drivers

These queries are not necessarily useful, usually you will apply modifications and/or filters to them.

Instead of plain text you can have XML as output format. Simply add the

format=xml

option to the URL:

• http://openprinting.org/query.cgi?type=printers&format=xml

Default is “format=text”.

Note: In URLs there can be no spaces. Options have to be separated by the ampersand (“&”).

Now you have only seen the names of the drivers and printers. To get details about them add “moreinfo=1”:

• http://openprinting.org/query.cgi?type=printers&moreinfo=1

These two options can be combined:

• http://openprinting.org/query.cgi?type=printers&moreinfo=1&format=xml

The OpenPrinting database supports also internationalization. The querying client can tell its user interface language using

uilanguage=<locale code>

“<locale code>” is a standard locale code, consisting of a two-letter language code and an optional two-letter country code, like de, it, pt_BR, ja, … If appropriate translations are available, the server will answer with translated text. Translated text is always UTF8-encoded. This modifier can be combined with all the other modifiers. Especially you should use it together with “moreinfo=1”, as the printer and driver names do not have translations. Example for a japanese environment:

• http://openprinting.org/query.cgi?type=drivers&make=HP&model=LaserJet_4&moreinfo=1&uilanguage=ja

Note that this does not select region-specific driver packages. See the “locale” option below.

If you are doing a query for drivers and you have specified the printer for which you want to see the drivers via search terms or an IEEE-1284 device ID, you probably also want to know the printer's Foomatic ID, so that you can see whether a search term was correctly matched and that you can more easily reference to the printer in our database or your local database. To do so, add the modifier

showprinterid=1

This modifier only works on driver queries which specify a printer. Example:

• http://openprinting.org/query.cgi?type=drivers&make=HP&model=LaserJet_4&showprinterid=1

This can also be combined with all other modifiers and filters.

Now you will get tons of output which will perhaps need some time to download. You will probably need only a few data sets, like

• All driver packages for the Samsung ML-1750 for the i386 architecture
• All available driver packages for the 64-bit PC architecture
• All driver packages which are free software
• All drivers for the HP LaserJet 3390 which are supplied by HP
• The printer entry corresponding to a given IEEE-1284 device ID

This can all be realized by filters. Following filters can be applied with “<name>=<value>”, all can be combined:

Note:

“onlydownload=1” is not the same as “driverpackages=1&onlyppdfiles=1”. The former shows all drivers which have something to download, a PPD OR a driver package, the latter shows only drivers for which BOTH a PPD AND a driver package is provided.

“onlyppdfiles=1” is not the same as “nobinarydriverpackages=1”. The former shows only drivers with downloadable PPD files, the latter suppresses listing of binary RPM packages for the drivers (for example if you want to see only source RPMs using the “sourcedriverpackages=1” filter).

When we talk about PPD files here, we mean ready-made (usually manufacturer supplied for PostScript printers) PPD files. The web query API never returns a Foomatic-generated PPD file as a downloadable item. The Foomatic-generated PPDs usually always need additional software to work (a driver), whereas driver packages and ready-made PPDs can get installed on any LSB-compliant machine and provide the full support for the selected printer.

In some cases special characters have to be included in the query, but they are not allowed in URLs or they are a delimiter for the elements of the query URL. These characters have to be substituted by “%<ASCII code of the character in hex>”. Here is a table of characters and their substitutions:

1. A printer setup tool detects an HP LaserJet 3390 on the local USB by getting the following IEEE-1284 device ID:

MFG:Hewlett-Packard;
CMD:PJL,PML,MLC,POSTSCRIPT,PCLXL,PCL;
MDL:HP LaserJet 3390;
CLS:PRINTER;
DES:Hewlett-Packard LaserJet 3390;
MEM:MEM=53MB;
1284.4DL:4d,4e,1;
COMMENT:RES=1200x1;

The device ID usually comes as one line, without line breaks, here it is only shown in one item per line to make it more readable. Let's assume that on the local machine has no driver for this printer (or only a driver which poorly supports this printer). The setup tool tries to look up drivers on the OpenPrinting site. To find out which printer was auto-detected, it requests the follwing URL:

• http://openprinting.org/query.cgi?type=printers&moreinfo=1&printer=MFG:Hewlett-Packard%3b\ CMD:PJL,PML,MLC,POSTSCRIPT,PCLXL,PCL%3bMDL:HP%20LaserJet%203390%3bCLS:PRINTER%3b\ DES:Hewlett-Packard%20LaserJet%203390%3bMEM:MEM=53MB%3b1284.4DL:4d,4e,1%3bCOMMENT:RES=1200x1%3b

Notes:

• All special characters in the device ID (space and ”;” here) are substituted
• The URL has to be supplied in one line, without the backslashes, here it is only split to not break the layout of the web page
• If you use “wget”, put the whole URL into single or double quotes so that the shell does not break it.
• For assignment of a printer model only the fields “MFG:” (or “MANUFACTURER:”), “MDL:” (or “MODEL:”), and “DES:” (or DESCRIPTION:“) are used. If the printer is not listed in the database, it is checked whether the printer knows PostScript or PCL by parsing the “CMD:” (or “COMMANDSET:”) field and an appropriate Generic printer is returned. All other fields of the ID will be ignored and therefore they can be omitted in the URL. Also the order of the fields is not relevant.

As answer something like this will come out:

HP-LaserJet_3390
  Manufacturer: HP
  Model: LaserJet 3390
  Works: Perfectly
  Recommended driver: Postscript
  Drivers:
    hpijs
    Postscript
  Autodetection data
    General
      Manufacturer: Hewlett-Packard
      Model: HP LaserJet 3390
      Description: Hewlett-Packard LaserJet 3390
      Command Set: PJL,MLC,PCL,POSTSCRIPT,PCLXL

This is the information about the printer in the database. Further queries you can do with the Foomatic ID now. The Foomatic ID is in the first line of the output. The setup tool gets info about downloadable drivers with (it has also detected that the platform it is running on is a usual 32-bit PC. We use a distribution with RPM as standard packaging system):

• http://openprinting.org/query.cgi?type=drivers&moreinfo=1&printer=HP-LaserJet_3390&\ onlydriverpackages=1&onlynewestdriverpackages=1&architectures=i386&packagesystem=rpm&lsbversion=3.2

The answer of this request is rather long and therefore not shown here. Please click on the request to see the answer.

Assuming we have also a Samsung ML-1750 on the same box, the setup tool will also do this request

• http://openprinting.org/query.cgi?type=drivers&moreinfo=1&printer=Samsung-ML-1750&\ onlydriverpackages=1&onlynewestdriverpackages=1&architectures=i386&packagesystem=rpm&lsbversion=3.2

and get as answer (In reality the answer is longer, as development of drivers has continued):

splix

URL: [[http://splix.ap2c.org/|http://splix.ap2c.org/]]
Supplier: SpliX project
Manufacturer-supplied: No
License: GPL
Free Software: Yes
Support contact: [[http://sourceforge.net/forum/?group_id=175815|http://sourceforge.net/forum/?group_id=175815]], SpliX forum at SourceForge (voluntary)
Short Description: Driver for Samsung SPL2 (ML-1710, ...) and SPLc (CLP-500, ...) laser printers
Driver type: CUPS Raster
Max. X Resolution: 1200
Max. Y Resolution: 1200
Color output: No
Text printing support: 100
Line art printing support: 100
Graphics printing support: 100
Photo printing support: 80
Packages for i486
  File: RPMS/i486/openprinting-splix-1.1.1-4lsb3.2.i486.rpm
    URL: [[http://www.openprinting.org/download/printdriver/RPMS/i486/openprinting-splix-1.1.1-4lsb3.2.i486.rpm|http://www.openprinting.org/download/printdriver/RPMS/i486/openprinting-splix-1.1.1-4lsb3.2.i486.rpm]]
    Real Version: 1.1.1
    Version: 1.1.1
    Release: 4
    LSB version: 3.2
    Sorting index: 1.1.1_3_3.2
    Link text: 1.1.1 (LSB 3.2)
    Architecture: i486
    Packaging System: rpm
    Scope: general
    Repositories
      yum:
        [openprinting-splix-driver]
        name=OpenPrinting LSB-3.2-based driver packages of "splix"
        baseurl=[[http://www.openprinting.org/download/printdriver/components/lsb3.2/splix/RPMS|http://www.openprinting.org/download/printdriver/components/lsb3.2/splix/RPMS]]
        enabled=1
        gpgcheck=0
      zypper: zypper sa [[http://www.openprinting.org/download/printdriver/components/lsb3.2/splix/RPMS/|http://www.openprinting.org/download/printdriver/components/lsb3.2/splix/RPMS/]] splix

Now the setup tool can check whether this driver exists already locally and if yes, compare the version information. If there is no local installation or an older version, it presents the user the general driver data (short description, license, support contact, …) and if he agrees with using this driver it downloads the driver by requesting the URL

• http://openprinting.org/download/printdriver/RPMS/i486/openprinting-splix-1.1.1-4lsb3.2.i486.rpm

and installs the package. After that it goes on setting up a print queue for the printer.

In addition, the printer setup tool can (and should) use the information in the “Repositories” section to add the package repository of the driver to the system. This way the auto-update process of the system will also find updates of the driver on OpenPrinting, for example bug fixes, especially in case of a security vulnerability.

The repository information is used as follows: On yum-based systems the contents of the subsection “yum” has to be put into a new file created in the /etc/yum/repos.d/ directory. The file name does not matter. You can for example use the string in the square brackets of the first line also as the file name. On zypper-based systems, run the command in the “zypper” section as root. On apt-based systems (Debian packages) add the line in the “apt” subsection to the /etc/apt/sources.list file. See also the instructions for manual installation of driver packages.

Note also the “Scope: general” entry in the data about the downloadable package. In the case that the driver consists of more than one package, there will be entries for each package and the “Scope: ” fields tell about the purpose for each package. This way it is possible to select only the packages which are really needed, like for example leaving out GUI tools on a head-less server. Predefined scopes are “general”, “gui”, “printer”, “scanner”, and “fax”.

A driver can also depend on another driver. This means that the driver only works if also the other driver is installed. This is the case for example if a driver is an add-on for another driver. A manufacturer could issue a free software driver suite to support most of their printers. For legal reasons they cannot publish the source code of drivers for some of their other printers. Therefore they make proprietary plug-ins for their free software driver suite and publish them as separate packages. These can be listed as separate drivers in the database and they depend on the main driver suite. The output of the driver query looks like the one shown above, but it has added a list of dependencies at its end:

  Requires:
    Driver: hpijs (>= 2.7.10)

In this case the printer setup tool has to query also this driver (by a driver query with the driver name) and to download and install also the packages listed there. The dependency entries can also require a certain minimum or maximum version of the driver.

For PostScript printers (or also printers which work with built-in drivers of GhostScript, like “pxlmono”) one does not necessarily need a driver package. A PPD would be enough. So let us look for any downloadable item:

• http://openprinting.org/query.cgi?type=drivers&moreinfo=1&printer=HP-LaserJet_3390&\ onlydownload=1&onlynewestdriverpackages=1&architectures=i386&packagesystem=rpm&lsbversion=3.2

But note that with single PPD files you do not have the advantage of a package manager, which allows easy updates and removal of the installed files.

A printer setup tool can even do a driver query without preceeding it by a printer query:

• http://openprinting.org/query.cgi?type=drivers&moreinfo=1&showprinterid=1&printer=MFG:Hewlett-Packard%3b\ CMD:PJL,PML,MLC,POSTSCRIPT,PCLXL,PCL%3bMDL:HP%20LaserJet%203390%3bCLS:PRINTER%3b\ DES:Hewlett-Packard%20LaserJet%203390%3bMEM:MEM=53MB%3b1284.4DL:4d,4e,1%3bCOMMENT:RES=1200x1%3b&\ onlydownload=1&onlynewestdriverpackages=1&architectures=i386&packagesystem=rpm&lsbversion=3.2

This shows the list of downloadable drivers and PPDs directly from a query of the IEEE-1284 device ID. We let the answer also contain the Foomatic ID of the printer (using “showprinterid=1”), so that we can see whether the correct printer model was used as base for this driver query.

2. A Linux distribution wants to include as many printer drivers as possible but keep the maintenance effort low. But as they want to have the drivers perfectly optimized for the users's PC and also to avoid the necessity of installing the “lsb” package, they decide to download the source RPMs and to rebuild all drivers. In addition, they need to make two packages, one of the free drivers to ship in the main distribution and one for the non-free to ship in an add-on repository.

So their package builder does the following two requests:

• http://openprinting.org/query.cgi?type=drivers&onlydriverpackages=1&onlyfree=1&moreinfo=1&\ sourcedriverpackages=1&nobinarydriverpackages=1&onlynewestdriverpackages=1&noobsoletes=1

This one is for the free software drivers. Only source RPMs get listed and only the newest versions of each driver. Drivers marked as obsolete in the database are excluded from the listing.

• http://openprinting.org/query.cgi?type=drivers&onlydriverpackages=1&onlynonfree=1&moreinfo=1&\ sourcedriverpackages=1&onlynewestdriverpackages=1&noobsoletes=1

For the non-free driver packages also the binary packages are listed, as proprietary software RPMs are often provided without source RPMs. So one gets such drivers at least as binary RPM.

Now the package builder uses the output of the requests for an index file in the package documentation and it downloads all source RPMs and in the case of the non-free drivers also the binary RPMs of drivers for which the source RPM is not available. It rebuilds all source RPMs and having binary RPMs of all drivers now it joins the files and scripts of the binary RPMs in its two driver packages.

There is also a query scheme for downloading single PPD files. It works both with PPD files which are generated from the database by Foomatic and with PPD files which are ready-to-use on the server (manufacturer-supplied PPDs).

The parameters needed are the driver name and the Foomatic printer ID. Both appear in the answers to the above-mentioned database queries. They are the headlines of the entries in the plain text output of driver and printer queries or the “id” parameter in the driver and printer entries of the XML output (”<driver id=“driver/…”>“ or ”<printer id=“printer/…”>“). Driver queries with the “showprinterid=1” option show the Foomatic ID of the printer in the first line (“Printer: …”) of the plain text output or in the XML output as ”<drivers printer=“printer/…”>“, also in the first line.

The URL for downloading a PPD is then

http://www.openprinting.org/ppd-o-matic.cgi?driver=<driver ID>&\\ printer=<Foomatic printer ID>

Here is an example for the Infotec IS2032 (Foomatic ID: Infotec-IS2032) with the pxlmono-Infotec driver:

http://www.openprinting.org/ppd-o-matic.cgi?driver=pxlmono-Infotec&\\ printer=Infotec-IS2032

This directly downloads the PPD file.

Links to single PPD files are shown if you do a driver query with a “printer=…” argument. This queries all drivers for a given printer. If a driver provides a ready-made (not a Foomatic-generated) PPD for the given printer, a link to the PPD will appear in the answer. Example:

http://www.openprinting.org/query.php?type=driver&\\ printer=Infotec-IS2032&moreinfo=1&showprinterid=1&format=text

In this example there is a “PPD file: …” line at the end of the two driver entries “Postscript-Infotec” and “pxlmono-Infotec”.