Get the information about the document and how the user wants to print it. More...

Data Structures
struct	caps_drv_page_limits
	The static rasterizer limits. More...

Functions
struct caps_drv_page_limits	caps_drv_job_limits_get (struct caps_drv *cdrv)

const char *	caps_drv_job_value_get (struct caps_drv cdrv, const char designator, const char *name)

const char *	caps_drv_job_choice_get (struct caps_drv cdrv, const char designator)

int	caps_drv_job_is_duplex (struct caps_drv *cdrv)

const char *	caps_drv_print_medium_format_name_get (struct caps_drv *cdrv)

struct caps_rect	caps_drv_print_medium_size_get (struct caps_drv *cdrv)

struct caps_area	caps_drv_print_medium_margins_get (struct caps_drv *cdrv)

enum caps_ppd_paper_leading_edges	caps_drv_print_medium_orientation_get (struct caps_drv *cdrv)

struct caps_area	caps_drv_print_medium_imageable_get (struct caps_drv *cdrv)

struct caps_ppd_resolution	caps_drv_print_resolution_get (struct caps_drv *cdrv)

enum caps_colour_format	caps_drv_print_colour_get (struct caps_drv *cdrv)

Detailed Description

All these functions hide the details of libcapsraster behind. You can call them in the caps_generic_driver::job_start() callback.

Function Documentation

◆ caps_drv_job_limits_get()

struct caps_drv_page_limits caps_drv_job_limits_get ( struct caps_drv * cdrv )

Get the rasterizer dependent (static) limits for the attached document

Parameters

[in] cdrv libcapsdriver handle

Returns: The Limits for the current document and its rasterizer

After attaching a job to a rastrizer it can report about limitiations it might have for this kind of document format.
For example a CUPS raster as an input document is limited to exactly one colour format: the one provided in the CUPS raster. Maybe your driver can deal with it - maybe not. This function can help you to see, if printing will be possible. If not, you should reject the job.

Precondition: Can be called within the caps_generic_driver::job_start() callback.

◆ caps_drv_job_value_get()

const char * caps_drv_job_value_get	(	struct caps_drv *	cdrv,
		const char *	designator,
		const char *	name
	)

Retrieve job related specific PPD value with a special designator (and maybe name)

Parameters

[in]	cdrv	libcapsdriver handle
[in]	designator	Designator to retrieve the value from
[in]	name	Name of the parameter (can be NULL)

Return values

Pointer	Pointer to the parameter's value
NULL	If the keyword does not exist

Refer caps_rstr_job_value_get() how to use this function.

Precondition: Can be called within the caps_generic_driver::job_start() callback.

Postcondition: The returned string is valid as long as the attached job is valid.

◆ caps_drv_job_choice_get()

const char * caps_drv_job_choice_get	(	struct caps_drv *	cdrv,
		const char *	designator
	)

Retrieve job related user selections from the PPD

Parameters

[in]	cdrv	libcapsdriver handle
[in]	designator	Designator to retrieve the choice from

Return values

Pointer	Pointer to the value string of the selection
NULL	If the designator doesn't exist

Refer caps_rstr_job_choice_get() how to use this function.

Note: Use this function only for your own selection extensions (defined via caps_ppd_base::selections and caps_ppd_selection ). Don't use it for the generic selections like PaperSize for example.
For the generic selections, dedicated functions do exist instead (like caps_drv_print_medium_format_name_get() or caps_drv_print_resolution_get() and so on).

Precondition: Can be called within the caps_generic_driver::job_start() callback.

Postcondition: The returned string is valid as long as the attached job is valid.

◆ caps_drv_job_is_duplex()

int caps_drv_job_is_duplex ( struct caps_drv * cdrv )

Check, if this job is intended to be printed in duplex mode

Parameters

[in] cdrv libcapsdriver handle

Return values

1	(true) This job is a duplex one
0	(false) This job is a simplex one

Note: It is just a wrapper around caps_rstr_job_is_duplex()

Precondition: Can be called within the caps_generic_driver::job_start() callback.

◆ caps_drv_print_medium_format_name_get()

const char * caps_drv_print_medium_format_name_get ( struct caps_drv * cdrv )

Retrieve the user's selection of the print medium as a format name

Parameters

[in] cdrv libcapsdriver handle

Returns: Name of the medium's format (like a4 or letter or a printer specific one)

This is the medium format name the user has selected to print to. Since it is derived from the settings the printer driver has provided in its caps_ppd_base feature structure, it just contains this data.

Precondition: Can be called within the caps_generic_driver::page_setup() callback.

Postcondition: The string is valid as long as the attached job is valid.

