caps-printer-prep.c File Reference

CAPS Printer Device Preparation. More...

Functions
int	caps_prn_recognize_new_printer_device (const struct usb_printer *prn, struct caps_inif_table *db)
static int	caps_prn_check_printer (const struct usb_printer *prn, struct caps_inif_table *db)
static int	caps_prn_check_device_node (const char *dev_node)
static void	handle_nls (void)
static int	prep_node_cb (const struct caps_arg_parser *parser, const char *value)
int	main (int argc, char *argv[])

Variables
static const struct caps_arg_parameter	caps_printer_prep_argument
static struct caps_arg_parser	caps_printer_prep_parser

Detailed Description

Copyright

GNU Lesser General Public License 2.1

Author

Jürgen Borleis

Warning

Use as experimental

Whenever a printer device is attached to the host, caps-printer-prep runs as a preparation step prior the printer driver launcher caps-printer. It runs with special permissions in order to prepare the filesystem content when a printer device occurs the very first time. When a connected printer device is already known, caps-printer-prep terminates immediately and successful.

Since caps-printer-prep gets triggered by the same service unit like the printer driver launcher caps-printer it should control the run of it.

Systemd expects a return value of:

• '0' if everything is okay and the printer driver launcher caps-printer should run as well in the next step
• '1…254' if the unit and thus, the printer driver launcher caps-printer should be skipped for this printer device
• '255' to mark the whole unit as failed

Function Documentation

caps_prn_recognize_new_printer_device()

int caps_prn_recognize_new_printer_device	(	const struct usb_printer *	prn,
		struct caps_inif_table *	db
	)

The printer device isn't known yet. Search the printer driver database for a corresponding printer driver.

Parameters

[in]	prn	The USB printer device information
[in,out]	db	The current device database to store the new entry to (on demand)

Return values

0	On success
negative	Ernno

If a printer driver is found, create its corresponding Instance's Parameter Directory in the Driver's Configuration Directory, create the file service.ini with the parameter entry 'name' and a unique name (to be adpated by the user) and add this information beside some other run-time information (like the USB connection to recognize this printer device the next time) to its run-time database.

Note

The run-time information is only added to the in-memory device database. And still needs to be written back to the filesystem

Think about: We could create everything relevant even for the case no printer driver is installed. We just skip the parameter directory and description INI in this case and stop here. But the run-time database gets updated so we know the printer the next time and amend the missing information when available.

caps_prn_check_printer()

static int caps_prn_check_printer ( const struct usb_printer *  prn, struct caps_inif_table *  db  )

static

Prepare for the printing device and its corresponding printer driver

Parameters

[in]	prn	USB printing device information
[in,out]	db	Run-time printing device database

Returns

0 on success, negative errno else

Handling printers mean, check if the printer is already known or create all information on demand if not.

Todo:

Print at info level the device specific INI file including its path and the content of this file? This would be helpful for the user (else the documentation is very complicated).

caps_prn_check_device_node()

static int caps_prn_check_device_node ( const char *  dev_node )

static

Make a simple duck test for a device node entry

Parameters

[in]

dev_node

The device node path to chck

Returns

0 on success, negative errno else

handle_nls()

static void handle_nls ( void  )

static

prep_node_cb()

static int prep_node_cb ( const struct caps_arg_parser *  parser, const char *  value  )

static

main()

int main	(	int	argc,
		char *	argv[]
	)

We are called here for exactly one printer device when it gets attached or detected.

Parameters

[in]	argc	Guess what
[in]	argv	Guess what

Returns

EXIT_FAILURE, else we never return here

caps-printer-prep will be started as root. In this run, it tests, if the connected printer device is already known. If yes, it just terminates, because its job is already done. If the connected printer isn't known yet, it adds this printer device and the required subdirectories first. It has to run as root to ensure all newly created data and files are owned by the correct user and the permissios are safe.

As a parameter we receive the corresponding device node via '–node=<nodename>'. We run as a systemd service with 'Type=notify'.

Variable Documentation

caps_printer_prep_argument

const struct caps_arg_parameter caps_printer_prep_argument

static

Initial value:

= {
    .keyword = "node", .key = 'n', .cb = prep_node_cb,
    .arg =  ( "NODE" ), .doc = ( "Printing device's node in '/dev'" ),
}

caps_printer_prep_parser

struct caps_arg_parser caps_printer_prep_parser

static

Initial value:

= {
    .parameter_cnt = 1,
    .parameter_list = &caps_printer_prep_argument,
    .footer = ( "This argument is mandatory" ),
    .domain = PACKAGE,
}