Server side DBUS CAPS printing cooordinator connection for printing providers. More...

Data Structures
struct	dbus_method_list

Macros
#define	HASHWORDBITS 32

Functions
DBusHandlerResult	dbus_return_i32 (DBusConnection connection, DBusMessage message, int32_t val)

DBusHandlerResult	dbus_return_i64 (DBusConnection connection, DBusMessage message, int64_t val)

DBusHandlerResult	dbus_return_file_handle (DBusConnection connection, DBusMessage message, int fh)

void	dbus_print_argument_failure (DBusMessage message, const DBusError error)

int64_t	dbus_receive_single_i64 (DBusMessage message, DBusError error)

static unsigned	__hash_string (const unsigned char *string)

static unsigned	provider_property_create (DBusMessage *message)

static void	dbus_job_change_notifier (DBusConnection connection, caps_identifier pr_id, caps_identifier job_id, const struct object_state_job state)

static void	provider_job_queue_drain (DBusConnection connection, struct caps_coordinator database, caps_identifier pr_id, const struct object_state_job *state)

static DBusHandlerResult	dbus_CreatePrinterId_dispatch (DBusConnection connection, DBusMessage message, struct caps_coordinator *database)

static void	dbus_provider_termination_notifier (DBusConnection *connection, caps_identifier pr_id)

static DBusHandlerResult	dbus_FreePrinterId_dispatch (DBusConnection connection, DBusMessage message, struct caps_coordinator *database)

static DBusHandlerResult	dbus_SetPrinterState_dispatch (DBusConnection connection, DBusMessage message, struct caps_coordinator *database)

static DBusHandlerResult	dbus_GetJobId_dispatch (DBusConnection connection, DBusMessage message, struct caps_coordinator *database)

static DBusHandlerResult	dbus_SetPrinterInfo_dispatch (DBusConnection connection, DBusMessage message, struct caps_coordinator *database)

static DBusHandlerResult	dbus_JobSetProgression_dispatch (DBusConnection connection, DBusMessage message, struct caps_coordinator *database)

static DBusHandlerResult	dbus_GetJob_dispatch (DBusConnection connection, DBusMessage message, struct caps_coordinator *database)

static DBusHandlerResult	dbus_job_state_update (DBusConnection connection, DBusMessage message, struct caps_coordinator *database)

static void	dbus_job_finished_notifier (DBusConnection *connection, caps_identifier pr_id, caps_identifier job_id)

static DBusHandlerResult	dbus_mark_job_finished (DBusConnection connection, DBusMessage message, struct caps_coordinator *database)

static DBusHandlerResult	dbus_SetPPDDefinition_dispatch (DBusConnection connection, DBusMessage message, struct caps_coordinator *database)

void	dbus_provider_send_job_change_notifier (DBusConnection *connection, caps_identifier pr_id, caps_identifier job_id)

static DBusHandlerResult	process_provider_messages (DBusConnection connection, DBusMessage message, struct caps_coordinator *database)

static void	provider_remove_on_termination (DBusConnection connection, const char s, struct caps_coordinator *database)

static DBusHandlerResult	process_provider_signal (DBusConnection connection, DBusMessage message, struct caps_coordinator *database)

DBusHandlerResult	caps_dbus_provider_dispatch (DBusConnection connection, DBusMessage message, void *data)

Variables
static const struct dbus_method_list	provider_rpc_method_list []

static const char *	introspect_xml_provider_config

Detailed Description

Copyright: GNU Lesser General Public License 2.1

Author: Jürgen Borleis

Warning: Use as experimental

This is the DBUS interface for printing providers.

Macro Definition Documentation

◆ HASHWORDBITS

#define HASHWORDBITS 32

Define the size in bits of a simple hash computed from a string

Function Documentation

◆ dbus_return_i32()

DBusHandlerResult dbus_return_i32	(	DBusConnection *	connection,
		DBusMessage *	message,
		int32_t	val
	)

Return a simple int32_t as a return value for a DBUS message

Parameters

[in]	connection	DBUS connection
[in]	message	The message to create an answer to
[in]	val	The `int32_t` to return

Returns: Handler result

◆ dbus_return_i64()