◆ caps_drv_print_medium_size_get()

struct caps_rect caps_drv_print_medium_size_get ( struct caps_drv * cdrv )

Retrieve the user's selection of the medium as a size in [pts]

Parameters

[in] cdrv libcapsdriver handle

Returns: Size of the medium's format in [pts] (like .width = 595.27584 x .length = 841.8888 pts for A4)

This is the medium size the user has selected to print to. Since it is derived from the settings the printer driver has provided in its caps_ppd_base feature structure, it just contains this data (which has impact to its size and orientation).

Note: The image above suggests portrait orientation, but the returned size information isn't restricted to this orientation. It is up to the driver's caps_ppd_base content.

It works for all kind of media definition, including the custom formats (if the driver makes use of it).

The returned size can be used in caps_drv_print_medium_size_set() to setup the raster size which should cover the full medium.

Attention: Consider this returned size has an orientation which might differ from the selected orientation (refer caps_drv_print_medium_orientation_get()). You may need to align the size to the selected orientation prior storing it in caps_rstr_page::medium_sz or using the caps_drv_print_medium_size_set() function.

Precondition: Can be called within the caps_generic_driver::job_start() callback.

◆ caps_drv_print_medium_margins_get()

struct caps_area caps_drv_print_medium_margins_get ( struct caps_drv * cdrv )

Get the margins of the user's selection of the print medium

Parameters

[in] cdrv libcapsdriver handle

Returns: The medium' margins in [pts]

The returned margins are four individial values, e.g. not coordinates! This is a misuse of struct caps_area!

The meaning of the four values

It can be used in caps_drv_print_medium_margins_set() to setup the rasters margins.

Note: The mentioned top margin is always the top (or the margin at the leading edge of the print medium). These margins never have an orientation, they describe hard limits of the printer device.

Precondition: Can be called within the caps_generic_driver::job_start() callback.

◆ caps_drv_print_medium_orientation_get()

enum caps_ppd_paper_leading_edges caps_drv_print_medium_orientation_get ( struct caps_drv * cdrv )

Get the user's selection of the print medium orientation

Parameters

[in] cdrv libcapsdriver handle

Returns: The orientation information

Only one of the values:

is valid. It is to be used in conjunction with the caps_drv_print_medium_size_get() returned size of the print medium.

Left: LIBCAPS_PLE_SHORT Right: LIBCAPS_PLE_LONG

Precondition: Can be called within the caps_generic_driver::job_start() callback.

◆ caps_drv_print_medium_imageable_get()

struct caps_area caps_drv_print_medium_imageable_get ( struct caps_drv * cdrv )

Get the imageable area of the user's selection of the print medium

Parameters

[in] cdrv libcapsdriver handle

Returns: The imageable area information in [pts]

This function returns the combination of the print medium size with the four margins applied and forms an area.

Meaning of the imageable area

Note: The area here refers the print medium size from the caps_drv_print_medium_size_get(). And thus, might missing the selected orientation!
The returned information suffers from the almost static PPD data.

Attention: Don't use if the orientation of caps_drv_print_medium_size_get() and caps_drv_print_medium_orientation_get() differs. Use caps_drv_print_medium_margins_get() and do the calculation by your own instead.

Precondition: Can be called within the caps_generic_driver::job_start() callback.

◆ caps_drv_print_resolution_get()

struct caps_ppd_resolution caps_drv_print_resolution_get ( struct caps_drv * cdrv )

Retrieve the user's selection of the print resolution

Parameters

[in] cdrv libcapsdriver handle

Returns: The selected resolution

The caps_ppd_resolution::horizontal refers always the cross medium feed direction.

Precondition: Can be called within the caps_generic_driver::job_start() callback.

◆ caps_drv_print_colour_get()

enum caps_colour_format caps_drv_print_colour_get ( struct caps_drv * cdrv )

Retrieve the user's selection of the colour mode

Parameters

[in] cdrv libcapsdriver handle

Return values

Selected colour mode for this print job

Precondition: Can be called within the caps_generic_driver::job_start() callback.

Data Structures

Functions

Detailed Description

Function Documentation

◆ caps_drv_job_limits_get()

◆ caps_drv_job_value_get()

◆ caps_drv_job_choice_get()

◆ caps_drv_job_is_duplex()

◆ caps_drv_print_medium_format_name_get()

◆ caps_drv_print_medium_size_get()

◆ caps_drv_print_medium_margins_get()

◆ caps_drv_print_medium_orientation_get()

◆ caps_drv_print_medium_imageable_get()

◆ caps_drv_print_resolution_get()

◆ caps_drv_print_colour_get()