Handle print jobs

Retrieve job to print or report a printing is done. More...

Functions
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)
caps_identifier	caps_pp_job_id_get (struct caps_pp_document_desc *job)
void	caps_pp_job_done (struct caps_pp_document_desc *job)
int	caps_pp_job_fh_get (struct caps_pp_document_desc *job)
const char *	caps_pp_job_parameter_get (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

And gain access to some internal job information.

Usage:

struct caps_pp_document_desc *job;
caps_identifier job_id;
int fd;
const char *params;
 
do {
  caps_pp_job_get(instance, &job, NULL);
  job_id = caps_pp_job_id_get(job);
  fd = caps_pp_job_fh_get(job);
  params = caps_pp_job_parameter_get(job);
  caps_pp_job_state_update(job, LIBCAPS_PJ_STATE_PROCESSING, LIBCAPS_PJ_REASON_NONE, NULL);
 
  // <process the job>
  caps_pp_job_progression_report(job, …)
 
  caps_pp_job_state_update(job, LIBCAPS_PJ_STATE_COMPLETED, LIBCAPS_PJ_REASON_COMPLETED_SUCCESSFULLY, NULL);
  caps_pp_job_done(job);
} while(1);

Or:

struct caps_pp_document_desc *job;
caps_identifier job_id;
int fd;
const char *params;
int rc;
 
do {
  rc = caps_pp_job_check(instance, &job);
  if (rc == 0)
    break;
  // <do something different>
} while(1);
 
job_id = caps_pp_job_id_get(job);
fd = caps_pp_job_fh_get(job);
params = caps_pp_job_parameter_get(job);
caps_pp_job_state_update(job, LIBCAPS_PJ_STATE_PROCESSING, LIBCAPS_PJ_REASON_NONE, NULL);
 
// <process the job>
caps_pp_job_progression_report(job, …)
 
caps_pp_job_state_update(job, LIBCAPS_PJ_STATE_COMPLETED, LIBCAPS_PJ_REASON_COMPLETED_SUCCESSFULLY, NULL);
caps_pp_job_done(job);

Todo:

Add more info how to deal with a job, what print parameters are aso.

Function Documentation

caps_pp_job_get()

int caps_pp_job_get	(	struct caps_pp_handle *	instance,
		struct caps_pp_document_desc **	job,
		volatile sig_atomic_t *	terminate
	)

Wait for a printing job and get it if one is present

Parameters

[in]	instance	Provider instance
[out]	job	Where to store the pointer to the document description (transparent content)
[in]	terminate	Where to look for a termination request (can be NULL)

Return values

'0'	On success, *job is then valid
-ENODATA	No job available
-ENODEV	Used printer ID is invalid (should not happen, because the caller is the dev)
-EPERM	No permission to this printer and its jobs (should not happen, because the caller is the dev)
-EIO	Real communication error with the Printing Coordinator (should not happen)
-EINVAL	Bad/unexpected reply from the Printing Coordinator (should not happen)

If *terminate changes to something different than '0' this functions returns with a -EIO

Postcondition

Use caps_pp_job_state_update() and caps_pp_job_progression_report() to give the user a feedback.

Call caps_pp_job_done() to free the resources after the job is done or an error happened

Developer's corner

The communication with the printing coordinator:

The full call stack:

caps_pp_job_check()

int caps_pp_job_check	(	struct caps_pp_handle *	instance,
		struct caps_pp_document_desc **	job
	)

Same as caps_pp_job_get() but returns after a timeout of 500 ms if no job is available

Parameters

[in]	instance	Provider instance
[out]	job	Where to store the pointer to the new document description (transparent content)

Return values

'0'	if a new job is available, *job is then valid
-EAGAIN	No job available, try again later (e.g. timeout)
-ENODATA	No job available (should not happen)
-ENODEV	Used printer ID is invalid (should not happen, because the caller is the dev)
-EPERM	No permission to this printer and its jobs (should not happen, because the caller is the dev)
-EIO	Real communication error with the Printing Coordinator (should not happen)
-EINVAL	Bad/unexpected reply from the Printing Coordinator (should not happen)

Postcondition

Call caps_pp_job_done() to free the resources after the job is done or an error happened

Developer's corner

The communication with the printing coordinator:

Note

The full call stack is equal to caps_pp_job_get().

caps_pp_job_id_get()

caps_identifier caps_pp_job_id_get

(

struct caps_pp_document_desc *

job

)

Get the job's ID

Parameters

[in]

job

The job of interest (from a caps_pp_job_get() call)

Returns

The job's ID

Note

This function does not return in the case of a failure

Developer's corner

caps_pp_job_done()

void caps_pp_job_done

(

struct caps_pp_document_desc *

job

)

Mark the job as done and free related resources

Parameters

[in]

job

The job which is done (from a caps_pp_job_get() call)

This call will free all local resources and thus, is very important.

This call also does the required communication with the printing coordinator to spread the information around this job is finaly done.

Note

This function does not return in the case of a failure

Precondition

A call to caps_pp_job_state_update() to setup the status, why and how it is done

A valid job retrieved via caps_pp_job_check() or caps_pp_job_get()

Developer's corner

The communication with the printing coordinator:

The full call stack:

caps_pp_job_fh_get()

int caps_pp_job_fh_get

(

struct caps_pp_document_desc *

job

)

Get the raw filehandle of the document's file

Parameters

[in]

job

The job of interest (from a caps_pp_job_get() call)

Return values

positive	The raw file handle
negative	Errno, e.g. no filehandle available (should not happen)

Postcondition

The filehandle is a copy, you need to close it when the job is done

Developer's corner

caps_pp_job_parameter_get()

const char * caps_pp_job_parameter_get

(

struct caps_pp_document_desc *

job

)

Get the printing parameters (if any) for this job

Parameters

[in]

job

The job of interest (from a caps_pp_job_get() call)

Return values

Pointer	String of key values pairs
NULL	No parameters available

The returned string can be something like:

"sides=two-sided-long-edge copies=2 ColorModel=Mono Duplex=DuplexNoTumble"

Todo:

Add info how to deal with these parameters, and what happens with them until the job starts to be processed by the driver

Developer's corner

caps_pp_job_progression_report()

void caps_pp_job_progression_report	(	struct caps_pp_document_desc *	job,
		const struct caps_job_progression *	prog
	)

Report progression while processing the job

Parameters

[in]	job	The job which has made progression (from a caps_pp_job_get() call)
[in]	prog	The progression information

According to caps_job_progression, all members except caps_job_progression::flags must not '0'.

This call also does the required communication with the printing coordinator to spread the information around.

Note

This function does not return if the content of prog is invalid

Attention

The first report is to be sent after the first page/medium was printed! Because you can't report page '0' as printed!

Precondition

All of caps_job_progression::copy, caps_job_progression::cpage, caps_job_progression::dmedia and caps_job_progression::fmedia mention a page number and thus, must not be 0.

Developer's corner

The communication with the printing coordinator:

The full call stack:

caps_pp_job_state_update()

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
	)

Update a job's state

Parameters

[in]	job	The job which has made progression (from a caps_pp_job_get() call)
[in]	state	The job's new state
[in]	reason	The new reason for this state (must be valid!)
[in]	message	An optional message (can be NULL or an empty string, e.g. "")

Return values

-ENODEV	Printer is already gone (should not happen, maybe related to -EPERM)
-EPERM	Calling provider isn't the owner of this printer or print job
-EINVAL	job_id seems invalid or state is invalid

Note

The human readable message contained in message should be in plain english, but you should mark it as a translateable string if it is very special. This function tries to translate this message into the local language first by using the printing provider's NLS domain and then by it's own NLS domain (if it is a common sentence shared by all printing providers for example).

Refer Common Printer State Messages for already defined messages.

This call also does the required communication with the printing coordinator to spread the information around.

Precondition

reason must be one of the available caps_printing_job_reason enums

Postcondition

A call to caps_pp_job_state_update() should be done prior a call to caps_pp_job_done()

Precondition

The application needs to activate NLS via setlocale() to make this translation mechanism work

Developer's corner

The communication with the printing coordinator:

The full call stack: