Print documents

Commit documents to print and monitor their print progression. More...

Data Structures
struct	caps_cl_job_state

Functions
int	caps_cl_job_commit (struct caps_cl_handle *instance, caps_identifier printer_id, int job_fd, const char *parameter, caps_identifier *job_id)
int	caps_cl_job_state_get (struct caps_cl_handle *instance, caps_identifier job_id, struct caps_cl_job_state *state)
bool	caps_cl_job_check_if_done (struct caps_cl_handle *instance, const struct caps_cl_job_state *state)
int	caps_cl_job_progression_get (struct caps_cl_handle *instance, caps_identifier job_id, struct caps_job_progression *prog)
int	caps_cl_job_cancel (struct caps_cl_handle *instance, caps_identifier job_id)

Detailed Description

In order to print the content of a document file just run:

struct caps_cl_handle *instance;
caps_identifier pr_id, job_id;
const char *printer_device = "My Printer";
const char *params = "copies=2";
int fd;
 
 instance = caps_cl_instance_create();
 caps_cl_instance_register(instance, NULL, NULL);
 caps_cl_printer_name_to_id(instance, printer_device, &pr_id);
 
 fd = open(doc, O_RDONLY);
 caps_cl_job_commit(instance, pr_id, fd, params, &job_id);
 close(fd);
 
 printf("Job committed with ID %jd\n"), (intmax_t)job_id);
 caps_cl_instance_unregister(instance);
 caps_cl_instance_destroy(instance);

Note

You always provide an open file descriptor to the document file to print. After caps_cl_job_commit() has forwarded it to the Printing Coordinator you can close your file descriptor. The Printing Coordinator still has an open copy.

Self Removing Files

To avoid print files fill up the filesystem you can use self removing files instead. caps_helper_invisible_file_create() from libcapsbase creates such a file. You can fill the document content into it and commit this file descriptor to the Printing Coordinator. You can close the file descriptor afterwards as usual. The file still retains, since the Printing Coordinator maintains an open copy of your file descriptor. After the print is done, the Printing Coordinator closes this file descriptor copy as well - and the file gets removed automatically.

[…]
int fd;
 
 instance = caps_cl_instance_create();
 caps_cl_instance_register(instance, NULL, NULL);
 caps_cl_printer_name_to_id(instance, printer_device, &pr_id);
 
 caps_helper_invisible_file_create(&fd);
   […]<fill the file with the documents data>[…]
 caps_cl_job_commit(instance, pr_id, fd, params, &job_id);
 close(fd);
 
 printf("Job committed with ID %jd\n"), (intmax_t)job_id);
 caps_cl_instance_unregister(instance);
 caps_cl_instance_destroy(instance);

You must have write permissions in the CAPS Document Storage Directory in order to make it work in such a way. Usually this is the case if you are a member in the lp group.

Function Documentation

caps_cl_job_commit()

int caps_cl_job_commit	(	struct caps_cl_handle *	instance,
		caps_identifier	printer_id,
		int	job_fd,
		const char *	parameter,
		caps_identifier *	job_id
	)

Commit a job to the Printing Coordinator

Parameters

[in]	instance	Client instance
[in]	printer_id	The printing provider's identifier the job is for
[in]	job_fd	File descriptor to the job content (e.g. the document to print)
[in]	parameter	Printing parameter (can be NULL)
[out]	job_id	Where to store the corresponding job ID

Return values

0	On success (*job_id is valid)
-ENODEV	printer_id refers to a non existing printer (*job_id is invalid)
-EPERM	Printer does not accept new print jobs (e.g. it is going offline)
-EIO	Real communication error with the Printing Coordinator (should not happen, *job_id is invalid)
-EINVAL	Bad/unexpected reply from the Printing Coordinator (should not happen, *job_id is invalid)

The parameter is meant as "printing parameter". Mostly key/value pairs derived from the possible options of the corresponding PPD file and/or from the IPP specification. Delimiter is the space character.

Refer RFC2911, 3.2.1 Print Job Operation, RFC2911, 4.2.x Job Template Attributes or the list of Supported Printing Parameter for details.

An example: Print 10 copies of all pages from 1 to 10 and 15:

 copies=10 page-ranges=1-10,15

Note

-ENODEV and -EPERM are regular use cases, no real error. Printers can fade away at any point of time. Be prepared for this

Precondition

A registered client instance

printer_id must be valid (e.g. a positive value, not CAPS_INVALID_IDENTIFIER for example)

job_fd must be valid file descriptor, already opened for reading

Postcondition

-EIO and -EINVAL create a readable error message (refer caps_cl_error_messages_catch())

Developer's corner

The communication with the printing coordinator:

The full call stack:

Note

Counterpart is dbus_commit_printing_job()

caps_cl_job_state_get()

int caps_cl_job_state_get	(	struct caps_cl_handle *	instance,
		caps_identifier	job_id,
		struct caps_cl_job_state *	state
	)

Get the state of a specific print job

Parameters

