Printing service provisioning

Register a printing service and define its capabilities. More...

Functions
struct caps_pp_handle *	caps_pp_instance_create (struct caps_arg_parser *parser)
int	caps_pp_instance_runtime_prepare (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)
const char *	caps_pp_instance_runtime_param_get (struct caps_pp_handle *instance, const char *section, const char *name)
void	caps_pp_instance_mime_setup (struct caps_pp_handle *instance, const struct caps_supported_mime_list *mimes)
void	caps_pp_instance_runtime_setup (struct caps_pp_handle *instance, const struct caps_ppd_base *cpb)
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)
struct caps_ppd_options_table *	caps_pp_ppd_options_get (struct caps_pp_handle *instance)
void	caps_pp_instance_domain_add (struct caps_pp_handle *instance, const char *domain)

Detailed Description

A simple example without error handling:

[…]
caps_pp_handle instance = caps_pp_instance_create(&parser);
 
[…]
// TODO process command line arguments
[…]
 
caps_pp_instance_runtime_prepare(instance);
 
[…]
// TODO: setup a device specific capability description
[…]
 
caps_pp_instance_runtime_setup(instance, printer_description);
 
[…]
// Since you are linked against one of the available rasterizer libraries you
// can call them for the supported MIME types
[…]
 
caps_pp_instance_mime_setup(instance, caps_rstr_mime_list_get());
 
caps_pp_instance_register(instance);
 
[…]
// TODO loop and do all the printing work until the driver needs to terminate
[…]
 
caps_pp_instance_unregister(instance);
[…]
 
// TODO don't forget to clean-up
caps_pp_instance_destroy(instance);

Function Documentation

caps_pp_instance_create()

struct caps_pp_handle * caps_pp_instance_create

(

struct caps_arg_parser *

parser

)

Create a provider instance handle

Parameters

[out]

parser

Where to store an argument parser definition

Returns

New provider instance handle

This is the first call to be done in order to create a printing provider. All further functions mentioned here depend on its return value.

The returned instance handle is incomplete and needs to be completed via caps_pp_instance_register()

The returned argument parser definition must be used within the application's caps_arg_parser_process() call as its child parser in order to parse the command line arguments for generic libcapsprovider specific and required arguments.

Mainly the parser will extract the --driver-ini (e.g. CAPS_DRIVER_INI_NAME) and --parameter-dir (e.g. CAPS_PARAM_DIRECTORY_NAME) command line parameter settings for further processing in caps_pp_instance_runtime_prepare().

Note

Does not return in case of memory failure

Postcondition

The returned handle needs to be freed after use via caps_pp_instance_destroy()

Expected is a call to caps_pp_instance_runtime_prepare() in the next step

Developer's corner

caps_pp_instance_runtime_prepare()

int caps_pp_instance_runtime_prepare

(

struct caps_pp_handle *

instance

)

Prepare the printer driver's run-time configuration from a list of INI files

Parameters

[in]

instance

Provider instance handle

Return values

0	on success
-EINVAL	Insufficient command line parameter information
negative	errno else

This is the second call to the library after caps_pp_instance_create().

Since this functions expects already parsed and processed command line arguments you must first use the returned parser child node from the caps_pp_instance_create() in your local caps_arg_parser_process() call and then call caps_pp_instance_runtime_prepare() as the next step.

The already processed command line parameters are used here to read in the run-time configuration for this specific printing provider/driver and its specific and corresponding printing device.

If this call returns successfully, run-time settings based on the corresponding INI files are available and can be retrieved via caps_pp_instance_runtime_param_get(). This can be used to tweak the printer's information (refer caps_pp_instance_runtime_setup()).

Run-Time Configuration

The run-time settings contain the following merged INI file content and - important - in this order:

• the global caps.ini (from the CAPS Configuration Directory)
• the global capsdriver.ini (from the CAPS Printer Driver Configuration Directory)
• a Device Description INI file (from the CAPS Printer Driver Database Directory), based on the value of the --driver-ini parameter
• an optional Driver Feature Configuration INI file (from the CAPS Printer Driver Configuration Directory, refer note below)
• Printing Device Parameters INI files (from a device specific subdirectory in the CAPS Printer Device Parameter Directory), the subdirectory is defined by the --parameter-dir command line parameter.

