Printing Provider States

Report printing provider's state. More...

Functions
int	caps_pp_state_update (struct caps_pp_handle *instance, enum caps_printing_provider_state state, enum caps_printing_provider_reason reason, const char *message)

Detailed Description

Talk to the printing coordinator to inform it about the state of a printing device or the printing provider/driver itself

If you have retrieved a new job and "starting the engines":

caps_pp_state_update(instance, LIBCAPS_PP_STATE_PREPARING, LIBCAPS_PP_REASON_NONE, NULL);

If you start to process the print job:

caps_pp_state_update(instance, LIBCAPS_PP_STATE_PROCESSING, LIBCAPS_PP_REASON_NONE, NULL);

If you have finished the last print job:

caps_pp_state_update(instance, LIBCAPS_PP_STATE_IDLE, LIBCAPS_PP_REASON_NONE, NULL);

If you miss media to print on:

caps_pp_state_update(instance, LIBCAPS_PP_STATE_STOPPED, LIBCAPS_PP_REASON_MEDIA_NEEDED, NULL);

Note

In this case no more print jobs will be queued for your printer until you leave this state again.

If your devices detects some media jam:

const char *message = NLS_("Open reverse cover and remove media");
caps_pp_state_update(instance, LIBCAPS_PP_STATE_STOPPED, LIBCAPS_PP_REASON_MEDIA_JAM, message);

Note

This example also reports a possible solution for the user. It shows as well how NLS works, by marking the help text with NLS_(…).

Sometimes the attention of the user is required. The printing provider still works as expected, but announces the need for attention with the LIBCAPS_PP_REASON_ATTENTION reason. Since this reason requires an explaining message, for a user attention both is required.

Example: the printer device is low on ink/toner

This attention can be combined with all other activity unless the reason is used otherwise.

const char *message = NLS_("Low on ink and need some love");
caps_pp_state_update(instance, LIBCAPS_PP_STATE_PREPARING, LIBCAPS_PP_REASON_ATTENTION, message);
caps_pp_state_update(instance, LIBCAPS_PP_STATE_PROCESSING, LIBCAPS_PP_REASON_ATTENTION, message);
caps_pp_state_update(instance, LIBCAPS_PP_STATE_IDLE, LIBCAPS_PP_REASON_ATTENTION, message);

Example: the printer device is out of ink/toner and cannot continue

const char *message = NLS_("Out of ink and need more love");
caps_pp_state_update(instance, LIBCAPS_PP_STATE_STOPPED, LIBCAPS_PP_REASON_ATTENTION, message);

Function Documentation

caps_pp_state_update()

int caps_pp_state_update	(	struct caps_pp_handle *	instance,
		enum caps_printing_provider_state	state,
		enum caps_printing_provider_reason	reason,
		const char *	message
	)

Update the printing provider's/driver's state to inform clients

Parameters

[in]	instance	Provider instance
[in]	state	The printer's new state
[in]	reason	The new reason for this state
[in]	message	An optional message (can be NULL, read precondition below)

Return values

0	on success
-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

This call is a simple 'report' type. It is for information only (e.g. printer is idle for example). Refer Printer State Definitions for state details.

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 already translated messages.

Attention

The new state is limited to one of the active states. Refer Printer State Definitions for ActiveState and TearDownState for details.

Note

If the preconditions aren't met, this function does not return (intentional)

Precondition

state must be valid

If reason is LIBCAPS_PP_REASON_ATTENTION a detailed message must provided

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

Postcondition

This call dispatches a provider change notifier on the DBUS interface.

Developer's corner

The communication with the printing coordinator:

The full call stack:

Note

Counterpart is dbus_SetPrinterState_dispatch()