[in]	instance	Client instance
[in]	job_id	The print job's identifier
[out]	state	Where to store the print job's state

Return values

0	On success (*state is valid)
-ENOENT	Job is already gone (*state is invalid)
-EINVAL	Bad/unexpected reply from the Printing Coordinator (should not happen, *state is invalid)
-EIO	Real communication error with the Printing Coordinator (should not happen, *state is invalid)

The Printing Coordinator forgets print jobs which are already done. Always expect a limited lifetime of jobs and handle it accordingly.

From the client point of view, a print job can be in one of the following visible states:

• LIBCAPS_PJ_STATE_QUEUED
• LIBCAPS_PJ_STATE_PREPARED
• LIBCAPS_PJ_STATE_PROCESSING
• LIBCAPS_PJ_STATE_PROCESSING_STOPPED

Or in one of the final states:

• LIBCAPS_PJ_STATE_CANCELED
• LIBCAPS_PJ_STATE_ABORTED
• LIBCAPS_PJ_STATE_COMPLETED

Note

Instead of polling the job's state, you can use notifiers.

-EINVAL for an invalid job ID is a regular use case, no real error. All jobs get removed if they are done

You can always assume a -EINVAL return value names a job ID issue. The "bad/unexpected reply" case should never happen

Precondition

A registered client instance

job_id must be valid (e.g. a positive value, not CAPS_INVALID_IDENTIFIER for example)

Postcondition

-EIO and -EINVAL create a readable error message (refer caps_cl_error_messages_catch())

Developer's corner

The communication with the printing coordinator.

The full call stack:

Note

Counterpart is dbus_get_printing_job_state()

The API documentation relies on the correct behaviour of pc_provider_job_drain(), pc_provider_job_finished() and pc_client_job_cancel() regarding already finished jobs. caps_cl_job_check_if_done() relies on it as well.

caps_cl_job_check_if_done()

bool caps_cl_job_check_if_done	(	struct caps_cl_handle *	instance,
		const struct caps_cl_job_state *	state
	)

Check if a given job state means the job is already done

Parameters

[in]	instance	Client instance
[in]	state	Job's state to check (from the caps_cl_job_get_state() call)

Return values

true	If the job is already done
false	If the job isn't done, yet

Note

This function doesn't honor why it is done (error or success).

This is a convenience function, refer caps_cl_job_state_get() for details

Precondition

A registered client instance

Developer's corner

This function relies on the correct behaviour of pc_provider_job_drain(), pc_provider_job_finished() and pc_client_job_cancel() regarding already finished jobs.

caps_cl_job_progression_get()

int caps_cl_job_progression_get	(	struct caps_cl_handle *	instance,
		caps_identifier	job_id,
		struct caps_job_progression *	prog
	)

Retrieve the printing progression info for a print job

Parameters

[in]	instance	Client instance
[in]	job_id	The print job's identifier
[out]	prog	Where to store the progression info

Return values

0	On success, *prog is valid
-ENOENT	Job is already gone (maybe its printer as well, *prog is invalid)
-EINVAL	Bad/unexpected reply from the Printing Coordinator (should not happen, *prog is invalid)
-EAGAIN	No progression yet (*prog is invalid)
-EIO	Real communication error with the Printing Coordinator (should not happen, *prog is invalid)

Refer caps_job_progression for details about the information you will get.

Note

Instead of polling the job's progression, you can use notifiers.

-ENOENT for an invalid job ID is a regular use case, no real error. All jobs gets removed if they are done

-EAGAIN is a regular use case, no real error. Simply try again later

Precondition

A registered client instance

job_id must be valid (e.g. a positive value, not CAPS_INVALID_IDENTIFIER for example)

Postcondition

-EIO and -EINVAL create a readable error message (refer caps_cl_error_messages_catch())

Developer's corner

The communication with the printing coordinator.

The full call stack:

Note

Counterpart is dbus_printing_job_progression_get()

caps_cl_job_cancel()

int caps_cl_job_cancel	(	struct caps_cl_handle *	instance,
		caps_identifier	job_id
	)

Cancel an already committed print job

Parameters

[in]	instance	Client instance
[in]	job_id	The print job's identifier to cancel

Return values

0	On success (as well, if the job is already done and removed from the queue)
-EIO	Real communication error with the Printing Coordinator (should not happen)
-EINVAL	Bad/unexpected reply from the Printing Coordinator (should not happen)

If the print job is still in the printing queue (at the Printing Coordinator level) it will just be removed from the queue. If the job is already being processed (at the printing provider level) the printing provider gets notified and it might terminate the processing if possible. The print job then might disappear from the queue.

Note

This function will not fail if the print job does not exist anymore.

Precondition

A registered client instance

job_id must be valid (e.g. a positive value, not CAPS_INVALID_IDENTIFIER for example)

Postcondition

-EIO and -EINVAL create a readable error message (refer caps_cl_error_messages_catch())

Developer's corner

The communication with the printing coordinator.

The full call stack:

Note

Counterpart is dbus_cancel_printing_job()