DBusHandlerResult dbus_return_i64	(	DBusConnection *	connection,
		DBusMessage *	message,
		int64_t	val
	)

Return a simple int64_t as a return value for a DBUS message

Parameters

[in]	connection	DBUS connection
[in]	message	The message to create an answer to
[in]	val	The `int64_t` to return

Returns: Handler result

◆ dbus_return_file_handle()

DBusHandlerResult dbus_return_file_handle	(	DBusConnection *	connection,
		DBusMessage *	message,
		int	fh
	)

Return a file handle as a return value for a DBUS message

Parameters

[in]	connection	DBUS connection
[in]	message	The message to create an answer to
[in]	fh	the file handle

Returns: Handler result

Note: What happens to the file handle? Here? On the way to the printing provider?

◆ dbus_print_argument_failure()

void dbus_print_argument_failure	(	DBusMessage *	message,
		const DBusError *	error
	)

Just print a unified error message for all internal DBUS interfaces

Parameters

[in]	message	Just to get the method to show where it happens
[in]	error	The error message to print

◆ dbus_receive_single_i64()

int64_t dbus_receive_single_i64	(	DBusMessage *	message,
		DBusError *	error
	)

Receive a simple message with a single int64_t value

Parameters

[in]	message	The message to create an answer to
[out]	error	Where to store the DBUS error (if any)

Return values

positive	The received `int64_t` value
-1	In case of an error, then *error is valid

Can be used to receive a single printing provider ID or job ID

Postcondition: The caller must free error (via dbus_error_free()) in case of a failure

◆ __hash_string()

static unsigned __hash_string ( const unsigned char * string )

static

Compute the hash value for the given string

Parameters

[in] string String to calculate a hash from

Returns: The calculated hash with at least 32 bits

Defines the so called ‘hashpjw’ function by P.J. Weinberger [see Aho/Sethi/Ullman, COMPILERS: Principles, Techniques and Tools, 1986, 1987 Bell Telephone Laboratories, Inc.]

Value is used to seed the unique provider ID generation.

Note: Stolen from the gettext package (under LGPL as well)

◆ provider_property_create()

static unsigned provider_property_create ( DBusMessage * message )

static

Create some kind of unique value about the counter part of this connection

Parameters

[in] message The (unmodified) message of the counter part

Returns: Some kind of unique number/hash

Precondition: the message must be still unmodified, else the here used value is invalid

◆ dbus_job_change_notifier()

static void dbus_job_change_notifier	(	DBusConnection *	connection,
		caps_identifier	pr_id,
		caps_identifier	job_id,
		const struct object_state_job *	state
	)

static

Notify clients about a job removal

Parameters

[in]	connection	DBUS connection
[in]	pr_id	Corresponding printer ID the job was removed from
[in]	job_id	The ID of the finished job
[in]	state	The first state to report

Separate function just for easier maintenance.

It first sends the abortion notifier and after that the completion notifier to cover all required state changes according to Print Job States and Notifiers.

◆ provider_job_queue_drain()

static void provider_job_queue_drain	(	DBusConnection *	connection,
		struct caps_coordinator *	database,
		caps_identifier	pr_id,
		const struct object_state_job *	state
	)

static

Drain the possibly still filled job queue of a printer

Parameters

[in]	connection	DBUS connection
[in]	database	Our local database (printing providers, jobs, ...)
[in]	pr_id	The printer's ID to drain
[in]	state	Pre-filled state why the queue is to be drained

Ensure a possibly still filled job queue is drained before the printing provider itself is removed. This includes sending notifiers about the print job removal according to Print Job States and Notifiers.

◆ dbus_CreatePrinterId_dispatch()

static DBusHandlerResult dbus_CreatePrinterId_dispatch	(	DBusConnection *	connection,
		DBusMessage *	message,
		struct caps_coordinator *	database
	)

static

DBUS printing provider RPC: create a new printer with a unique identifier

Parameters

[in]	connection	DBUS connection
[in]	message	DBUS message (already pre-processed for this method)
[in]	database	Our local database (printing providers, jobs, ...)

Returns: DBUS_HANDLER_RESULT_HANDLED or DBUS_HANDLER_RESULT_NOT_YET_HANDLED

