dbus-client-interface.c File Reference

Client side DBUS CAPS printing cooordinator connection for printing client. More...

Data Structures
struct	dbus_method_list

Functions
static DBusHandlerResult	dbus_report_error (DBusConnection *connection, DBusMessage *message, const char *error_name, const char *error_message)
static DBusHandlerResult	dbus_report_unknown_pr_id (DBusConnection *connection, DBusMessage *message)
static void	dbus_job_user_complete_notifier (DBusConnection *connection, caps_identifier pr_id, caps_identifier job_id)
static DBusHandlerResult	dbus_cancel_printing_job (DBusConnection *connection, DBusMessage *message, struct caps_coordinator *database)
static DBusHandlerResult	dbus_get_printing_job_state (DBusConnection *connection, DBusMessage *message, struct caps_coordinator *database)
static DBusHandlerResult	dbus_commit_printing_job (DBusConnection *connection, DBusMessage *message, struct caps_coordinator *database)
static DBusHandlerResult	dbus_get_printers_state_dispatch (DBusConnection *connection, DBusMessage *message, struct caps_coordinator *database)
static DBusHandlerResult	dbus_printing_job_progression_get (DBusConnection *connection, DBusMessage *message, struct caps_coordinator *database)
static DBusHandlerResult	dbus_get_printers_PPD_dispatch (DBusConnection *connection, DBusMessage *message, struct caps_coordinator *database)
static DBusHandlerResult	dbus_get_printers_info_dispatch (DBusConnection *connection, DBusMessage *message, struct caps_coordinator *database)
static DBusHandlerResult	dbus_get_printer_list_dispatch (DBusConnection *connection, DBusMessage *message, struct caps_coordinator *database)
static int	check_compatibility (int cmajor, int cminor, int cmicro)
static DBusHandlerResult	dbus_client_introduction_dispatch (DBusConnection *connection, DBusMessage *message, struct caps_coordinator *database)
void	dbus_client_send_provider_change_notifier (DBusConnection *connection, caps_identifier pr_id, const struct object_state_prn *pstate)
void	dbus_client_send_job_change_notifier (DBusConnection *connection, caps_identifier pr_id, caps_identifier job_id, const struct object_state_job *jstate, const struct object_progression_job *jprog)
static DBusHandlerResult	distribute_client_messages (DBusConnection *connection, DBusMessage *message, struct caps_coordinator *database)
DBusHandlerResult	caps_dbus_client_dispatch (DBusConnection *connection, DBusMessage *message, void *data)

Variables
static const struct dbus_method_list	client_rpc_method_list []
static const char *	introspect_xml_client_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 clients.

Function Documentation

dbus_report_error()

static DBusHandlerResult dbus_report_error ( DBusConnection *  connection, DBusMessage *  message, const char *  error_name, const char *  error_message  )

static

Convenience function to report an error via DBUS

Parameters

[in]	connection	DBUS connection
[in]	message	DBUS message (already pre-processed for this method)
[in]	error_name	A DBUS conform path (...strange thing)
[in]	error_message	The error messagte itself

Returns

DBUS_HANDLER_RESULT_HANDLED

Note

This function does not return in case of a memory failure

dbus_report_unknown_pr_id()

static DBusHandlerResult dbus_report_unknown_pr_id ( DBusConnection *  connection, DBusMessage *  message  )

static

dbus_job_user_complete_notifier()

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

static

Notify clients about a job cancellation and completion, made by the user

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.

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

dbus_cancel_printing_job()

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

static

DBUS printing client RPC: cancel an already committed specific printing 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	If an answer to the client was sent
DBUS_HANDLER_RESULT_NOT_YET_HANDLED	If the received parameters were invalid

Related to CANCEL_PRINTING_JOB_METHOD and CANCEL_PRINTING_JOB_XML

Note

It's a regular use-case the printing job is already gone from the list. It's a run-time setup feature

Does not return in case of memory failure

Related to the job notifier state changes. Calling this functions deals with the state transistions:

• from LIBCAPS_PJ_STATE_QUEUED to LIBCAPS_PJ_STATE_CANCELED to LIBCAPS_PJ_STATE_COMPLETED
• from LIBCAPS_PJ_STATE_PROCESSING or LIBCAPS_PJ_STATE_PROCESSING_STOPPED to LIBCAPS_PJ_STATE_CANCELED

