caps_generic_driver Struct Reference

Printer Driver Callback declaration. More...

Data Fields
int(*	init )(struct caps_drv *, void *)
int(*	printer_adaptions )(struct caps_drv *, void *)
int(*	job_start )(struct caps_drv *, void *)
int(*	job_finish )(struct caps_drv *, void *)
int(*	page_setup )(struct caps_drv *, void *)
int(*	page_print )(struct caps_drv *, void *)
int(*	printer_monitor )(struct caps_drv *, void *)
int(*	exit )(struct caps_drv *, void *)

Detailed Description

Here you define the callback functions of your driver specific implementation.

Note

There are no default callbacks provided. If you leave the callback function pointer at NULL, nothing will be done in this stage. But only some callback functions can be left undefined. They are marked here in the documentation. All other are mandatory.

Field Documentation

init

int(* init) (struct caps_drv *, void *)

Everything you need for your driver's internal preparation.

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_adaptions

int(* printer_adaptions) (struct caps_drv *, void *)

Adapt your defaults to the user's settings.

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

int(* job_start) (struct caps_drv *, void *)

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

int(* job_finish) (struct caps_drv *, void *)

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

int(* page_setup) (struct caps_drv *, void *)

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

int(* page_print) (struct caps_drv *, void *)

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

int(* printer_monitor) (struct caps_drv *, void *)

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.

exit

int(* exit) (struct caps_drv *, void *)

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.

---

The documentation for this struct was generated from the following file:

• libcapsdriver/src/libcapsdriver.h