caps-dbus-interface.h File Reference

DBUS related API declaration. More...

Go to the source code of this file.

Functions
void	dbus_print_argument_failure (DBusMessage *message, const DBusError *error)
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)
int64_t	dbus_receive_single_i64 (DBusMessage *message, DBusError *error)
DBusHandlerResult	caps_dbus_provider_dispatch (DBusConnection *connection, DBusMessage *message, void *data)
DBusHandlerResult	caps_dbus_client_dispatch (DBusConnection *connection, DBusMessage *message, void *data)
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)
void	dbus_provider_send_job_change_notifier (DBusConnection *connection, caps_identifier pr_id, caps_identifier job_id)
void *	dbus_coordinator_allocate (DBusBusType dbus, void *data)
void	dbus_coordinator_loop (void *handle, volatile sig_atomic_t *quit)
void	dbus_coordinator_exit (void *handle)

Detailed Description

Copyright

GNU Lesser General Public License 2.1

Author

Jürgen Borleis

Function Documentation

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_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_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

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

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

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.

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

dbus_coordinator_allocate()

void * dbus_coordinator_allocate	(	DBusBusType	dbus,
		void *	data
	)

Prepare the DBUS interface for a full featured communication

Parameters

[in]	dbus	Type of DBUS to connect to
[in]	data	Pointer to use in all DBUS callbacks (here: the main coordinator structure)

Return values

Pointer	A DBUS connection (transparent)
NULL	Connection impossible

dbus_coordinator_loop()

void dbus_coordinator_loop	(	void *	handle,
		volatile sig_atomic_t *	quit
	)

Todo:

If 10 seconds no printing provider is connected, terminate this loop

dbus_coordinator_exit()

void dbus_coordinator_exit

(

void *

handle

)