OpenPrinting Web Query API

Contents

Querying the OpenPrinting Database

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.

 

Query types

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

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

All printers in the database get listed by

All drivers in the database get listed by

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

 

Modification of the output

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

format=xml

option to the URL:

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":

These two options can be combined:

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:

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:

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

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

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

Name Values Default Meaning
printer printer search term none List only printers matching the search term (or drivers for the best match). The search term can be a Foomatic ID, "<make>|<model>", "<make> <model>", or any part of that. Also an IEEE-1284 device ID can be supplied, for example to find drivers for an auto-detected printer. Note that certain characters are not allowed in URLs and need to be escaped. See below.
make manufacturer name none List only printers from this manufacturer
model model name/search term none List only printers matching the search term (or drivers for the best match)
driver driver name none List only this driver
onlydownload 0, 1 0 If 1, list only drivers for which there are downloadable driver packages or PPDs
onlyppdfiles 0, 1 0 If 1, list only drivers for which a downloadable PPD file is available
onlydriverpackages 0, 1 0 If 1, list only drivers for which a downloadable driver package is available
sourcedriverpackages 0, 1 0 If 1, list also source driver packages (source RPMs)
nobinarydriverpackages 0, 1 0 If 1, no binary driver packages get listed
onlynewestdriverpackages 0, 1 0 If 1, list only the newest version of each driver package
onlysigneddriverpackages 0, 1 0 If 1, list only signed driver packages for which the signature key fingerprint is available
architectures arch name bin List only driver packages of selected architectures: all, bin (all binary packages), src (source packages), i386, i486, i586, i686, x86_32, ia32, amd64, x86_64, ia64, ppc, s390, s390x, noarch (architecture-independent packages), any (architecture-independent packages)
locale locale code none List only driver packages for selected languages/countries. If there are versions of the driver packages for different regions only the ones suitable for the given language and/or country will be listed. Without this options all packages are shown. The locale code is a two-letter language code with optional two-letter country code, or only a country code in two upper-case letters (de, fr, pt_BR, JP, ...)
notscopes scopes none The answer of a query can contain more than one file for a driver. Then the printer setup tool has to respect this and to install all listed packages if no special instructions are supplied. If there is more then one package for a driver, these are often devided by scopes like "general", "gui", "printer", "scanner", "fax", ... The "notscopes" filter allows to suppress unwished scopes, for example "gui" for head-less servers. The unwished scopes are supplied as a comma-separated list.
onlyscopes scopes none This filter allows to list only the driver packages matching the scopes supplied as a comma-separated list. This is for example useful if one has suppressed some packages with the "notscopes" filter earlier and now these missing parts should get installed.
noobsoletes 0, 1 0 If 1, do not list drivers which are marked as obsolete
onlyfree 0, 1 0 If 1, list only drivers which are free software
onlynonfree 0, 1 0 If 1, list only drivers which are not free software
onlymanufacturer 0, 1 0 If 1, list only drivers which are supplied by the printer manufacturer
nolicensetext 0, 1 0 If 1, list everything except the driver's license text (affects only driver queries with "moreinfo=1" option and with a license text in the database entry)
onlylicensetext 0, 1 0 If 1, show only the license text (no output if there is no license text)
origlicensetext 0, 1 0 If 1, show only the original (English) license text, independent of the chosen UI language, as this is usually the legally valid one (no output if there is no license text)
origlicenselink 0, 1 0 If 1, show only the link to the original (English) license text (no output if there is no such link in the case of the original license text being embedded in the driver XML file or no license text being available at all)
packagesystem package system all List only package files for the given package system: all, rpm (RPM), deb (Debian).
lsbversion LSB version all List only package files for the given LSB version: all, 3.1, 3.2, 4.0, .... More than one version can be given via a comma- and/or space-separated list.

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.

Character escaping

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:

Character To be substituted by
" " (space) %20
"%" %25
"&" %26
";" %3b
"?" %3f
"|" %7c

 

Examples

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:

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):

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

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

splix
  URL: http://splix.ap2c.org/
  Supplier: SpliX project
  Manufacturer-supplied: No
  License: GPL
  Free Software: Yes
  Support contact: 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
      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
          enabled=1
          gpgcheck=0
        zypper: zypper sa 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

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:

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:

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:

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.

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.

 

Downloading PPD files

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".

 

Groups: