Prototypes of internally used functions. More...

Data Structures
struct	caps_pp_notifier

struct	coord_comm

struct	nls_domain

struct	caps_pp_handle

struct	caps_pp_document_desc

Macros
#define	CAPS_DRIVER_INI_NAME "driver-ini"

#define	CAPS_DRIVER_INI_NAME_SHORT 'f'

#define	CAPS_PARAM_DIRECTORY_NAME "parameter-dir"

#define	CAPS_PARAM_DIRECTORY_NAME_SHORT 'd'

Typedefs
typedef struct DBusConnection	DBusConnection

Functions
int	coord_connection_create (struct coord_comm instance, const struct caps_pp_notifier notifier, void *data)

void	coord_connection_destroy (struct coord_comm *instance)

int	coord_printer_id_create (struct coord_comm instance, caps_identifier pr_id)

void	coord_printer_id_free (struct coord_comm *instance, caps_identifier pr_id)

int	coord_printer_info_setup (struct coord_comm instance, caps_identifier pr_id, const char name, const char info, const char location, const char vendor, const char model, struct caps_supported_mime_list *mime_list)

int	coord_printer_ppd_setup (struct coord_comm *instance, caps_identifier pr_id, int fd)

int	coord_printer_state_setup (struct coord_comm instance, caps_identifier pr_id, enum caps_printing_provider_state state_id, enum caps_printing_provider_reason reason_id, const char state_message)

int	coord_job_id_get_next_available (struct coord_comm instance, caps_identifier pr_id, caps_identifier job_id)

int	coord_job_data_get (struct coord_comm instance, caps_identifier pr_id, caps_identifier job_id, int job_fh, char **job_params)

int	coord_job_mark_finished (struct coord_comm *instance, caps_identifier pr_id, caps_identifier job_id)

int	coord_job_progress_report (struct coord_comm instance, caps_identifier pr_id, caps_identifier job_id, const struct caps_job_progression prog)

int	coord_job_state_set (struct coord_comm instance, caps_identifier pr_id, caps_identifier job_id, enum caps_printing_job_state state_id, enum caps_printing_job_reason state_reason_id, const char state_message)

int	coord_notifiers_process (struct coord_comm *instance)

static bool	caps_pp_check_printing_id (struct caps_pp_handle *instance, caps_identifier pr_id)

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

Detailed Description

Copyright: GNU Lesser General Public License 2.1

Author: Jürgen Borleis

Warning: Use as experimental

Macro Definition Documentation

◆ CAPS_DRIVER_INI_NAME

#define CAPS_DRIVER_INI_NAME "driver-ini"

This is the long command line parameter handled by libcapsprovider in caps_pp_instance_runtime_prepare().
This parameter defines the name of the driver's INI file at run-time, expected in the CAPS Printer Driver Database Directory directory (usually /usr/share/caps/drivers).

◆ CAPS_DRIVER_INI_NAME_SHORT

#define CAPS_DRIVER_INI_NAME_SHORT 'f'

Same usage than CAPS_DRIVER_INI_NAME, but the short form

◆ CAPS_PARAM_DIRECTORY_NAME

#define CAPS_PARAM_DIRECTORY_NAME "parameter-dir"

This is the long command line parameter handled by libcapsprovider in caps_pp_instance_runtime_prepare().
This parameter defines the name of the device's parameter directory, expected in the CAPS Printer Device Database Directory directory (usually /var/lib/caps).

◆ CAPS_PARAM_DIRECTORY_NAME_SHORT

#define CAPS_PARAM_DIRECTORY_NAME_SHORT 'd'

Same usage than CAPS_PARAM_DIRECTORY_NAME, but the short form

Typedef Documentation

◆ DBusConnection

typedef struct DBusConnection DBusConnection

just a forward declaration

Function Documentation

◆ coord_connection_create()

int coord_connection_create	(	struct coord_comm *	instance,
		const struct caps_pp_notifier *	notifier,
		void *	data
	)

Create and establish a communication connection to the printing coordinator

Parameters

[in,out]	instance	The communication instance
[in]	notifier	Notifier callback for job status changes
[in]	data	The data parameter for the notifier callback

Return values

0	On success
-EIO	Failed to connect to DBUS
-EBUSY	Failed to register at the CAPS universe DBUS service
-ENOMSG	Failed to attach to CAPS universe DBUS signals to establisch notifiers

◆ coord_connection_destroy()

void coord_connection_destroy ( struct coord_comm * instance )

Close the communication connection to the printing coordinator

Parameters

[in] instance The communication instance

◆ coord_printer_id_create()

int coord_printer_id_create	(	struct coord_comm *	instance,
		caps_identifier *	pr_id
	)

Retrieve a unique printing provider ID

Parameters

[in]	instance	The communication instance
[out]	pr_id	Where to store the ID

Return values

0	on success
-EIO	Failed to connect to DBUS
-EINVAL	Bad reply

The printing provider ID is the base for all communication with the printing coordinator.

With this identifier the printing service provider registers itself at the coordinator. All further requests will need this identifier.

Todo:: rename it -> printing_provider_id or similar

Developer's corner

Note: Counterpart is dbus_CreatePrinterId_dispatch()

◆ coord_printer_id_free()

void coord_printer_id_free	(	struct coord_comm *	instance,
		caps_identifier	pr_id
	)

Free a unique printing provider ID at the printing coordinator

Parameters

[in]	instance	The communication instance
[out]	pr_id	The printing provider ID to free

Developer's corner

Counterpart is dbus_FreePrinterId_dispatch()

◆ coord_printer_info_setup()

int coord_printer_info_setup	(	struct coord_comm *	instance,
		caps_identifier	pr_id,
		const char *	name,
		const char *	info,
		const char *	location,
		const char *	vendor,
		const char *	model,
		struct caps_supported_mime_list *	mime_list
	)

Setup some static information about the printer.

Parameters

[in]	instance	The communication instance
[in]	pr_id	Printer ID this information is for
[in]	name	Printer's name, used to identify
[in]	info	Some free information about the printer
[in]	location	Where the printer is located
[in]	vendor	Vendor name
[in]	model	Model name
[in]	mime_list	List of supported MIME types (content gets copied)

Return values

0	On success
-ENODEV	pr_id is invalid
-EPERM	No permission to change the information
-EBUSY	Information is already set (strange failure!)
-EIO	Failed to communicate with the CAPS universe service RPC
-EINVAL	Bad reply from the CAPS universe service RPC

This information is used by the printing coordinator for its clients to identify a printer

Note: It's possible to call this function again if the information content changes.

Developer's corner

Counterpart is dbus_SetPrinterInfo_dispatch()

◆ coord_printer_ppd_setup()

int coord_printer_ppd_setup	(	struct coord_comm *	instance,
		caps_identifier	pr_id,
		int	fd
	)

Provide the PostScript Printer Description file (aka PPD)

Parameters

[in]	instance	The communication instance
[in]	pr_id	Printer ID this PPD is for
[in]	fd	File descriptor to the PPD file

Return values

0	On success
-ENODEV	pr_id is invalid
-EPERM	No permission to change the information
-EIO	Failed to communicate with the CAPS universe service RPC
-EINVAL	Bad reply from the CAPS universe service RPC or file descriptor fd is invalid

The PPD describes specific features of the printing provider.

Precondition: The fd file descriptor must be valid and opened for reading; pr_id must be a valid ID (e.g. not negative)

Developer's corner

Note: Counterpart is dbus_SetPPDDefinition_dispatch()

◆ coord_printer_state_setup()

int coord_printer_state_setup	(	struct coord_comm *	instance,
		caps_identifier	pr_id,
		enum caps_printing_provider_state	state_id,
		enum caps_printing_provider_reason	reason_id,
		const char *	state_message
	)

Setup the state of a printing provider

Parameters

[in]	instance	The communication instance
[in]	pr_id	Printer ID this state information is for
[in]	state_id	New state identifier
[in]	reason_id	New reason identifier why the printer is in state state_id
[in]	state_message	A utf8 string forming the reason description (for human readers and in local national language)

Return values

0	On success
-ENODEV	pr_id is invalid
-EPERM	No permission to change the information
-EIO	Failed to communicate with the CAPS universe service RPC
-EINVAL	Bad reply from the CAPS universe service RPC or invalid state or printer should become visible but has incomplete base information

Whenever the printer's state changes, the corresponding printing provider must call this function to ensure a useful feedback for the user.

Precondition: pr_id must be a valid ID (e.g. not negative); state_id must be valid (e.g. > LIBCAPS_PP_STATE_INVISIBLE); reason_id must be valid (e.g. > LIBCAPS_PP_REASON_NONE); state_message must be valid (e.g. point to valid string)

Developer's corner

Note: Counterpart is dbus_SetPrinterState_dispatch()

◆ coord_job_id_get_next_available()

int coord_job_id_get_next_available	(	struct coord_comm *	instance,
		caps_identifier	pr_id,
		caps_identifier *	job_id
	)

Retrieve the ID of the next waiting printing job

Parameters

[in]	instance	The communication instance
[in]	pr_id	Printer ID this state information is for
[out]	job_id	Where to store the printing job ID

Return values

0	On success (*job_id is valid)
-ENODATA	No job available, try again later
-ENODEV	pr_id is invalid
-EPERM	No permission to this printer and its jobs
-EIO	Failed to communicate with the CAPS universe service RPC
-EINVAL	Bad reply from the CAPS universe service RPC

Precondition: pr_id must be a valid ID (e.g. not negative)

Developer's corner

Note: Counterpart is dbus_GetJobId_dispatch()

◆ coord_job_data_get()

int coord_job_data_get	(	struct coord_comm *	instance,
		caps_identifier	pr_id,
		caps_identifier	job_id,
		int *	job_fh,
		char **	job_params
	)

Retrieve the printing data and printing parameter for a specific printing job

Parameters

[in]	instance	The communication instance
[in]	pr_id	Printer ID this job is assigned to
[in]	job_id	Printing job ID to get the data/parameters from
[out]	job_fh	Where to store the printing job file descriptor (e.g. data)
[out]	job_params	Where to store the printing job parameters

Return values

0	on success (job_fh and job_params are valid)
-ENODEV	pr_id is invalid
-EIO	Failed to communicate with the CAPS universe service RPC or missing call to coord_job_id_get_next_available()
-EPERM	Calling provider isn't the owner of this printer or print job
-EINVAL	Bad reply from the CAPS universe service RPC or invalid job_id

Note: The file descriptor is opened for reading; The params pointer is never NULL, if no printing parameters are defined an empty string is returned

Postcondition: The returned params string must be freed after use

Todo:: pr_id is redundant due to a job ID is already assigned to one printer

Developer's corner

Note: Counterpart is dbus_GetJob_dispatch()

◆ coord_job_mark_finished()

int coord_job_mark_finished	(	struct coord_comm *	instance,
		caps_identifier	pr_id,
		caps_identifier	job_id
	)

Mark a specific printing job as done

Parameters

[in]	instance	The communication instance
[in]	pr_id	Printer ID this job is assigned to
[in]	job_id	Printing job ID to mark as done

Return values

0	On success
-ENODEV	pr_id is invalid
-EIO	Failed to communicate with the CAPS universe service RPC
-EPERM	Calling provider isn't the owner of this printer or print job
-EINVAL	Bad reply from the CAPS universe service RPC or invalid job_id

This call instructs the printing coordinator to remove the job from its queue.

Todo:: pr_id is redundant due to a job ID is already assigned to one printer

Developer's corner

Note: Counterpart is dbus_mark_job_finished()

◆ coord_job_progress_report()

int coord_job_progress_report	(	struct coord_comm *	instance,
		caps_identifier	pr_id,
		caps_identifier	job_id,
		const struct caps_job_progression *	prog
	)

Report printing progression for a specific job

Parameters

[in]	instance	The communication instance
[in]	pr_id	Printer ID this job is assigned to
[in]	job_id	Printing job ID to report progression for
[in]	prog	Progression info

Return values

0	Progression reported
-ENODEV	pr_id is invalid
-EIO	Failed to communicate with the CAPS universe service RPC
-EPERM	Calling provider isn't the owner of this printer or print job
-EINVAL	Bad reply from the CAPS universe service RPC or invalid job_id

Attention: According to caps_job_progression, all members except caps_job_progression::flags must not '0' (e.g. follow the documentation in caps_job_progression).

Precondition: Content of prog is invalid

Todo:: pr_id is redundant due to a job ID is already assigned to one printer

Developer's corner

Note: Counterpart is dbus_JobSetProgression_dispatch()

◆ coord_job_state_set()

int coord_job_state_set	(	struct coord_comm *	instance,
		caps_identifier	pr_id,
		caps_identifier	job_id,
		enum caps_printing_job_state	state_id,
		enum caps_printing_job_reason	state_reason_id,
		const char *	state_message
	)

Update the state of a specific job

Parameters

[in]	instance	The communication instance
[in]	pr_id	Printer ID this job is assigned to
[in]	job_id	Printing job ID to report progression for
[in]	state_id	Job's new state
[in]	state_reason_id	Job's new state reason
[in]	state_message	Job's new state message

Return values

-ENODEV	Printer is already gone
-EIO	Failed to communicate with the CAPS universe service RPC
-EPERM	Calling provider isn't the owner of this printer or print job
-EINVAL	Bad reply from the CAPS universe service RPC or invalid job_id or state_id is invalid

Precondition: state_id must be >= LIBCAPS_PJ_STATE_PROCESSING; state_message must not NULL (but can point to an empty string)

Todo:: pr_id is redundant due to a job ID is already assigned to one printer

Developer's corner

Note: Counterpart is dbus_job_state_update()

◆ coord_notifiers_process()

int coord_notifiers_process ( struct coord_comm * instance )

Run the DBUS message queue and process events

Parameters

[in] instance The communication instance

Returns: 0 on success, negative errno else

◆ caps_pp_check_printing_id()

static bool caps_pp_check_printing_id	(	struct caps_pp_handle *	instance,
		caps_identifier	pr_id
	)

inlinestatic

◆ 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()

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ CAPS_DRIVER_INI_NAME

◆ CAPS_DRIVER_INI_NAME_SHORT

◆ CAPS_PARAM_DIRECTORY_NAME

◆ CAPS_PARAM_DIRECTORY_NAME_SHORT

Typedef Documentation

◆ DBusConnection

Function Documentation

◆ coord_connection_create()

◆ coord_connection_destroy()

◆ coord_printer_id_create()

Developer's corner

◆ coord_printer_id_free()

Developer's corner

◆ coord_printer_info_setup()

Developer's corner

◆ coord_printer_ppd_setup()

Developer's corner

◆ coord_printer_state_setup()

Developer's corner

◆ coord_job_id_get_next_available()

Developer's corner

◆ coord_job_data_get()

Developer's corner

◆ coord_job_mark_finished()

Developer's corner

◆ coord_job_progress_report()

Developer's corner

◆ coord_job_state_set()

Developer's corner

◆ coord_notifiers_process()

◆ caps_pp_check_printing_id()

◆ state_message_translate()