libcapsprovider.c File Reference

Library to gain access to the printing coordinator for printing providers/printer drivers. More...

Functions
void	caps_libprovider_version_get (unsigned *major, unsigned *minor, unsigned *micro)
static void	free_printers_features (struct caps_pp_handle *instance)
static void	free_mime_types (struct caps_supported_mime_list *mimes)
static void	free_instance_domain_list (struct caps_pp_handle *instance)
static void	free_instance_structure (struct caps_pp_handle *instance)
static void	init_printers_features (struct caps_pp_handle *instance)
static void	init_instance_structure (struct caps_pp_handle *instance)
void	caps_pp_instance_domain_add (struct caps_pp_handle *instance, const char *domain)
const char *	state_message_translate (struct caps_pp_handle *instance, const char *string)
int	caps_pp_state_update (struct caps_pp_handle *instance, enum caps_printing_provider_state state, enum caps_printing_provider_reason reason, const char *message)
static const char *	_caps_pp_get_priorized_option (const struct caps_inif_table *option_table, const char *section, const char *name)
const char *	caps_pp_instance_runtime_param_get (struct caps_pp_handle *instance, const char *section, const char *name)
static int	printer_setup_ppd_info (struct caps_pp_handle *instance)
static void	ppd_dev_info_setup (struct caps_inif_table *rt_cfg, struct caps_ppd_device_info *i)
void	caps_pp_instance_runtime_setup (struct caps_pp_handle *instance, const struct caps_ppd_base *cpb)
static void	runtime_configuration_default_readin (struct caps_inif_table *runtime_config, const char *ini_filename)
static void	runtime_configuration_apply_init (const struct caps_inif_table *runtime_config)
static int	driver_ini_cb (const struct caps_arg_parser *parser, const char *value)
static int	param_dir_cb (const struct caps_arg_parser *parser, const char *value)
int	caps_pp_instance_runtime_prepare (struct caps_pp_handle *instance)
struct caps_pp_handle *	caps_pp_instance_create (struct caps_arg_parser *parser)
int	notifier_job_change (void *data, caps_identifier pr_id, caps_identifier job_id)
static void	copy_mime_types (struct caps_supported_mime_list *dst, const struct caps_supported_mime_list *src)
static int	_coord_setup_printer_info_from_config (struct caps_pp_handle *instance)
int	caps_pp_instance_register (struct caps_pp_handle *instance)
void	caps_pp_instance_unregister (struct caps_pp_handle *instance)
void	caps_pp_instance_destroy (struct caps_pp_handle *instance)
int	caps_pp_instance_runtime_implant (struct caps_pp_handle *instance, const char *level, const char *section, const char *key, const char *value)
void	caps_pp_instance_mime_setup (struct caps_pp_handle *instance, const struct caps_supported_mime_list *mimes)
struct caps_ppd_options_table *	caps_pp_ppd_options_get (struct caps_pp_handle *instance)

Variables
static const struct caps_arg_parameter	libcapsprovider_argument_list []
static struct caps_arg_parser	libcapsprovider_parser
static const struct caps_pp_notifier	provider_notifier

Detailed Description

Copyright

GNU Lesser General Public License 2.1

Author

Jürgen Borleis

Warning

Use as experimental

Function Documentation

free_printers_features()

static void free_printers_features ( struct caps_pp_handle *  instance )

static

Free the printer feature information

Parameters

[in]

instance

The instance where to free all printer feature related information

This is a separate function in order to support changing the printer's features at run-time.

free_mime_types()

static void free_mime_types ( struct caps_supported_mime_list *  mimes )

static

Free existing MIME type information

Parameters

[in,out]

mimes

The MIME type structure to clean

free_instance_domain_list()

static void free_instance_domain_list ( struct caps_pp_handle *  instance )

static

Free the additional NLS domains (if any)

Parameters

[in,out]

instance

The instance to clean its NLS domain

free_instance_structure()

static void free_instance_structure ( struct caps_pp_handle *  instance )

static

Guess what...

Parameters

[out]

instance

The to be destroyed...

init_printers_features()

static void init_printers_features ( struct caps_pp_handle *  instance )

static

prepare for the printer feature information

Parameters

[in]

instance

The instance where to free all printer feature related information

This is a separate function in order to support changing the printer's features at run-time.

Note

Does not return in case of a failure (memory or I/O).

init_instance_structure()

static void init_instance_structure ( struct caps_pp_handle *  instance )

static

Guess what...

Parameters

[out]

instance

The to be initialized...

Its important to clear the .coord_connection as well in order to ensure it does not try to close a non-existent connection to the DBUS in a partially initialized strucure. This is to be improved...

state_message_translate()

const char * state_message_translate	(	struct caps_pp_handle *	instance,
		const char *	string
	)

Try to translate a string which might be defined in the printing provider's translations

Parameters

[in]	instance	The instance with its own translation hints
[in]	string	The string to translate

Returns

The translated string or the original string if no translation is available