dbus_get_printing_job_state()

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

static

DBUS printing client RPC: get the processing state of 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, ...)

Return values

DBUS_HANDLER_RESULT_HANDLED	If an answer to the client was sent
DBUS_HANDLER_RESULT_NOT_YET_HANDLED	If the received parameters were invalid

Related to GET_PRINTING_JOB_STATE_METHOD and GET_PRINTING_JOB_STATE_XML

Note

It's a regular use-case the printing job is already gone from the list. It's a run-time setup feature

Does not return in case of memory failure

dbus_commit_printing_job()

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

static

DBUS printing client RPC: commit a new printing job to the 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, ...)

Return values

DBUS_HANDLER_RESULT_HANDLED	If an answer to the client was sent
DBUS_HANDLER_RESULT_NOT_YET_HANDLED	If the received parameters were invalid

Related to DBUS method COMMIT_PRINTING_JOB_METHOD and introspection COMMIT_PRINTING_JOB_METHOD_XML.

Counterpart in libcapsclient is caps_cl_job_commit()

Note

Does not return in case of memory failure

Todo:

What happens to the jobfh, if it isn't used due to an error?

dbus_get_printers_state_dispatch()

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

static

DBUS printing client RPC: get the working state of a specific printing provider

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	If an answer to the client was sent
DBUS_HANDLER_RESULT_NOT_YET_HANDLED	If the received parameters were invalid

Related to DBUS method GET_PRINTERS_STATE_METHOD and introspection GET_PRINTERS_STATE_XML

Counterpart in libcapsclient is caps_cl_printer_state_get()

Note

It's a regular use-case the printing provider is already gone.

Does not return in case of memory failure

dbus_printing_job_progression_get()

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

static

DBUS printing client RPC: get the printing progression info for a specified 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	If an answer to the client was sent
DBUS_HANDLER_RESULT_NOT_YET_HANDLED	If the received parameters were invalid

Related to GET_PRINTING_JOB_PROGRESSION_METHOD and GET_PRINTING_JOB_PROGRESSION_XML

Note

It's a regular use-case if the job is already gone.

Counterpart is caps_cl_job_progression_get()

dbus_get_printers_PPD_dispatch()

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

static

DBUS printing client RPC: get the PPD information a specific printing provider

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	If an answer to the client was sent
DBUS_HANDLER_RESULT_NOT_YET_HANDLED	If the received parameters were invalid

Related to GET_PRINTERS_PPD_METHOD and GET_PRINTERS_PPD_XML

Note

It's a regular use-case if the printing provider is already gone.

Counterpart is caps_cl_printer_PPD_get()

Todo:

How to return a real error value? And how to return an invalid file handle?

dbus_get_printers_info_dispatch()

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

static

DBUS printing client RPC: get generic information about a specific printing provider

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	If an answer to the client was sent
DBUS_HANDLER_RESULT_NOT_YET_HANDLED	If the received parameters were invalid

Related to GET_PRINTERS_INFO_METHOD and GET_PRINTERS_INFO_XML

Note

It's a regular use-case if the printing provider is already gone.

Does not return in case of memory failure

Counterpart is caps_cl_printer_info_get() in libcapsclient.c

Todo:

Deal with the fact, the printer in question doesn't exist (anymore)

dbus_get_printer_list_dispatch()

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

static

DBUS printing client RPC: get a list of currently available printing providers

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	If an answer to the client was sent
DBUS_HANDLER_RESULT_NOT_YET_HANDLED	If the received parameters were invalid

Related to GET_PRINTER_LIST_METHOD and GET_PRINTER_LIST_XML parameters

Note

Does not return in case of memory failure

Counterpart is caps_cl_printer_list_get()

check_compatibility()

static int check_compatibility ( int  cmajor, int  cminor, int  cmicro  )

static

Check if this version can service callers libcapsclient version

Parameters

[in]	cmajor	Client's libcapsclient major version
[in]	cminor	Client's libcapsclient minor version
[in]	cmicro	Client's libcapsclient micro version

Return values

0	Callers libcapsclient version can be served
-ENOSYS	No way to service callers libcapsclient version

If we are called by an older libcapsclient we must reject the connection, if the expected (by the client) and currently used dbus interface cannot work together.