Attention

The optional 'printer driver feature INI' listed above is merged on demand only if mentioned in the 'printer driver INI' in section [defaults], key 'features'

Since the INI files get merged into one data set, the latter INI file can overwrite key/values from its predecessor.

In case of failure, do not continue to work with instance, except caps_pp_instance_destroy() - and after that terminate gracefully!

More details can be found in Printing Device INI files hierarchy

Precondition

Successful call to caps_pp_instance_create()

Successful parsed and processed command line arguments

Developer's corner

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

caps_pp_instance_runtime_implant()

int caps_pp_instance_runtime_implant	(	struct caps_pp_handle *	instance,
		const char *	level,
		const char *	section,
		const char *	key,
		const char *	value
	)

Implant run-time information (development feature)

Parameters

[in]	instance	Provider instance handle
[in]	level	INI file's 'level' value ('user', 'defaults' or 'base', refer _caps_pp_get_priorized_option() for details)
[in]	section	INI file's 'section' value (for example 'info')
[in]	key	INI file's 'key' value (for example 'name' or 'brief')
[in]	value	INI file's 'value' value (can be NULL if 'key' is of type boolean)

Return values

0	on success
negative	errno else

This feature is more a developer's feature. It's intended to test a printing driver, without to make the big loop over all kind of INI file setup. It helps to avoid the call to caps_pp_instance_runtime_prepare() and replaces its function.

In case of failure, do not continue to work with instance, except caps_pp_instance_destroy() - and after that terminate gracefully!

Precondition

Successful call to caps_pp_instance_create()

Note

Don't expect this function is available in a non-DEBUG variant of the library

Developer's corner

caps_pp_instance_runtime_param_get()

const char * caps_pp_instance_runtime_param_get	(	struct caps_pp_handle *	instance,
		const char *	section,
		const char *	name
	)

Get the value from the specified section/name parameter out of the run-time configuration

Parameters

[in]	instance	Provider instance handle or instance
[in]	section	Section name to read the parameter from (can be NULL)
[in]	name	Name of the parameter

Return values

string	Pointer to the parameter's value
NULL	If the key does not exist

This function can be called after caps_pp_instance_runtime_prepare() was called once to retrieve run-time configurations.

To the developer: if you add some keys to make your driver work, don't forget to add some meaningful defaults for these keys to your driver-default INI. And add some documentation, when and why and to what to change these defaults on demand.

Note

