The Printing Coordinator calls back. More...

Data Structures
struct	caps_cl_notifier
	Define notifier callbacks for Printing Coordinator clients. More...

Macros
#define	CAPS_NOTIFIER_HANDLED 0

#define	CAPS_NOTIFIER_NOT_YET_HANDLED 1

Functions
int	caps_cl_notifiers_process (struct caps_cl_handle *instance)

int	caps_cl_connection_fd_get (struct caps_cl_handle *instance)

Detailed Description

Notifier API.

Sometimes you are interested in state changes of printers and/or print jobs. Instead of polling their state all the time, you can be called back via a notfier instead.

Printer related state change notifications can be:

a new printer is available
a printer is gone (e.g. gone offline)
a printer entered an error state (out of paper for example)
a printer left an error state (it is ready to print)

Job related state change notifications can be:

print progression
print job done

For this, you can register notifiers:

one for printer state changes
one for print job state changes

Using the notifiers looks like the example in Be part of the whole thing, only the Do all the hard work block differs:

The corresponding code example looks like in Be part of the whole thing. It is extended by the notifier functions and the structure caps_cl_notifier to register it. And the periodical call to caps_cl_notifiers_process() is added as well.

static int printer_notifier(void *data, caps_identifier pr_id,
                            struct caps_cl_printer_state *pstate)
{
  struct my_private_data *priv_data;
  priv_data = (struct my_private_data *)data;
 
  // […]do something[…]
}
 
static int job_notifier(void *data, caps_identifier job_id,
                        struct caps_cl_job_state *jstate,
                        struct caps_job_progression *progression)
{
  struct my_private_data *priv_data;
  priv_data = (struct my_private_data *)data;
 
  // […]do something different[…]
}
 
[…]
 
main()
{
 struct caps_cl_handle *instance;
 struct caps_cl_notifier notifier = {
   .provider_change = printer_notifier,
   .job_change = job_notifier,
 };
 struct my_private_data priv_data;
 
 instance = caps_cl_instance_create();
 caps_cl_instance_register(instance, &notifier, &priv_data);
 
 do {
  // […]do some work here[…]
  caps_cl_notifiers_process(instance);
 while (!done);
 
 caps_cl_instance_unregister(instance);
 caps_cl_instance_destroy(instance);
}

Example for a printer notifier:

static int printer_notifier(void *data, caps_identifier pr_id,
                            struct caps_cl_printer_state *pstate)
{
  struct my_private_data *priv_data = (struct my_private_data *)data;
  struct caps_cl_printer_info *info;
  int rc;
 
  // Check, if the printer is new to you. If yes:
  {
    rc = caps_cl_printer_info_get(priv_data->instance, pr_id, &info);
    if (rc < 0) {
       if (rc == -ENODEV) {
          // […]report somehow the printer is gone[…]
       }
       // deal with other errors
       return CAPS_NOTIFIER_HANDLED;
    }
    // […]report somehow the new printer in *info[…]
    caps_cl_printer_info_destroy(info);
  }
  if (pstate != NULL)
    // […]report somehow the printer's new state in *pstate[…]
 
  return CAPS_NOTIFIER_HANDLED;
}

Example for a print job notifier:

static int print_job_notifier(void *data, caps_identifier job_id,
                              struct caps_cl_job_state *jstate,
                              struct caps_job_progression *jprogression)
{
  struct my_private_data *priv_data = (struct my_private_data *)data;
  struct caps_job_progression progression;
  struct caps_cl_job_state state;
  int rc;
 
  if (jstate != NULL) {
     // The job has a new state
     // […]report somehow the job's new state[…]
  }
  if (jprogression != NULL) {
    // The job made some progression
    // […]report its progression somehow […]
  }
 
  return CAPS_NOTIFIER_HANDLED;
}

Macro Definition Documentation

◆ CAPS_NOTIFIER_HANDLED

#define CAPS_NOTIFIER_HANDLED 0

Used by the notifier callback as a return value: the incoming notifier is finally processed

Precondition: Value must correspond to DBUS_HANDLER_RESULT_HANDLED

◆ CAPS_NOTIFIER_NOT_YET_HANDLED

#define CAPS_NOTIFIER_NOT_YET_HANDLED 1

Used by the notifier callback as a return value: the incoming notifier isn't finally processed

Precondition: Value must correspond to DBUS_HANDLER_RESULT_NOT_YET_HANDLED

Function Documentation

◆ caps_cl_notifiers_process()

int caps_cl_notifiers_process ( struct caps_cl_handle * instance )

Process CAPS printer and job related notifiers

Parameters

[in] instance Client instance

Return values

0	On success
-EIO	If the connection to the printing coordinator was (unexpectedly) closed

Processing a notifier means dispatching the received information to the registered notifier callback functions.

If notifiers are ready to process, this function processes them and returns immediately. If no notifier is present when called (e.g. queue is empty, nothing to be done), it waits for a notifier to arrive until a timeout of one second and then returns.

In a main loop you can call this function, whenever the filedescriptor of the underlying connection signals data is present (refer caps_cl_connection_fd_get()).

Note: Processes as much notifiers as present, e.g. returns only if the queue is empty.; Call it periodically to process CAPS notifiers if you don't run a main loop. Else call it only, if the filedescriptor signals data is present.

Precondition: A registered client instance; Defined notifier callbacks (caps_cl_notifier) when calling caps_cl_instance_register()

Developer's corner

◆ caps_cl_connection_fd_get()

int caps_cl_connection_fd_get ( struct caps_cl_handle * instance )

Retrieve the underlying communication filedescriptor for main loop inclusion