libcapsprovider-job.c File Reference

Job related functions. More...

Functions
static void	check_for_valid_job (const struct caps_pp_document_desc *job)
static struct caps_pp_handle *	job_to_instance (const struct caps_pp_document_desc *job)
static void	job_init (struct caps_pp_document_desc *job)
static void	job_destroy (struct caps_pp_document_desc *job)
static struct caps_pp_document_desc *	job_create (void)
caps_identifier	caps_pp_job_id_get (struct caps_pp_document_desc *job)
const char *	caps_pp_job_parameter_get (struct caps_pp_document_desc *job)
int	caps_pp_job_fh_get (struct caps_pp_document_desc *job)
static int	get_job_data_from_coordinator (struct caps_pp_document_desc *job)
int	notifier_job_change (void *data, caps_identifier pr_id, caps_identifier job_id)
int	caps_pp_job_get (struct caps_pp_handle *instance, struct caps_pp_document_desc **job, volatile sig_atomic_t *terminate)
int	caps_pp_job_check (struct caps_pp_handle *instance, struct caps_pp_document_desc **job)
void	caps_pp_job_done (struct caps_pp_document_desc *job)
void	caps_pp_job_progression_report (struct caps_pp_document_desc *job, const struct caps_job_progression *prog)
int	caps_pp_job_state_update (struct caps_pp_document_desc *job, enum caps_printing_job_state state, enum caps_printing_job_reason reason, const char *message)

Detailed Description

Copyright

GNU Lesser General Public License 2.1

Author

Jürgen Borleis

Warning

Use as experimental

This is a collection of routines which deals with printing jobs. The externally available API is to hide internal implementation details of caps_pp_document_desc

Function Documentation

check_for_valid_job()

static void check_for_valid_job ( const struct caps_pp_document_desc *  job )

static

Check if the job can be used

Parameters

[in]

job

The job to validate

Note

Does not return if the job is invalid

job_to_instance()

static struct caps_pp_handle * job_to_instance ( const struct caps_pp_document_desc *  job )

static

Convert a job handle into an instance handle

Parameters

[in]

job

The job handle to convert

Return values

The	instance handle

Note

Does not return if the job is invalid

job_init()

static void job_init ( struct caps_pp_document_desc *  job )

static

Prepare a new job structure with initialized info

Parameters

[in]

job

The job to initialize

This prepares the content to safely call job_destroy() on it at every state.

Note

The returned job is still invalid (refer check_for_valid_job())

job_destroy()

static void job_destroy ( struct caps_pp_document_desc *  job )

static

Clean up all job related resources, invalidate its content and frees its memory

Parameters

[in]

job

The job to clean up

Note

Closing the filehandle should remove the job file as well if it was created with caps_helper_invisible_file_create().

job_create()

static struct caps_pp_document_desc * job_create ( void  )

static

Create a new job structure, intended to forward it to the caller

Returns

Pointer to a new job structure

Note

This function does not return in case of a memory failure

Postcondition

The returned memory needs to be freed after use

get_job_data_from_coordinator()

static int get_job_data_from_coordinator ( struct caps_pp_document_desc *  job )

static

Retrieve the printing job and its parameter

Parameters

[in,out]

job

Where to store job's data

Return values

0	On success, job is now valid
-ENODATA	No job available
-ENODEV	pr_id is invalid
-EPERM	No permission to this printer and its jobs
-EIO	Failed to connect the CAPS universe service RPC
-EINVAL	Bad reply from the CAPS universe service RPC

Okay, there is a job waiting for us at the printing coordinator. Let's get the job data itself and its printing parameters.

Precondition

The job caps_pp_document_desc::instance must already be valid

Postcondition

caps_pp_document_desc::parameters must be freed after use

notifier_job_change()

int notifier_job_change	(	void *	data,
		caps_identifier	pr_id,
		caps_identifier	job_id
	)

Called by the DBUS interface, if the job state changes at the printing coordinator

Parameters

[in]	data	Pointer to anonymous data, defined when coord_connection_create() is called
[in]	pr_id	Dedicated printing provider ID the job status changes
[in]	job_id	Job ID the status changes

Returns

0 on success

This function is called whenever the job state changes at a printing coordinator. It means it gets called even if the job isn't for this running provider. So this routine must sort out all jobs dedicated for different printing providers.

Called-back when coord_notifiers_process() is called.

Note

Access to the job dedicated for a different provider is rejected by the printing coordinator. So even we receive it's signal, we cannot get control about its job.