This routine tries to translate the given string into the local language (environment variable LANG) using the NLS domain caps_ppd_base::domain_name of the calling printing driver. If the printing driver does not support it (e.g. its caps_ppd_base::domain_name is NULL, or hasn't a translation for this message), this routine tries an optional list of NLS domains registerd with caps_pp_instance_domain_add(). If there are no additionla NLS domains registerd or they do not provide a translation, it tries to use coordinators po file. Some messages are common and maybe a shared translation is already available.

Todo:

Add a list of common shared messages. Refer caps_pp_state_update() and caps_pp_job_state_update()

_caps_pp_get_priorized_option()

static const char * _caps_pp_get_priorized_option ( const struct caps_inif_table *  option_table, const char *  section, const char *  name  )

static

Read in a specific parameter in section [info] by its name and honor overwrites

Parameters

[in]	option_table	The parameter table to search for
[in]	section	Section to read the parameter from
[in]	name	The parameter's name to search for

Returns

The key's value or NULL if not found

This routine prefers user settings. If the user hasn't set its own value (via overwrite) it falls back to more generic settings.

Todo:

Why didn't work the first approach (with "level" = NULL)?

Note

The level names used here must be in sync with the level names used in caps_pp_instance_runtime_prepare()

Attention

Sollte überflüssig sein, da ich jetzt alles nach "base" einlese

printer_setup_ppd_info()

static int printer_setup_ppd_info ( struct caps_pp_handle *  instance )

static

Setup the printer's corresponding PPD file at the printing coordinator

Parameters

[in]

instance

Library instance handle

Returns

0 on success, negative errno on failure

Todo:

It's unclear about the permissions this file should have. We will forward it to clients and there is only exactly one file in the filesystem.

Note

After calling this function, the stream I/O should not be used anymore.

ppd_dev_info_setup()

static void ppd_dev_info_setup ( struct caps_inif_table *  rt_cfg, struct caps_ppd_device_info *  i  )

static

Setup some basic printer device information in order to create a PPD according to the spec

Parameters

[in]	rt_cfg	Run-time configuration
[out]	i	The printer device information to fill

If the run-time info contains some specific PPD entries use them. If not, try to fall back to the generic information. If this fails as well, use generic data.

Note

The returned strings are valid as long the run-time config is valid

The used information expected in the INI files are described in Device Description INI files: section [ppd]

Precondition

Call to caps_pp_instance_runtime_prepare()

runtime_configuration_default_readin()

static void runtime_configuration_default_readin ( struct caps_inif_table *  runtime_config, const char *  ini_filename  )

static

Read-in the default settings from the driver's INI and its feature INI (if defined)

Parameters

[out]	runtime_config	The configuration table to fill
[in]	ini_filename	The FQP name of the driver's INI

The driver's INI settings and its feature INI settings get merged into one level: "default"

The used information expected in the INI files are described in Device Description INI files: section [defaults]

Precondition

The runtime_config must already be initialized

runtime_configuration_apply_init()

static void runtime_configuration_apply_init ( const struct caps_inif_table *  runtime_config )

static

Apply some settings from the configuration

Parameters

[in]

runtime_config

The current run-time settings

For all drivers and services using the 'libcapsprovider' are currently applied:

• verbosity via the entry 'verbosity' in section 'debug'
• process priority via entry 'priority' in section 'feature' (TODO)

Todo:

Remove the priority handling from here and implement it in libcapsdriver instead.

driver_ini_cb()

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

static

param_dir_cb()

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

static

notifier_job_change()

int notifier_job_change	(	void *	data,
		caps_identifier	pr_id,
		caps_identifier	job_id
	)

Called by the DBUS interface, if the job state changes at the printing coordinator

Parameters

[in]	data	Pointer to anonymous data, defined when coord_connection_create() is called
[in]	pr_id	Dedicated printing provider ID the job status changes
[in]	job_id	Job ID the status changes

Returns

0 on success

This function is called whenever the job state changes at a printing coordinator. It means it gets called even if the job isn't for this running provider. So this routine must sort out all jobs dedicated for different printing providers.

Called-back when coord_notifiers_process() is called.

Note

Access to the job dedicated for a different provider is rejected by the printing coordinator. So even we receive it's signal, we cannot get control about its job.

copy_mime_types()

static void copy_mime_types ( struct caps_supported_mime_list *  dst, const struct caps_supported_mime_list *  src  )

static

_coord_setup_printer_info_from_config()

static int _coord_setup_printer_info_from_config ( struct caps_pp_handle *  instance )

static

Setup the base printer's information at the Printing Coordinator

Parameters

[in]

instance

Library instance handle

Return values

0	On success
-EINVAL	If no name for this instance is defined
negative	More from dbus_SetPrinterInfo_dispatch

Extract and use the printing provider's information from the run-time configuration

The used information expected in the INI files are described in Printing Device Parameters INI files: section [info] for user adaption and in Device Description INI files: section [info]

Variable Documentation

libcapsprovider_argument_list

const struct caps_arg_parameter libcapsprovider_argument_list[]

static

Initial value:

= {
    {
        .keyword =  "driver-ini" , .key =  'f' ,
        .cb = driver_ini_cb,
        .arg =  NLS_("FILE"), .doc = NLS_("Device Description INI file name"),
    }, {
        .keyword =  "parameter-dir" , .key =  'd' ,
        .cb = param_dir_cb,
        .arg = NLS_("DIR"), .doc = NLS_("Printers's dynamic parameter directory"),
    },
}

libcapsprovider_parser

struct caps_arg_parser libcapsprovider_parser

static

Initial value:

= {
    .parameter_cnt = ARRAY_SIZE(libcapsprovider_argument_list),
    .parameter_list = libcapsprovider_argument_list,
    .header = NLS_("Provider generic arguments"),
    .footer = NLS_("These arguments are mandatory"),
    .domain = PACKAGE,
}

The libcapsprovider argument parser for the main arguments shared by all printing drivers/providers.

Attention

This structure cannot be 'const' since the object member must be set at run-time.

provider_notifier

const struct caps_pp_notifier provider_notifier

static

Initial value:

= {
    .job_change = notifier_job_change,
}