libcapsdriver: API description

CAPS universe printer driver convenience library. More...

Features
	Version info
	Info for user's code to do the right thing.
	Using the Printer Driver Framework from your driver
	The startup.
	Managing printer driver private data
	Set and get some driver private data in your callback functions.
	Managing some configuration information
	Configuration related helper functions.
	Define the printer device capabilities
	Printer Device Capabilities helper functions.
	Query the printer device and framework status
	Printer Device and Framework Status helper functions.
	Retrieving information about the job to print
	Get the information about the document and how the user wants to print it.
	Error handling when printing
	Provide more detailed information about failures.
	Retrieving information about the current page to print
	Get the information how the current page should be printed.
	Setting up the rasterizer for the current page
	Setup the information the rasterizer requires to rasterize the document page in a way your printer needs it.
	Get the full medium rasterized dot data to print
	Reading the full medium raster line by line for your own processing.
	Get the raw rasterized dot data to print
	Reading the raw raster line by line for your own processing.
	Some convenience functions
	Makes the life easier (sometimes)
	Access to internals
	Sometimes there is a need to get our fingers on internal data.
	Multi core processing framework
	Multithread framework to improve data processing.

Detailed Description

This library is a collection of helper functions to simplify printer driver development, since it hides all the communication, rasterization and reporting details of the CAPS universe.

Note

A skeleton implementation of a driver who uses libcapsdriver you can find in the libcapsdriver's skeleton/ subdirectory

The startup.

You mainly need to write some code to setup national language support (optional, on demand), trigger the command line parameter parsing and then call the libcapsdriver's caps_drv_run() function.

static const struct caps_generic_driver my_driver = {
  // …your callback setup…
};
 
static struct caps_arg_parser parser[2];
 
int main(int argc, char *argv[])
{
    struct caps_arg_parser_list parser_list = {
        .cnt = 2, .list = parser,
        .errorout = stderr, .out = stdout,
   };
   struct caps_drv *h;
   int rc;
 
   h = caps_drv_init(parser);
   […]
   caps_arg_parser_process(&parser_list, argc, argv);
   […]
   rc = caps_drv_run(h, &my_driver, NULL);
   […]
   caps_drv_exit(h);
   […]
   return rc;
}

Instead of doing everything in your printer driver by your own, libcapsdriver uses callbacks into your driver to do all the required steps to start-up and dealing with print jobs. They are called at different stages to deal with print jobs in a generic manner.

Your printer driver callback functions are defined in a caps_generic_driver structure.

A special role has the caps_generic_driver::printer_monitor callback. It is intended to check the state of the printer. Depending on flags managed by libcapsdriver and INI file settings, the monitor callback is called at different points of time (refer caps_drv_printer_tweak_status).

Some printers are in trouble when their status is queried while they are printing at the same time. Thus, the monitor feature can be controlled via an INI setting.

Init Callback

It is called very early while initializing the framework.

• parameter you get
  • framework handle
  • a pointer to your own private data (on demand via caps_drv_run(), for configuation options for example)

    Attention

    This pointer differs from the pointer of all other callback functions.

• you can expect as already done
  • command line arguments are already processed (but its up to you when you call caps_arg_parser_process())
  • nothing else. This is really internal only.
• what you can do
  • you can allocate your private memory and register it as a hint for the other callbacks via caps_drv_private_set()
• what you must do
  • nothing
• values you should return
  • 0 everything is okay, the framework can continue
  • -EINVAL Something really bad happened in your initialisation and the framework should terminate

Note

This callback is optional.

Printer Adaption Callback

Its called after the command line parameter parsing is done and all kind of information is available.

• parameter you get
  • framework handle
  • your private data hint (if already set in Callback init(), else it is NULL)
• you can expect as already done
  • all INI files are already read in and you can use to query all settings
  • the communication to the printer is established and configured (refer Feature: printing data buffer_size)
  • but there is still no established connection to the printing coordinator!
• what you can do
  • you can allocate your private memory and register it for the other callbacks via caps_drv_private_set() (if not already done, yet)
  • you can query all INI file based settings via the setup API and adapt your own settings, mostly to setup your own printer description (refer caps_ppd_base)
  • on demand configure your printer device somwhow
  • setup tweaks for your printer device if nessesary (note: no supported yet this way, refer Feature: control printer monitoring instead)
• what you must do
  • registering your own printer description (caps_ppd_base) via caps_drv_printer_desc_set()
• values you should return
  • 0 everything is okay, the framework can continue
  • -ENODEV It isn't the expected printing device or something else is bad with this device and the framework should terminate

Functions related to this state:

• Managing some configuration information

Note

This callback is optional.

Job Start Callback

This callback is called when the framework has received a printing job. It already has checked if it can deal with the document data format, e.g. a corresponding rasterizer is already attached and now it is up to you to check if this job can be printed on your printer.

• parameter you get
  • framework handle
  • your private data hint
• you can expect as already done
  • everything is working as expected, e.g. communication with the printing coordinator and the printer device
• what you can do
  • everything you need to do to process data
• what you must do
  • you must check if this job can be printed on your device
    • medium format settings
    • resolution settings
    • colour/grey/monochrome setup
    • simplex/duplex settings
    • and so on
