Using the Printer Driver Framework from your driver

The startup. More...

Data Structures
struct	caps_generic_driver
	Printer Driver Callback declaration. More...

Functions
struct caps_drv *	caps_drv_init (struct caps_arg_parser parser[2])
void	caps_drv_exit (struct caps_drv *cdrv)
int	caps_drv_run (struct caps_drv *cdrv, const struct caps_generic_driver *cb, void *private)
int	caps_drv_terminate_now (struct caps_drv *cdrv)
FILE *	caps_drv_to_stream (struct caps_drv *cdrv)

Detailed Description

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.

Function Documentation

caps_drv_init()

struct caps_drv * caps_drv_init

(

struct caps_arg_parser

parser[2]

)

Initialize the library and retrieve the library's command line parser definition and a library instance handle

Parameters

[out]

parser

Where to store two command line parser definitions

Returns

New driver instance handle

The returned library instance handle is used in all other library calls.

Attention

The caps_arg_parser array requires to have at least two entries. If your driver has its own parser you need three entries. But you are free where you add the two command line parser entries from libcapsdriver in this array. E.g. after your own parser or in front of it. It only has an impact on the order of the generated help text.

Note

Does not return in case of memory failure

Postcondition

The instance handle needs to be freed via caps_drv_exit()

Only one instance is currently possible (the returned handle is static)

caps_drv_exit()

void caps_drv_exit

(

struct caps_drv *

cdrv

)

Free library specific resources

Parameters

[in]

cdrv

libcapsdriver handle to be freed (from the caps_drv_init() call)

Should be called prior process termination.

Precondition

Successful call to caps_drv_init()

caps_drv_run()

int caps_drv_run	(	struct caps_drv *	cdrv,
		const struct caps_generic_driver *	cb,
		void *	private
	)

Run the libcapsdriver engine

Parameters

[in]	cdrv	libcapsdriver handle
[in]	cb	The list of callbacks of your driver implementation
[in]	private	Pointer to private data for the caps_generic_driver::init callback

Return values

EXIT_SUCCESS	For a regular termination (SIGTERM for example)
EXIT_FAILURE	Something failed while running.

This call doesn't return until the driver should terminate. All further print job and page processing happens via callbacks into your driver implementation.

Note

The private pointer in this call is special. It is used exactly once in the caps_generic_driver::init callback and not stored into the libcapsdriver handle. But you can do so, if you want (refer caps_drv_private_set())

This function registers two signal handlers for the signals SIGTERM and SIGINT. Both signals are interpreted as a request to terminate. If your printer driver has long periods of processing, your should call caps_drv_terminate_now() periodically and terminate your processing gracefully on demand.

Precondition

Successful call to caps_drv_init()

Successful parsed and processed command line arguments (via caps_arg_parser_process())

caps_drv_terminate_now()

int caps_drv_terminate_now

(

struct caps_drv *

cdrv

)

Check if the driver should terminate

Parameters

[in]

cdrv

libcapsdriver handle

Return values

0	Continue
1	Terminate, libcapsdriver has received a SIGTERM or SIGINT

Usually you don't need to call this function. It is only intended if long term processing tasks are running inside your printer driver callbacks. If possible your should call it periodically and should return early to terminate the whole printer driver gracefully.

caps_drv_to_stream()

FILE * caps_drv_to_stream

(

struct caps_drv *

cdrv

)

Get the stream to communicate with the printer device

Parameters

[in]

cdrv

libcapsdriver handle

Return values

STREAM	A valid stream to send data to the printer
NULL	No stream available. Internal failure, should not happen

Note

Since a printer can go offline at any point of time you always should check for failures when you communicate with the printer. If you detect a communication failure, return with -ENODEV in the corresponding callback to trigger a termination.