Does not return in case of failure (non existing key isn't a failure)

Boolean keys return a valid pointer to an empty string (e.g. the first character is '\0').

Todo:

Add link to a section explaining what run-time configuration means

Precondition

Successful call to caps_pp_instance_runtime_prepare()

Developer's corner

caps_pp_instance_mime_setup()

void caps_pp_instance_mime_setup	(	struct caps_pp_handle *	instance,
		const struct caps_supported_mime_list *	mimes
	)

Setup the supported MIME formats for this printing provider

Parameters

[in]	instance	Provider instance handle
[in]	mimes	List of nativly supported MIME types

This is the third call to the library after caps_pp_instance_create().

This call must be done before the call of caps_pp_instance_register(), e.g. the supported MIME types cannot be changed after the registration anymore.

Note

The supported MIME types required here can be retrieved from libcapsraster or libcapsdriver.

Precondition

Successful call to caps_pp_instance_runtime_prepare()

This call can be done only once per instance to define the supported MIME types

Developer's corner

caps_pp_instance_runtime_setup()

void caps_pp_instance_runtime_setup	(	struct caps_pp_handle *	instance,
		const struct caps_ppd_base *	cpb
	)

Setup the printer provider's/driver's information

Parameters

[in]	instance	Provider instance
[in]	cpb	Printer feature description

This call can be done more than once. Each call will re-new the corresponding information locally and at the printing coordinator remotely.

Normally this information is static. But maybe your printer can detect any change of its available media at run-time and the driver can read this back. In this case it can forward a new provider's/driver's information to the coordinator on the change.

Precondition

Successful call to caps_pp_instance_runtime_prepare()

Developer's corner

caps_pp_instance_register()

int caps_pp_instance_register

(

struct caps_pp_handle *

instance

)

Register this printing provider/driver instance at the printing coordinator

Parameters

[in]

instance

Provider instance handle to register

Return values

0	on success
-EIO	Connection to or communication with the CAPS universe service RPC failed
-EBUSY	Failed to register at the CAPS universe service RPC or some part of the setup seems already done (should not happen!)
-ENOMSG	Failed to attach to the CAPS universe service notifiers
-EINVAL	Bad/unexpected reply from the CAPS universe service RPC or printer name is missing
-ENODEV	Unknown printer ID (should not happen, we're just registering it)
-EPERM	Permission rejected (should not happen, we're just registering it)

This is the forth call to the library after caps_pp_instance_create(), caps_pp_instance_runtime_prepare() and caps_pp_instance_mime_setup().

Note

For all communication related failures, you can find a more specific error message in the logs.

Precondition

Successful calls to caps_pp_instance_create()

Unique instance's name must be already set via caps_pp_instance_runtime_prepare()

Instance's PPD options must be already set via caps_pp_instance_runtime_setup()

Instance's MIME types must be already set via caps_pp_instance_mime_setup()

Developer's corner

The communication with the printing coordinator:

The full call stack:

Note

Counterpart is dbus_CreatePrinterId_dispatch()

caps_pp_instance_unregister()

void caps_pp_instance_unregister

(

struct caps_pp_handle *

instance

)

Unregister this printing provider/driver instance at the printing coordinator

Parameters

[in]

instance

Provider instance to unregister

The internal state of the provider will be set to:

• object_state_prn::id = LIBCAPS_PP_STATE_OFFLINE
• object_state_prn::reason = LIBCAPS_PP_REASON_NONE
• object_state_prn::message = "Gone offline"

Note

For a graceful termination you should call this function.

The printing coordinator will remove this instance as well, if your driver terminates without calling this function

You can also call caps_pp_instance_destroy() instead

Precondition

Successful call to caps_pp_instance_register()

Postcondition

This call dispatches a provider change notifier on the DBUS interface.

Developer's corner

The communication with the printing coordinator:

The full call stack:

Note

Counterpart is dbus_FreePrinterId_dispatch()

caps_pp_instance_destroy()

void caps_pp_instance_destroy

(

struct caps_pp_handle *

instance

)

Free all provider instance resources

Parameters

[in]

instance

Provider instance handle to destroy

If not already done yet, this function will call caps_pp_instance_unregister() as well.

Note

For a graceful termination you should call this function. At least you will make memory leak detection easier and remove one possible false positive.

Precondition

A call to caps_pp_instance_create() was already done

Postcondition

If this call needs to call caps_pp_instance_unregister() it dispatches a provider change notifier on the DBUS interface.

Developer's corner

caps_pp_ppd_options_get()

struct caps_ppd_options_table * caps_pp_ppd_options_get

(

struct caps_pp_handle *

instance

)

Get a copy of the instance's default PPD options

Parameters

[in]

instance

Library instance

Returns

Pointer Table of PPD options

This copy is required to apply the device specific printing parameters to it (for each individual print job). Don't forget to free the returned default PPD options table.

Note

Does not return if the instance has no PPD options.

Precondition

A successful call to caps_pp_instance_runtime_setup()

Postcondition

Since you receive a copy of the default PPD options table, you need to free it with caps_ppd_options_table_clean_up()

Developer's corner

caps_pp_instance_domain_add()

void caps_pp_instance_domain_add	(	struct caps_pp_handle *	instance,
		const char *	domain
	)

Add further NLS domains to support more detailed status messages from different sources

Parameters

[in]	instance	Provider instance
[in]	domain	NLS domain name to add

caps_pp_job_state_update() and caps_pp_state_update() can deal with up to two different NLS domains by default to translate a given message into a local language:

• one is the libcapsprovider's one
• one is the printer driver's one (via the caps_ppd_base)

But there are additional libraries which can add state messages like libcapsdriver does. Thus, more NLS domains need to be searched in order to support their individual translations.