• values you should return
  • 0 everything is okay, the framework can continue
  • -EINVAL if the job cannot be printed.
    • the job will be canceled and the job_finish() callback is called next
  • -EBUSY The printer is somehow busy (more or less a printer error condition, cover opened for example)
    • TODO makes no sense here
  • -EBADMSG ?
  • -ENODEV It isn't the expected printing device or something else is bad with this device and the framework should terminate

Functions related to this state:

• Retrieving information about the job to print

  Todo:

  Job status updating in case of a failure.

  We need to distinguish a bad job from a bad behaviour of the software, e.g just skip the job versus terminating the driver

Job Finish Callback

This callback is called once per job (even if printing has failed somehow).

Called when the job is "done" somehow, e.g.:

• if the last page was printed
• if print fails
  • due to an external event (printer is gone for example)
  • due to one of your callback functions returned an error condition (like -ENODEV for example)
  • termination request recieved
• if the job has to be canceled

Printing can fail due to your own return values in Callback job_start(), or Callback page_setup(), Callback page_print() or Callback printer_monitor() or by failures detected somewhere else in the framework.

• parameter you get
  • framework handle
  • your private data hint
• you can expect as already done
  • everything might working as expected, e.g. communication with the printing coordinator and the printer device
  • take care when communicating with the printer. It is possible, it is already gone! You can call caps_drv_is_offline() to check, if it is alreay gone.
• what you can do
  • everything to clean up from processing (freeing memory for example) and printing (inform the printer device the printing is done for example if possible).
• what you must do
  • terminate printing (if not already done)
  • everything else depends on your requirements
• values you should return
  • 0 everything is okay, the framework can continue
  • -ENODEV if something is really bad with your printer and the framework should terminate.

Page Setup Callback

Called when the framework has extracted all required information about the next page to print. It is called once per page.

• parameter you get
  • framework handle
  • your private data hint
• you can expect as already done
  • everything is working as expected, e.g. communication with the printing coordinator and the printer device
• what you can do
  • everything to parametrize the next page rasterization
• what you must do
  • setup the rasterizing parameter for the next page
  • everything else depends on your requirements
• values you should return
  • 0 everything is okay, the framework can continue
  • -EINVAL if the page cannot be printed. TODO error message why!

Functions related to this state:

• Retrieving information about the current page to print
• Setting up the rasterizer for the current page

Page Print Callback

Called when the framework has rasterized the current page and this data is ready to be printed. It is called once per page. E.g. once per medium in simplex print and twice per medium when printing in duplex.

• parameter you get
  • framework handle
  • your private data hint
• you can expect as already done
  • everything is working as expected, e.g. communication with the printing coordinator and the printer device
• what you can do
  • everything else depends on your requirements
• what you must do
  • process the raster data and transform it into the printer's wire data format
• values you should return
  • 0 everything is okay, the framework can continue
  • -EINVAL if the page cannot be processed/printed and the job should be terminated.
  • -ENODEV if something is really bad with your printer and the framework should terminate.
  • -ENXIO if a transaction with the printer's stream failed and the framework should terminate.

Note

For the case of -EINVAL and -ENXIO, you should use caps_drv_job_canceled() or caps_drv_job_aborted() to set a useful error message why the job was terminated (if you have one. Else the framework will set a generic one, which is most of the time less helpful).

Functions related to this state:

• Get the full medium rasterized dot data to print
• Get the raw rasterized dot data to print

Printer Monitor Callback

Called, when the framework retrieves the status of the printer. But not always. See below.

• parameter you get
  • framework handle
  • your private data hint
• you can expect as already done
  • the printer is still online and can be accessed
• what you can do
  • everything what is possible with your printer
• what you must do
  • nothing
• values you should return
  • 0 everything is okay, the framework can continue
  • -EBUSY if the printer isn't ready to print somehow
  • -ENODEV if something is really bad with your printer and the framework should terminate.
  • -EINVAL if something is wrong with your printer, but can be recovered. If currently a job is processed it will be canceled

libcapsdriver checks the printer status:

• never, if CAPS_TWEAK_SKIP_STATUS is set, and thus, never calls this callback
• periodically when the printer is idle (e.g. waiting for a job to print) if CAPS_TWEAK_SKIP_STATUS isn't set
• immediately before printing a page (e.g. before calling page_print()) if CAPS_TWEAK_SKIP_STATUS_WHEN_PRINTING and CAPS_TWEAK_SKIP_STATUS aren't set

Whenever it checks the printer's status, it calls the callback only if it detects a ready printer device.

Note

This call interferes with some of the flags from caps_drv_prn_tweaks if set in your driver. E.g. it could be limited or fully disabled by these flags. Be warned about this.

This callback is optional.

Monitoring the printer device might be a sensible task somehow. Thus, its behaviour can be controlled via an INI file setting:

For how to control the behaviour, refer Feature: control printer monitoring

Exit Callback

Everything you need to clean up.

• parameter you get
  • framework handle
  • your private data hint
• you can expect as already done
  • connection to the printing coordinator is already closed
  • communication to the printer is still possible, but only if the printer device is still online. Since most of the time a gone printer device is the trigger to terminate the driver, you shouldn't expect a working communication with the printer. You can use caps_drv_is_offline() to distinguish this case.
• what you must do
  • prepare your printer device to shut down (power saving mode for example) if it is still online
  • memory clean up (to avoid false positives when running with a memory leak checker for example)
• values you should return
  • 0 everything is okay, the framework can continue

Note

This callback is optional.