====== Introduzione alle api di Cups ======
Autore: **//Fabio Di Matteo//** \\ Ultima revisione: **//24/12/2015  - 12:17//** \\ \\

[[http://www.cups.org/index.php|Cups]] il famoso sistema di stampa per Gnu/Linux,  Macosx e altri sistemi Unix possiede delle api che permettono il controllo del server da parte di terze applicazioni che ne fanno uso. In questo esempio vedremo come interagire con lo scheduler per prelevare la lista delle stampanti collegate al sistema e visualizzare la coda di stampa. Scriveremo dunque 2 semplici funzioni in C ''showPrinters()'' e	''myGetJobs()'' . \\ \\
Link utili:
  * [[http://www.cups.org/documentation.php/api-cups.html#cupsGetJobs|]]
  * [[https://github.com/molefrog/cupsidity/blob/master/src/jobs.cc|]] (c++)



===== Avviare/Riavviare Cups =====
Puo' essere utile sapere come avviare o riavviare il server. Sulla mia distribuzione basata su systemd (ArchLinux) basta il seguente comando:
<file>sudo systemctl start org.cups.cupsd.service</file>
Puo'essere anche utile conoscere le utility da riga di comando [[http://www.cups.org/documentation.php/options.html|Command-Line Printing and Options]] oltre che sapere che cups ha una comoda interfaccia web per gestire le stampe [[http://localhost:631|http://localhost:631]]

===== Visualizzare stampanti e coda di stampa =====

**main.c**

<code c>
// Avviare cups su manjaro
//sudo systemctl start org.cups.cupsd.service



#include <stdio.h>
#include <cups/cups.h>


void myGetJobs()
{
	/* Struttura  principale usata:
	struct cups_job_s {
		time_t completed_time;
		time_t creation_time;
		char *dest;
		char *format;
		int id;
		int priority;
		time_t processing_time;
		int size;
		ipp_jstate_t state;
		char *title;
		char *user;
	};
	 * */
	
	
	//Struct che contiene i lavori (uno per ogni struct)
	cups_job_t *jobs ;
	
	//Nome della stampante (NULL per tutte)
	const char *stampante=NULL ;
	
	
	
	/* Funzione (cupsGetJobs) che da info sui lavori in coda, come numero
	 * e stato. Viene creata una  struct (jobs) con le info per ogni
	 * lavoro.La funzioine ritorna il numero di lavori attivi con CUPS_WHICHJOBS_ACTIVE,
	 * totali con CUPS_WHICHJOBS_ALL, completati con CUPS_WHICHJOBS_COMPLETED 
	 * 
	 * Man: http://www.cups.org/documentation.php/api-cups.html#cupsGetJobs
	 * Example: https://github.com/molefrog/cupsidity/blob/master/src/jobs.cc
	 * */
	int njobs= cupsGetJobs (&jobs,stampante,	0,	CUPS_WHICHJOBS_ACTIVE);
	
	//Stampo il numero dei lavori:
	printf("Lavori in coda: %d\n\n", njobs);
	
	
	//Mi serve ques'altra struttura collegata a "jobs" per prelevare il lavoro
	//corrente
	cups_job_t * job = jobs;
	
	int i;
	for (i=0 ; i<njobs; i++, job++)//n.b. incremento anche job
	{
		//Stampo la lista dei lavori
		printf("%d - %s - %s (%s)\n",job->id ,job->title, job->user, job->dest);
	}
}

//Questa funzione mostra le stampanti collegate al sistema
void showPrinters()
{
	int i;
	/* la struct "dests" verra riempita con le info sulle stampanti 
	 * usero' inseguito "dest" per prelevare info su una singola stampante*/
	cups_dest_t *dests, *dest;
	
	
	/*
	 * 
			typedef struct				
			{
			  char		*name,			 Printer or class name 
			  char *instance,		 Local instance name or NULL 
			  int		is_default;		 Is this printer the default? 
			  int		num_options;		 Number of options 
			  cups_option_t	*options;		 Options 
			} cups_dest_t;
	 * 
	 * */
	
	
	
	
	/*cupsGetDests oltre che ritornare il numero delle stampanti riempe
	 * la struttura dests con i dettagli di ogni stampante
	 * */
	int num_dests = cupsGetDests(&dests);

	for (i = num_dests, dest = dests; i > 0; i --, dest ++)//incremento anche dest
	{
	if (dest->instance)
	  printf("%s/%s\n", dest->name, dest->instance);
	else
	  puts(dest->name);
	}

}



int main(void)
{
		showPrinters();
		myGetJobs();
		
  return (0);
}


</code>

**makefile**
<file>
CPP = gcc
OPTS = `cups-config --cflags --libs`

all:
	$(CPP)  main.c -o main $(OPTS)

clean:
	rm main

</file>

===== Cancellare lavori di stampa (jobs) =====

Se si vogliono cancella i lavori di stampa di una certa stampante si puo' invece riccorere a queste 2 funzioni:
<code c>

int cancelJob(const char* destName, int jobId)
{
	//Doc: http://www.cups.org/documentation.php/api-cups.html#cupsCancelJob 
	int success = cupsCancelJob( destName, jobId );
	return success;
}

void cancelAllJobs(const char* destName)
{
	/*int success = cupsCancelJob( destName, CUPS_JOBID_ALL);
	return success;*/
	
	
	//Struct che contiene i lavori (uno per ogni struct)
	cups_job_t *jobs ;
	
	//Nome della stampante (NULL per tutte)
	const char *stampante=destName ;
	
	
	//Vedere myGetJobs()
	int njobs= cupsGetJobs (&jobs,stampante,	0,	CUPS_WHICHJOBS_ACTIVE);
	
	//Mi serve ques'altra struttura collegata a "jobs" per prelevare il lavoro
	//corrente
	cups_job_t * job = jobs;
	
	int i, success;
	for (i=0 ; i<njobs; i++, job++)//n.b. incremento anche job
	{
		//Stampo la lista dei lavori
		//printf("%d - %s - %s (%s)\n",job->id ,job->title, job->user, job->dest);
		success = cupsCancelJob( destName, job->id );
	}
}
</code>