Must be called first by the printing provider in order to register its printing service in the next step

Related to CREATE_PR_ID_METHOD and CREATE_PR_ID_XML

Developer's corner

Note: Counterpart is coord_printer_id_create()

◆ dbus_provider_termination_notifier()

static void dbus_provider_termination_notifier	(	DBusConnection *	connection,
		caps_identifier	pr_id
	)

static

Notify clients about a printing provider is now gone

Parameters

[in]	connection	DBUS connection
[in]	pr_id	Corresponding printer ID the job was finished on

Separate function just for easier maintenance.

◆ dbus_FreePrinterId_dispatch()

static DBusHandlerResult dbus_FreePrinterId_dispatch	(	DBusConnection *	connection,
		DBusMessage *	message,
		struct caps_coordinator *	database
	)

static

DBUS printing provider RPC: method 'FreePrId' of path '/org/caps/coordinator' at interface 'org.caps.coordinator.printer'

Parameters

[in]	connection	DBUS connection
[in]	message	DBUS message (already pre-processed for this method)
[in]	database	Our local database (printing providers, jobs, ...)

Returns: DBUS_HANDLER_RESULT_HANDLED or DBUS_HANDLER_RESULT_NOT_YET_HANDLED

Related to FREE_PR_ID_METHOD and FREE_PR_ID_XML

If a printing provider is going to go, call this function to remove it from the coordinator

◆ dbus_SetPrinterState_dispatch()

static DBusHandlerResult dbus_SetPrinterState_dispatch	(	DBusConnection *	connection,
		DBusMessage *	message,
		struct caps_coordinator *	database
	)

static

DBUS printing provider RPC: method 'UpdatePrState' of path '/org/caps/printing' at interface 'org.caps.printing.coordinator'

Parameters

[in]	connection	DBUS connection
[in]	message	DBUS message (already pre-processed for this method)
[in]	database	Our local database (printing providers, jobs, ...)

Returns: DBUS_HANDLER_RESULT_HANDLED or DBUS_HANDLER_RESULT_NOT_YET_HANDLED

Related to SET_PRINTER_STATE_METHOD and SET_PRINTER_STATE_XML

◆ dbus_GetJobId_dispatch()

static DBusHandlerResult dbus_GetJobId_dispatch	(	DBusConnection *	connection,
		DBusMessage *	message,
		struct caps_coordinator *	database
	)

static

DBUS printing provider RPC: get the next job identifier from the queue

Parameters

[in]	connection	DBUS connection
[in]	message	DBUS message (already pre-processed for this method)
[in]	database	Our local database (printing providers, jobs, ...)

Returns: DBUS_HANDLER_RESULT_HANDLED or DBUS_HANDLER_RESULT_NOT_YET_HANDLED

Related to GET_JOB_ID_METHOD and GET_JOB_ID_XML

To inform the printing services about a new job we send a signal and all services must call if the job is for them.

◆ dbus_SetPrinterInfo_dispatch()

static DBusHandlerResult dbus_SetPrinterInfo_dispatch	(	DBusConnection *	connection,
		DBusMessage *	message,
		struct caps_coordinator *	database
	)

static

DBUS printing provider RPC: setup the printer details

Parameters

[in]	connection	DBUS connection
[in]	message	DBUS message (already pre-processed for this method)
[in]	database	Our local database (printing providers, jobs, ...)

Returns: DBUS_HANDLER_RESULT_HANDLED or DBUS_HANDLER_RESULT_NOT_YET_HANDLED

Since it requires a 'Printer ID', method 'CreateId' must be called first

Counterpart is coord_printer_info_setup()

◆ dbus_JobSetProgression_dispatch()

static DBusHandlerResult dbus_JobSetProgression_dispatch	(	DBusConnection *	connection,
		DBusMessage *	message,
		struct caps_coordinator *	database
	)

static

DBUS printing provider RPC: report progression in job printing

Parameters

[in]	connection	DBUS connection
[in]	message	DBUS message (already pre-processed for this method)
[in]	database	Our local database (printing providers, jobs, ...)

Returns: DBUS_HANDLER_RESULT_HANDLED or DBUS_HANDLER_RESULT_NOT_YET_HANDLED