dbus_client_introduction_dispatch()

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

static

DBUS printing client RPC: the client introduces itself

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	If an answer to the client was sent
DBUS_HANDLER_RESULT_NOT_YET_HANDLED	If the received parameters were invalid

Currently we ignore the content of the message. In future releases it may help to be backward compatible.

Related to DBUS method CL_INTRODUCTION_METHOD and introspection CL_INTRODUCTION_XML parameters

Counterpart in libcapsclient is client_introduction()

dbus_client_send_provider_change_notifier()

void dbus_client_send_provider_change_notifier	(	DBusConnection *	connection,
		caps_identifier	pr_id,
		const struct object_state_prn *	pstate
	)

DBUS printing client RPC: notify clients about a change in the available printing provider list

Parameters

[in]	connection	DBUS connection
[in]	pr_id	Printer identifier which has changed (to be discussed!)
[in]	pstate	Current printer state (can be NULL)

A printing provider change event can be of:

• new printing provider available
  • in this case pstate is NULL, only the base information is available
• printing provider is gone (after that, all queries for this provider or its jobs will fail)
• printing provider's state has changed (offline, failure...)
• printing provider's info has changed

Note

This function is called from the provider's side of this DBUS implementation. Should not happen, but cannot be avoided.

dbus_client_send_job_change_notifier()

void dbus_client_send_job_change_notifier	(	DBusConnection *	connection,
		caps_identifier	pr_id,
		caps_identifier	job_id,
		const struct object_state_job *	jstate,
		const struct object_progression_job *	jprog
	)

DBUS printing client RPC: notify clients about a change in a job status

Parameters

[in]	connection	DBUS connection
[in]	pr_id	Printer identifier where the job state has changed
[in]	job_id	Job identifier where something has changed
[in]	jstate	New job's state description (can be NULL)
[in]	jprog	New job's progression description (can be NULL)

A job change can be of:

• job finshed
• job stopped due to some error when processing
• corresponding printing provider is gone (job is discarded)
• the job has made some progression

Note

This function is called from the provider's side of this DBUS implementation. Should not happen, but cannot be avoided.

Todo:

Assemble a notifier message with only required members to limit its size.

distribute_client_messages()

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

static

DBUS printing client RPC: process method calls from the printing client 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

Return values

DBUS_HANDLER_RESULT_HANDLED	If an answer to the client was sent
DBUS_HANDLER_RESULT_NOT_YET_HANDLED	If the received parameters were invalid or the called method is unknown

Todo:

Mark the connection as invalid: it seems the client cannot really communicate with us

caps_dbus_client_dispatch()

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

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

Parameters

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

Return values

DBUS_HANDLER_RESULT_HANDLED	If an answer to the client was sent
DBUS_HANDLER_RESULT_NOT_YET_HANDLED	If the received parameters were invalid or the called method is unknown or the data parameter was NULL

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

Variable Documentation

client_rpc_method_list

const struct dbus_method_list client_rpc_method_list[]

static

Initial value:

= {
    {
        .method_name =  "ClIntroduction" ,
        .dispatch_fn = dbus_client_introduction_dispatch,
    }, {
        .method_name =  "GetPrinterList" ,
        .dispatch_fn = dbus_get_printer_list_dispatch,
    }, {
        .method_name =  "GetPrintersInfo" ,
        .dispatch_fn = dbus_get_printers_info_dispatch,
    }, {
        .method_name =  "GetPrintersPPD" ,
        .dispatch_fn = dbus_get_printers_PPD_dispatch,
    }, {
        .method_name =  "GetPrintersState" ,
        .dispatch_fn = dbus_get_printers_state_dispatch,
    }, {
        .method_name =  "CommitPrintingJob" ,
        .dispatch_fn = dbus_commit_printing_job,
    }, {
        .method_name =  "GetPrintingJobState" ,
        .dispatch_fn = dbus_get_printing_job_state,
    }, {
        .method_name =  "GetPrintingJobProgression" ,
        .dispatch_fn = dbus_printing_job_progression_get,
    }, {
        .method_name =  "CancelPrintingJob" ,
        .dispatch_fn = dbus_cancel_printing_job,
    },
}

introspect_xml_client_config

const char* introspect_xml_client_config

static