Based on some timeout value, a progression report will send out a signal to the clients about this state change. Refer caps_pp_job_progression_report() for details.

Counterpart is coord_job_progress_report()

◆ dbus_GetJob_dispatch()

static DBusHandlerResult dbus_GetJob_dispatch	(	DBusConnection *	connection,
		DBusMessage *	message,
		struct caps_coordinator *	database
	)

static

DBUS printing provider RPC: deliver a specific job.

Parameters

[in]	connection	DBUS connection
[in]	message	DBUS message (already pre-processed for this method)
[in]	database	Our local database (printing providers, jobs, ...)

Returns: DBUS_HANDLER_RESULT_HANDLED or DBUS_HANDLER_RESULT_NOT_YET_HANDLED

The RPC returns the job's filehandle, or 0 if nothing to be print and negative value in case of an error

To inform the printing services about a new job we send a signal and all services must call if the job is for them.

Related to GET_JOB_METHOD and GET_JOB_XML

Precondition: 'int32_t' and 'int' are equal in size (on 32 bit and 64 bit hosts)

◆ dbus_job_state_update()

static DBusHandlerResult dbus_job_state_update	(	DBusConnection *	connection,
		DBusMessage *	message,
		struct caps_coordinator *	database
	)

static

DBUS printing provider RPC: update the state of a job

Parameters

[in]	connection	DBUS connection
[in]	message	DBUS message (already pre-processed for this method)
[in]	database	Our local database (printing providers, jobs, ...)

Return values

DBUS_HANDLER_RESULT_HANDLED	FIXME
DBUS_HANDLER_RESULT_NOT_YET_HANDLED	FIXME

Counterpart is coord_job_state_set()

◆ dbus_job_finished_notifier()

static void dbus_job_finished_notifier	(	DBusConnection *	connection,
		caps_identifier	pr_id,
		caps_identifier	job_id
	)

static

Notify clients about the job is finished (somehow)

Parameters

[in]	connection	DBUS connection
[in]	pr_id	Corresponding printer ID the job was finished on
[in]	job_id	The ID of the finished job

Separate function just for easier maintenance.

◆ dbus_mark_job_finished()

static DBusHandlerResult dbus_mark_job_finished	(	DBusConnection *	connection,
		DBusMessage *	message,
		struct caps_coordinator *	database
	)

static

DBUS printing provider RPC: mark a printing job as finished

Parameters

[in]	connection	DBUS connection
[in]	message	DBUS message (already pre-processed for this method)
[in]	database	Our local database (printing providers, jobs, ...)

Return values

DBUS_HANDLER_RESULT_HANDLED	FIXME
DBUS_HANDLER_RESULT_NOT_YET_HANDLED	FIXME

Note: Marking a printing job this way means we signal this event to the clients. If one is interested it can query the job's state; Counterpart is coord_job_mark_finished()

◆ dbus_SetPPDDefinition_dispatch()

static DBusHandlerResult dbus_SetPPDDefinition_dispatch	(	DBusConnection *	connection,
		DBusMessage *	message,
		struct caps_coordinator *	database
	)

static

DBUS printing provider RPC: setup the printer's PPD file

Parameters

[in]	connection	DBUS connection
[in]	message	DBUS message (already pre-processed for this method)
[in]	database	Our local database (printing providers, jobs, ...)

Returns: DBUS_HANDLER_RESULT_HANDLED or DBUS_HANDLER_RESULT_NOT_YET_HANDLED

The PPD file is used for backward compatibility. The IPP is using it and most of the printing dialouges are using its content to create a printer specific feature menu.

Developer's corner

Note: Counterpart is coord_printer_ppd_setup()

◆ dbus_provider_send_job_change_notifier()

void dbus_provider_send_job_change_notifier	(	DBusConnection *	connection,
		caps_identifier	pr_id,
		caps_identifier	job_id
	)

DBUS printing provider RPC: notify printing providers about a change in their jobs status

Parameters

[in]	connection	DBUS connection
[in]	pr_id	The printing provider where the the job is for
[in]	job_id	Job identifier where something has changed

A job change can be of:

new job
job state changed on client's request (pause, cancel)

Note: This function is called from the client's side of this DBUS implementation. Should not happen, but cannot be avoided.; This function is a copy of the dbus_client_send_job_change_notifier() function, just sent to a different interface

◆ process_provider_messages()

static DBusHandlerResult process_provider_messages	(	DBusConnection *	connection,
		DBusMessage *	message,
		struct caps_coordinator *	database
	)

static

DBUS printing provider RPC: process messages from the printing provider side by passing it to a corresponding function

Parameters

[in]	connection	The DBUS connection info
[in]	message	The message to process
[in,out]	database	The internal printer database

Returns: DBUS_HANDLER_RESULT_HANDLED or DBUS_HANDLER_RESULT_NOT_YET_HANDLED

◆ provider_remove_on_termination()

static void provider_remove_on_termination	(	DBusConnection *	connection,
		const char *	s,
		struct caps_coordinator *	database
	)

static

Remove a provider if its own connection to DBUS is terminated

Parameters

[in]	connection	DBUS connection
[in]	s	The provider's connection info
[in,out]	database	The internal printer database

Since we use the provider's DBUS connection name to use it as its property, we now can use s for the same purpose. E.g. s and #dbus_message_get_sender(message) are the same.

We receive this signal always after the provider's termination. It doesn't matter if the termination was intended or not.

◆ process_provider_signal()

static DBusHandlerResult process_provider_signal	(	DBusConnection *	connection,
		DBusMessage *	message,
		struct caps_coordinator *	database
	)

static

Process a received DBUS signal.

Parameters

[in]	connection	DBUS connection
[in]	message	The DBUS signal message
[in]	database	Our internal state/database

Return values

DBUS_HANDLER_RESULT_HANDLED	Signal processed
DBUS_HANDLER_RESULT_NOT_YET_HANDLED	Signal not for us

Since we have registered a match in dbus_coordinator_allocate() we recieve signals for providers and clients here. We are not interested in clients, but provider_remove_on_termination() sorts them out.

◆ caps_dbus_provider_dispatch()

DBusHandlerResult caps_dbus_provider_dispatch	(	DBusConnection *	connection,
		DBusMessage *	message,
		void *	data
	)

DBUS printing provider RPC: central callback for the provider side of the DBUS interface

Parameters

[in]	connection	DBUS connection
[in]	message	DBUS message
[in]	data	Our local database (printing providers, jobs, ...)

Returns: DBUS_HANDLER_RESULT_HANDLED or DBUS_HANDLER_RESULT_NOT_YET_HANDLED

It seems the data is NULL, if the message is for the introspectice interface! WTF? At least one time the assert() matches when I had used the d-feet tool to view the introspection data

Variable Documentation

◆ provider_rpc_method_list

const struct dbus_method_list provider_rpc_method_list[]

static

◆ introspect_xml_provider_config

const char* introspect_xml_provider_config

static

Data Structures

Macros

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ HASHWORDBITS

Function Documentation

◆ dbus_return_i32()

◆ dbus_return_i64()

◆ dbus_return_file_handle()

◆ dbus_print_argument_failure()

◆ dbus_receive_single_i64()

◆ __hash_string()

◆ provider_property_create()

◆ dbus_job_change_notifier()

◆ provider_job_queue_drain()

◆ dbus_CreatePrinterId_dispatch()

Developer's corner

◆ dbus_provider_termination_notifier()

◆ dbus_FreePrinterId_dispatch()

◆ dbus_SetPrinterState_dispatch()

◆ dbus_GetJobId_dispatch()

◆ dbus_SetPrinterInfo_dispatch()

◆ dbus_JobSetProgression_dispatch()

◆ dbus_GetJob_dispatch()

◆ dbus_job_state_update()

◆ dbus_job_finished_notifier()

◆ dbus_mark_job_finished()

◆ dbus_SetPPDDefinition_dispatch()

Developer's corner

◆ dbus_provider_send_job_change_notifier()

◆ process_provider_messages()

◆ provider_remove_on_termination()

◆ process_provider_signal()

◆ caps_dbus_provider_dispatch()

Variable Documentation

◆ provider_rpc_method_list

◆ introspect_xml_provider_config