Google Cloud Print non è più supportato a partire dal 31 dicembre 2020. Consulta l'articolo di assistenza per ricevere supporto per la migrazione.

Questa pagina è stata tradotta dall'API Cloud Translation.

Privet

Privet è un'API Cloud Device Local Discovery utilizzata dai servizi cloud. Questo documento è organizzato nelle seguenti sezioni:

Introduzione: introduzione a Privet
Rilevamento: meccanismi di rilevamento locali
Annunci: annunci di scoperta locale
API: API privata per dispositivi cloud generici
API Stampante: API privata utilizzate dalle stampanti
Appendice: diagrammi supplementari

1. Introduzione

I dispositivi cloud connessi hanno molti vantaggi. Possono utilizzare i servizi di conversione online, ospitare code di job mentre il dispositivo è offline e essere accessibile ovunque nel mondo. Tuttavia, con molti dispositivi cloud accessibili da un determinato utente, dobbiamo fornire un metodo per trovare il dispositivo più vicino in base alla posizione. Lo scopo del protocollo Privet è vincolare la flessibilità dei dispositivi cloud con un meccanismo di rilevamento locale adatto, affinché i dispositivi possano essere scoperti facilmente in nuovi ambienti.

Gli obiettivi di questo protocollo sono:

rendere i dispositivi cloud rilevabili localmente
Registrare dispositivi cloud con un servizio cloud
associare i dispositivi registrati alla rappresentazione cloud
abilita funzionalità offline
Semplifica l'implementazione in modo che possa essere utilizzata dai piccoli dispositivi

Il protocollo Privet è costituito da due parti principali: rilevamento e API. Il rilevamento viene utilizzato per trovare il dispositivo sulla rete locale e l'API viene utilizzata per ottenere informazioni sul dispositivo ed eseguire alcune azioni. Nel corso di questo documento, il dispositivo fa riferimento a un dispositivo connesso al cloud che implementa il protocollo Privet.

2. Discovery

Discovery è un protocollo basato su zeroconf (mDNS + DNS-SD). Il dispositivo DEVE implementare gli indirizzi IPv4 Link-Local. Il dispositivo DEVE rispettare le specifiche mDNS e DNS-SD.

http://www.rfc-editor.org/rfc/rfc3927.txt (IPv4 Link locale)
http://www.rfc-editor.org/rfc/rfc4862.txt (IPv6 Link locale)
http://www.rfc-editor.org/rfc/rfc6762.txt (mDNS)
http://www.rfc-editor.org/rfc/rfc6763.txt (DNS-SD)

Il dispositivo DEVE eseguire la risoluzione dei conflitti di nomi in base alle specifiche riportate sopra.

2.1. Tipo di servizio

DNS Service Discovery utilizza il seguente formato per i tipi di servizi: _applicationprotocol._transportprotocol. Nel caso del protocollo Privet, il tipo di servizio per DNS-SD dovrebbe essere: _privet._tcp

Il dispositivo può anche implementare altri tipi di servizi. Consigliamo di utilizzare lo stesso nome di istanza di servizio per tutti i tipi di servizi implementati dal dispositivo. Ad esempio, una stampante potrebbe implementare la stampante "Stampante XYZ._privet._tcp&quot" e la "Stampante XYZ._printer._tcp" servizi. Semplifica la configurazione per l'utente. Tuttavia, i client Privet cercherà solo "_privet._tcp".

Oltre al tipo di servizio principale, il dispositivo DEVE pubblicizzare i record PTR per i relativi sottotipi corrispondenti (vedi le specifiche DNS-SD: "7.1. Enumerazione selettiva delle istanze (sottotipi)". Il formato deve essere il seguente: _<subtype>._sub._privet._tcp

Attualmente l'unico sottotipo di dispositivo supportato è stampante. Quindi, tutte le stampanti DEVONO pubblicizzare due record PTR:

_privet._tcp.local.
_printer._sub._privet._tcp.local.

2.2. Record TXT

DNS Service Discovery definisce i campi per aggiungere informazioni facoltative su un servizio nei record TXT. Un record TXT è costituito da coppie chiave/valore. Ogni coppia chiave/valore inizia dal byte di lunghezza seguito da un massimo di 255 byte di testo. La chiave è il testo che precede il primo carattere "=" e il valore corrisponde al testo che segue il primo carattere "=" fino alla fine. La specifica non consente alcun valore nel record, in tal caso non ci sarà il carattere '=' O non verrà inserito testo dopo il carattere '='. (Vedi le specifiche DNS-SD: ""6.1. Regole di formato generali per i record TXT DNS" per il formato dei record TXT DNS e "6.2. Record TXT TXT DNS-SD" (per la lunghezza consigliata).

Privet richiede che il dispositivo invii le seguenti coppie chiave/valore nel record TXT. Le stringhe di chiave/valore non fanno distinzione tra maiuscole e minuscole, ad esempio "CS=online" e &cs=online sono uguali. Le informazioni nel record TXT DEVONO essere le stesse accessibili tramite l'API /info (vedi 4.1. .

Consigliamo di mantenere i record TXT sotto i 512 byte.

2.2.1. txtvers

Versione della struttura TXT. txtver DEVE essere il primo record della struttura TXT. Attualmente l'unica versione supportata è 1.

txtvers=1

2.2.2. ty

Fornisce un nome leggibile del dispositivo. Ad esempio:

ty=Google Cloud Ready Printer Model XYZ

2.2.3. nota (facoltativa)

Fornisce un nome leggibile del dispositivo. Ad esempio:

note=1st floor lobby printer

Nota: questa è una chiave facoltativa e può essere ignorata. Tuttavia, se presente, l'utente DEVE essere in grado di modificare questo valore. La stessa descrizione DEVE essere utilizzata quando si registra il dispositivo.

2.2.4. URL

URL del server a cui è connesso questo dispositivo (incluso il protocollo). Ad esempio:

url=https://www.google.com/cloudprint

2.2.5. tipo

Elenco di sottotipi separati da virgole supportati da questo dispositivo. Il formato è: "type=_subtype1,_subtype2". Attualmente, l'unico sottotipo di dispositivo supportato è stampante.

type=printer

Ogni sottotipo elencato deve essere pubblicizzato utilizzando un record PTR corrispondente. Per ogni sottotipo di servizio supportato deve essere presente una voce corrispondente. Il nome del sottotipo di servizio (<subtype>._sub._privet._tcp) deve essere uguale al tipo di dispositivo qui.

2.2.6. ID

ID dispositivo. Se il dispositivo non è stato ancora registrato, dovrebbe essere presente questa chiave, ma il valore deve essere vuoto. Ad esempio:

  id=11111111-2222-3333-4444-555555555555
  id=

2.2.7. cs

Indica lo stato attuale della connessione del dispositivo. In questa specifica vengono definiti quattro possibili valori.

"online" indica che il dispositivo è attualmente connesso al cloud.
"offline" indica che il dispositivo è disponibile sulla rete locale, ma non può comunicare con il server.
"connessione" indica che il dispositivo sta eseguendo la sequenza di avvio e non è ancora completamente online.
"not-configured" indica che l'accesso a Internet del dispositivo non è stato ancora configurato. Questo valore non è attualmente utilizzato, ma potrebbe essere utile nelle versioni future della specifica.

Ad esempio:

cs=online
cs=offline
cs=connessione

Se il dispositivo è stato registrato con un cloud, all'avvio deve controllare la connettività con un server per rilevare il suo stato di connessione (ad esempio, chiamando l'API Cloud per recuperare le impostazioni del dispositivo). Il dispositivo potrebbe usare lo stato della connessione del canale di notifica (ad es. XMPP) per segnalare il valore. I dispositivi non registrati all'avvio potrebbero inviare un ping a un dominio per rilevare il loro stato di connessione (ad esempio, ping su www.google.com per i dispositivi Cloud Print).

3. Annunci

All'avvio, all'arresto o alla modifica dello stato, il dispositivo DEVE eseguire il passaggio di annuncio, come descritto nella specifica mDNS. DEVE inviare l'annuncio corrispondente almeno due volte dopo un intervallo di almeno un secondo.

3.1. Avvio

All'avvio del dispositivo DEVE eseguire probing e annunci dei passaggi come descritto nella specifica mDNS. In questo caso, devono essere inviati record SRV, PTR e TXT. Se possibile, ti consigliamo di raggruppare tutti i record in una risposta DNS. In caso contrario, il seguente ordine è consigliato: record SRV, PTR, TXT.

3.2. Arresto

All'arresto del dispositivo, DOVREBBE cercare di comunicarlo a tutte le parti interessate inviando un "pacchetto di addio" con TTL=0 (come descritto nella documentazione mDNS).

3.3 Update

Se le informazioni descritte in TXT sono cambiate, il dispositivo DEVE inviare un annuncio di aggiornamento. In questo caso è sufficiente inviare solo il nuovo record TXT. Ad esempio, dopo la registrazione, il dispositivo DEVE inviare un annuncio di aggiornamento che includa il nuovo ID dispositivo.

4. API

Dopo aver rilevato un dispositivo cloud, la comunicazione client viene abilitata con il dispositivo direttamente sulla rete locale. Tutte le API sono basate su HTTP 1.1. I formati dei dati sono basati su JSON. Le richieste API possono essere richieste GET o POST.

Ogni richiesta DEVE contenere un'intestazione "X-Privet-Token" valida. L'unica richiesta consentita è avere un'intestazione "X-Privet-Token" vuota è la richiesta /privet/info (nota che l'intestazione DEVE essere ancora presente). Se manca l'intestazione "X-Privet-Token" perché il dispositivo DEVE rispondere con il seguente errore HTTP 400:

HTTP/1.1 400 Missing X-Privet-Token header.

Se l'intestazione "X-Privet-Token" è vuota o non valida, il dispositivo DEVE rispondere con un "Errore X-Privet-Token non valido" (invalid_x_privet_token; consulta la sezione Errori per i dettagli). L'unica eccezione è l'API /info. Per ulteriori informazioni sul motivo della rimozione e su come dovrebbero essere generati i token, consulta l'Appendice A: attacchi e prevenzione XSSI e XSRF.

Se un'API richiesta non esiste o non è supportata, il dispositivo DEVE restituire un errore HTTP 404.

4.1. Disponibilità dell'API

Prima di esporre QUALSIASI API (inclusa l'API /info), il dispositivo DEVE contattare il server per verificare le impostazioni locali. Le impostazioni locali DEVONO essere conservate tra i riavvii. Se il server non è disponibile, è necessario utilizzare le ultime impostazioni locali note. Se il dispositivo non è ancora stato registrato, deve rispettare le impostazioni predefinite.

I dispositivi Cloud Print DEVONO seguire i passaggi riportati di seguito per registrare, ricevere e aggiornare le impostazioni locali.

4.1.1. Registrazione

Quando il dispositivo si registra, DEVE specificare il parametro "local_settings" come segue:

{
       "current": {
                "local_discovery": true,
                "access_token_enabled": true,
                "printer/local_printing_enabled": true,
                "printer/conversion_printing_enabled": true,
                "xmpp_timeout_value": 300
        }
}

È possibile configurare le seguenti impostazioni:

Nome valore	Tipo di valore	Descrizione
local_discovery	boolean	Indica se la funzionalità di rilevamento locale è consentita. Se "false", tutte le API locali (incluso /info) e il rilevamento DNS-SD devono essere disabilitate. Per impostazione predefinita, i dispositivi di nuova registrazione devono superare "true".
access_token_enabled	Booleano (facoltativo)	Indica se l'API /accesstoken deve essere esposta sulla rete locale. Per impostazione predefinita, deve essere "true".
stampante/local_printing_enabled	Booleano (facoltativo)	Indica se la funzionalità di stampa locale (/printer/createjob, /printer/submitdoc, /printer/jobstate) deve essere esposta sulla rete locale. Per impostazione predefinita, deve essere "true".
stampante/stampa_conversioni_attivata	Booleano (facoltativo)	Indica se la stampa locale può inviare un job al server per la conversione. Ha senso solo quando è attiva la stampa locale.
xmpp_timeout_value	int (facoltativo)	Indica il numero di secondi tra i ping del canale XMPP. Per impostazione predefinita, DEVE essere pari o superiore a 300 (5 minuti).

Importante: la mancanza di valori facoltativi indica che la funzionalità corrispondente non è completamente supportata dal dispositivo.

4.1.2. Avvio

All'avvio del dispositivo, dovrebbe contattare il server per verificare quali API sono disponibili per essere esposte nella rete locale. Per le stampanti collegate a Cloud Print, devono chiamare:

/cloudprint/printer?printerid=<printer_id>

/cloudprint/list

È preferibile utilizzare /cloudprint/printer anziché /cloudprint/list, ma funzionano entrambe.

Questa API restituisce gli attuali parametri del dispositivo, incluse le impostazioni dell'API locale. La risposta dal server avrà il seguente formato:

"local_settings": {
        "current": {
                "local_discovery": true,
                "access_token_enabled": true,
                "printer/local_printing_enabled": true,
                "printer/conversion_printing_enabled": true,
                "xmpp_timeout_value": 300
         },
         "pending": {
                "local_discovery": true,
                "access_token_enabled": true,
                "printer/local_printing_enabled": false,
                "printer/conversion_printing_enabled": false,
                "xmpp_timeout_value": 500
         }
}

"attuale" oggetto indica le impostazioni in vigore al momento.

"in sospeso" l'oggetto indica le impostazioni che devono essere applicate al dispositivo (questo oggetto potrebbe mancare).

Quando il dispositivo vede le impostazioni in attesa, ne deve aggiornare lo stato (vedi di seguito).

4.1.2. Update

Se è necessario aggiornare le impostazioni, viene inviata una notifica XMPP al dispositivo. La notifica avrà il seguente formato:

<device_id>/update_settings

Quando riceve una notifica di questo tipo, il dispositivo DEVE inviare una query al server per ricevere le impostazioni più recenti. I dispositivi Cloud Print DEVONO utilizzare:

/cloudprint/printer?printerid=<printer_id>

Quando il dispositivo vede la sezione "in attesa" a causa dell'API /cloudprint/printer (all'avvio o a causa della notifica), il dispositivo DEVE aggiornare il proprio stato interno per memorizzare le nuove impostazioni. Per confermare le nuove impostazioni DEVE chiamare l'API del server. Per le stampanti cloud, il dispositivo DEVE chiamare l'API /cloudprint/update e utilizzare il parametro "quo_;local_settings" come durante la registrazione.

Quando ti riconnetti al canale XMPP, il dispositivo DEVE chiamare l'API /cloudprint/printer per controllare se le impostazioni locali sono state modificate dall'ultima volta.

4.1.3.1. Impostazioni locali in attesa

"local_settings" parametro utilizzato dal dispositivo per chiamare l'API del server NON DEVE contenere la sezione "in attesa".

4.1.3.2. Attuale impostazioni locali

SOLO il dispositivo può modificare la sezione "corrente" di "local_settings"." Tutti gli altri utenti modificheranno la sezione "in attesa" e attenderanno che le modifiche vengano propagate alla sezione "corrente" dal dispositivo.

4.1.3. Offline

Quando non è possibile contattare il server durante l'avvio, dopo la notifica, il dispositivo DEVE utilizzare le ultime impostazioni locali note.

4.1.5. Eliminazione del dispositivo dal servizio in corso...

Se il dispositivo è stato eliminato dal servizio (ad esempio GCP), verrà inviata una notifica XMPP. La notifica avrà il seguente formato:

<device_id>/delete

Quando riceve una notifica di questo tipo, il dispositivo DEVE andare sul server per controllarne lo stato. I dispositivi Cloud Print DEVONO utilizzare:

/cloudprint/printer?printerid=<printer_id>

Il dispositivo DEVE ricevere una risposta HTTP con esito positivo, senza descrizione del dispositivo e/o della stampante. Significa che il dispositivo è stato rimosso dal server e DEVE cancellare le credenziali e passare alla modalità predefinita delle impostazioni di fabbrica.

Ogni volta che il dispositivo riceve una risposta che indica che è stato eliminato a causa dell'API /cloudprint/printer (avvio, notifica di impostazioni di aggiornamento, ping giornaliero), DEVE eliminare le relative credenziali e passare alla modalità predefinita.

4.2. API /privet/info

L'API info è OBBLIGATORIA e deve essere implementata da ogni dispositivo. È una richiesta GET HTTP per "/privet/info" url: GET /privet/info HTTP/1.1

L'API info restituisce informazioni di base su un dispositivo e una funzionalità supportate. Questa API NON DEVE mai modificare lo stato del dispositivo o eseguire un'azione, poiché è vulnerabile agli attacchi XSRF. Questa è l'unica API consentita per avere un'intestazione "X-Privet-Token" vuota. I client devono chiamare l'API /privet/info con "X-Privet-Token" intestazione impostata su X-Privet-Token: ""

L'API delle informazioni DEVE restituire dati coerenti con i dati disponibili nel record TXT durante il rilevamento.

4.2.1. Input

L'API /privet/info non ha parametri di input.

4.2.2. Andata e ritorno

L'API /privet/info restituisce informazioni di base sul dispositivo e sulle funzionalità supportate.

La colonna TXT indica il campo corrispondente nel record TXT DNS-SD.

Nome valore	Tipo di valore	Descrizione	TXT
versione	string	La versione più recente (major.minor) dell'API supportata, attualmente 1.0
name	string	Nome leggibile del dispositivo.	ty
descrizione	string	(Facoltativo) Descrizione del dispositivo. DOVREBBE essere modificabile dall'utente.	nota
url	string	URL del server con cui comunica questo dispositivo. L'URL DEVE includere le specifiche del protocollo, ad esempio: https://www.google.com/cloudprint.	url
digita	Elenco di stringhe	Elenco dei tipi di dispositivi supportati.	digita
id	string	ID dispositivo, vuoto se il dispositivo non è ancora stato registrato.	id
stato_dispositivo	string	Lo stato del dispositivo. Inattivo indica che il dispositivo è pronto. Elaborazione significa che il dispositivo è occupato e la funzionalità potrebbe essere limitata per un po' di tempo. Operazione interrotta indica che il dispositivo non funziona e che è necessario l'intervento dell'utente.
stato_connessione	string	Stato della connessione al server (base_url) online - connessione disponibile offline - nessuna connessione connessione - passaggi di avvio in esecuzione non configurato - connessione non ancora configurata Un dispositivo registrato può segnalare il proprio stato di connessione in base allo stato del canale di notifica (ad es. stato della connessione XMPP).	cs
produttore	string	Nome del produttore del dispositivo
modello	string	Modello del dispositivo
numero_di_serie	string	Identificatore univoco del dispositivo. In questa specifica, DEVE essere un UUID. (Specifiche GCP 1.1) (facoltativo) Consigliamo vivamente di utilizzare lo stesso ID numero di serie ovunque, in modo che client diversi possano identificare lo stesso dispositivo. Ad esempio, le stampanti che implementano IPP possono utilizzare questo ID numero di serie nel campo "printer-device-id".
firmware	string	Versione firmware del dispositivo
tempo di attività	int	Numero di secondi dall'avvio del dispositivo.
url_configurazione	string	(facoltativo) URL (compreso il protocollo) della pagina con le istruzioni di configurazione
url_assistenza	string	(facoltativo) URL (compreso il protocollo) della pagina con assistenza, informazioni sulle domande frequenti
update_url	string	(facoltativo) URL (compreso il protocollo) della pagina con istruzioni per l'aggiornamento del firmware
token-x-privet	string	Valore dell'intestazione X-Privet-Token che deve essere passato a tutte le API per prevenire gli attacchi XSSI e XSRF. Vedi 6.1. per i dettagli.
api	descrizione delle API	Elenco delle API supportate (descritto di seguito)
stato_semantico	JSON	(Facoltativo) Stato semantico del dispositivo in formato CloudDeviceState.

api: è un elenco JSON contenente l'elenco delle API disponibili tramite la rete locale. Tieni presente che non tutte le API possono essere disponibili contemporaneamente sulla rete locale. Ad esempio, un nuovo dispositivo connesso dovrebbe supportare solo l'API /register:

"api": [
        "/privet/register",
]

Al termine della registrazione, il dispositivo DEVE interrompere il supporto dell'API /register. Il dispositivo deve inoltre contattare il servizio per fornire le API che possono essere esposte sulla rete locale. Ad esempio:

"api": [
        "/privet/accesstoken",
        "/privet/capabilities",
        "/privet/printer/submitdoc",
]

Al momento sono disponibili le seguenti API:

/privet/register: l'API per la registrazione dei dispositivi sulla rete locale. (consulta /privet/register API) per i dettagli. Questa API DEVE essere nascosta quando il dispositivo viene registrato correttamente nel cloud.
/privet/accesstoken - API per richiedere il token di accesso dal dispositivo (vedi /privet/accesstoken API per i dettagli).
/privet/capabilities: l'API per recuperare le funzionalità del dispositivo (consulta l'API /privet/capabilities per i dettagli).
/privet/printer/*: API specifica per il tipo di dispositivo "printer"; per informazioni dettagliate, consulta le API specifiche della stampante.

Ecco un esempio di risposta /privet/info. Tieni presente l'assenza dell'API /privet/register, poiché il dispositivo è già registrato.

{
        "version": "1.0",
        "name": "Gene’s printer",
        "description": "Printer connected through Chrome connector",
        "url": "https://www.google.com/cloudprint",
        "type": [
                "printer"
        ],
        "id": "11111111-2222-3333-4444-555555555555",
        "device_state": "idle",
        "connection_state": "online",
        "manufacturer": "Google",
        "model": "Google Chrome",
        "serial_number": "1111-22222-33333-4444",
        "firmware": "24.0.1312.52",
        "uptime": 600,
        "setup_url": "http://support.google.com/cloudprint/answer/1686197/?hl=en",
        "support_url": "http://support.google.com/cloudprint/?hl=en",
        "update_url": "http://support.google.com/cloudprint/?hl=en",
        "x-privet-token": "AIp06DjQd80yMoGYuGmT_VDAApuBZbInsQ:1358377509659",
        "api": [
                "/privet/accesstoken",
                "/privet/capabilities",
                "/privet/printer/submitdoc",
        ]
}

Ecco un esempio di risposta /privet/info per una stampante che ha esaurito l'inchiostro (nota il campo semantic_state):

{
        "version": "1.0",
        "name": "Gene’s printer",
        "description": "Printer connected through Chrome connector",
        "url": "https://www.google.com/cloudprint",
        "type": [
                "printer"
        ],
        "id": "11111111-2222-3333-4444-555555555555",
        "device_state": "stopped",
        "connection_state": "online",
        "manufacturer": "Google",
        "model": "Google Chrome",
        "serial_number": "1111-22222-33333-4444",
        "firmware": "24.0.1312.52",
        "uptime": 600,
        "setup_url": "http://support.google.com/cloudprint/answer/1686197/?hl=en",
        "support_url": "http://support.google.com/cloudprint/?hl=en",
        "update_url": "http://support.google.com/cloudprint/?hl=en",
        "x-privet-token": "AIp06DjQd80yMoGYuGmT_VDAApuBZbInsQ:1358377509659",
        "api": [
                "/privet/accesstoken",
                "/privet/capabilities",
                "/privet/printer/submitdoc",
        ],
        "semantic_state": {
                "version": "1.0",
                "printer": {
                        "state": "STOPPED",
                        "marker_state": {
                                "item": [
                                        {
                                                "vendor_id": "ink",
                                                "state": "EXHAUSTED",
                                                "level_percent": 0
                                        }
                                ]
                        }
                }
        }
}

4.2.3. Errori

/privet/info API dovrebbe restituire un errore SOLO se manca l'intestazione X-Privet-Token. DEVE essere un errore HTTP 400:

HTTP/1.1 400 Missing X-Privet-Token header.

4.3. API /privet/register

l'API /privet/register è facoltativa. Si tratta di una richiesta POST HTTP. /privet/register L'API DEVE verificare la presenza di un'intestazione X-Privet-Token valida. Il dispositivo DEVE implementare questa API su "/privet/register" url:

POST /privet/register?action=start&user=user@domain.com HTTP/1.1
POST /privet/register?action=complete&user=user@domain.com HTTP/1.1

Il dispositivo deve esporre l'API /privet/register SOLO quando consente la registrazione anonima al momento. Ad esempio:

Quando il dispositivo è acceso (o dopo aver fatto clic su un pulsante speciale sul dispositivo) e non è ancora stato registrato, deve esporre l'API /privet/register per consentire a un utente della rete locale di rivendicare la stampante.
Al termine della registrazione, il dispositivo non deve più esporre l'API /privet/register per impedire a un altro utente sulla rete locale di rivendicare il dispositivo.
Alcuni dispositivi potrebbero avere modi diversi di registrare i dispositivi e non dovrebbero esporre l'API /privet/register (ad esempio, il connettore Chrome Cloud Print).

Il processo di registrazione è composto da 3 passaggi (vedi la registrazione anonima per Cloud Print).

Avvia la procedura di registrazione anonima.
Un client avvia questa procedura chiamando l'API /privet/register. Il dispositivo potrebbe attendere la conferma dell'utente.
Recupera il token della rivendicazione.

Il client esegue un sondaggio per sapere quando il dispositivo è pronto per continuare. Quando il dispositivo è pronto, invia una richiesta al server per recuperare il token di registrazione e l'URL di registrazione. Il token e l'URL ricevuti DOVREBBE essere restituiti al client. Durante questo passaggio, se il dispositivo riceve un'altra chiamata per inizializzare la registrazione, deve:

Se si tratta dello stesso utente che ha avviato la registrazione, elimina tutti i dati precedenti (se presenti) e avvia una nuova procedura di registrazione.
Se si tratta di un utente diverso, restituisci l'errore device_occupato e 30 secondi di timeout.

Completa la procedura di registrazione.

Dopo aver rivendicato il dispositivo, il client deve notificare il completamento della registrazione. Al termine della procedura di registrazione, il dispositivo deve inviare un annuncio di aggiornamento, incluso l'ID dispositivo appena acquisito.

Nota: quando il dispositivo sta elaborando una chiamata API /privet/register, non è possibile elaborare contemporaneamente altre chiamate API /privet/register. Il dispositivo DEVE restituire l'errore device_occupato e 30 secondi di timeout.

È vivamente consigliata la conferma dell'utente per la registrazione sul dispositivo. Se implementato, il dispositivo DEVE attendere la conferma dell'utente DOPO che riceve una chiamata API /privet/register?action=start. Il client chiamerà l'API /privet/register?action=getClaimToken per sapere quando la conferma dell'utente è completa e se il token di richiesta è disponibile. Se l'utente annulla la registrazione sul dispositivo (ad esempio preme il pulsante Annulla), viene restituito l'errore user_cancel. Se l'utente non ha confermato la registrazione entro un determinato periodo di tempo, l'errore confermare_timeout DEVE essere restituito. Per ulteriori dettagli, consulta la sezione dei valori predefiniti.

4.3.1. Input

L'API /privet/register ha i seguenti parametri di input:

Nome	Valore
azione	Può essere uno dei seguenti: start - per avviare la procedura di registrazione getClaimToken - recupero del token di rivendicazione per il dispositivo cancel - per annullare il processo di registrazione complete - per completare il processo di registrazione
utente	Email dell'utente che rivendicherà il dispositivo.

Il dispositivo DEVE verificare che l'indirizzo email di tutte le azioni (start, getClaimToken, cancel, complete) corrisponda.

4.3.2. Andata e ritorno

/privet/register restituisce l'API i seguenti dati:

Nome valore	Tipo di valore	Descrizione
azione	string	Stessa azione del parametro di input.
utente	stringa (facoltativa)	Stesso utente del parametro di input (potrebbe essere mancante, se omesso nell'input).
token	stringa (facoltativa)	Token di registrazione (obbligatorio per la risposta &gett;getClaimToken" omessa per "quoit;start", "complete", "cancel").
reclamo_url	stringa (facoltativa)	URL di registrazione (obbligatorio per "&ClaimtToken}" Per le stampanti cloud deve essere indicato "&completet;complete_invito_url" ricevuto dal server.
automatizzate_claim_url	stringa (facoltativa)	URL di registrazione (obbligatorio per "&ClaimtToken}" Per le stampanti cloud deve essere ricevuto il messaggio "automazione_invito_url" ricevuto dal server.
id_dispositivo	stringa (facoltativa)	Nuovo ID dispositivo (omesso per "risposta", inizio obbligatorio per "completare").

Il dispositivo DEVE restituire il proprio ID dispositivo nella risposta dell'API /privet/info SOLO al termine della registrazione.

Esempio 1:

{
        "action": "start",
        "user": "user@domain.com",
}

Esempio 2:

{
        "action": "getClaimToken",
        "user": "user@domain.com",
        "token": "AAA111222333444555666777",
        "claim_url": "https://domain.com/SoMeUrL",
}

Esempio 3:

{
        "action": "complete",
        "user": "user@domain.com",
        "device_id": "11111111-2222-3333-4444-555555555555",
}

4.3.3. Errori

L'API /privet/register potrebbe restituire i seguenti errori (vedi la sezione relativa agli errori per maggiori dettagli):

Errore	Descrizione
dispositivo_occupato	Il dispositivo è occupato e non può eseguire l'azione richiesta. Riprova dopo il timeout.
in attesa_azione_utente	In risposta al messaggio "getClaimToken": questo errore indica che il dispositivo è ancora in attesa di conferma da parte dell'utente e "&ClaimtTokenToken" dovrebbe essere ritentata la richiesta dopo il timeout.
cancellazione_utente	L'utente ha annullato esplicitamente la procedura di registrazione dal dispositivo.
conferma_timeout	Timeout della conferma dell'utente.
azione_non_valida	Viene chiamata un'azione non valida. Ad esempio, se il client ha chiamato action=complete prima di chiamare action=start e action=getClaimToken.
parametri_non validi	Parametri non validi specificati nella richiesta. (I parametri sconosciuti devono essere ignorati in modo sicuro per una compatibilità futura). Ad esempio, restituisci questo valore se il client ha chiamato action=unknown o user=.
errore_configurazione_dispositivo	La data e l'ora (o alcune altre impostazioni) sono errate sul lato dispositivo. L'utente deve accedere al sito web interno del dispositivo e configurare le impostazioni del dispositivo.
offline	Al momento il dispositivo è offline e non può comunicare con il server.
errore_server	Errore del server durante la procedura di registrazione.
token_privato_non_valido	X-Privet-Token non è valido o è vuoto nella richiesta.

Il dispositivo DEVE interrompere l'esposizione dell'API /privet/register al termine della registrazione. Se il dispositivo non espone l'API /privet/register, DEVE restituire l'errore HTTP 404. Pertanto, se un dispositivo è già registrato, la chiamata a questa API DEVE restituire 404. Se manca l'intestazione X-Privet-Token, il dispositivo DEVE restituire l'errore HTTP 400.

4.4. API /privet/accesstoken

L'API /privet/accesstoken è FACOLTATIVO. Si tratta di una richiesta GET HTTP. /privet/accesstoken API DEVE verificare la presenza di un'intestazione "X-Privet-Token" valida. Il dispositivo DEVE implementare questa API sull' "/privet/accesstoken" url:

GET /privet/accesstoken HTTP/1.1

Quando il dispositivo riceve la chiamata API /accesstoken, deve chiamare il server per recuperare il token di accesso per l'utente specificato e restituire il token al client. Il client utilizzerà il token di accesso per accedere a questo dispositivo tramite il cloud.

I dispositivi Cloud Print DEVONO chiamare la seguente API:

/cloudprint/proximitytoken

e passa il parametro "printerid/#lt;printer_id>" e "user" dall'API locale. In caso di esito positivo, la risposta del server conterrà il seguente oggetto:

"proximity_token": {
        "user": "user@domain.com",
        "token": "AAA111222333444555666777",
        "expires_in": 600
}

I dispositivi Cloud Print DEVONO passare il valore dell'oggetto "proximity_token" nella risposta alle chiamate API locali /privet/accesstoken. È più vantaggioso (a prova di futuro) se il dispositivo può superare TUTTI i parametri (inclusi quelli non descritti in questa specifica).

4.4.1. Input

L'API /privet/accesstoken ha i seguenti parametri di input:

Nome	Valore
utente	Email dell'utente che intendeva utilizzare questo token di accesso. La richiesta potrebbe essere vuota.

4.4.2. Andata e ritorno

L'API /privet/accesstoken restituisce i seguenti dati:

Nome valore	Tipo di valore	Descrizione
token	string	Token di accesso restituito dal server
utente	string	Stesso utente del parametro di input.
scade_in	int	Numero di secondi alla scadenza di questo token. Ricevuto dal server e passato in questa risposta.

Esempio:

{
        "token": "AAA111222333444555666777",
        "user": "user@domain.com",
        "expires_in": 600
}

4.4.3. Errori

L'API /privet/accesstoken potrebbe restituire i seguenti errori (per informazioni dettagliate, consulta la sezione Errori):

Errore	Descrizione
offline	Al momento il dispositivo è offline e non può comunicare con il server.
accesso_rifiutato	Diritti insufficienti. Accesso negato Il dispositivo dovrebbe restituire questo errore quando la richiesta è stata rifiutata in modo esplicito dal server.
parametri_non validi	Parametri non validi specificati nella richiesta. (I parametri sconosciuti devono essere ignorati in modo sicuro per una compatibilità futura). Ad esempio, se il client ha chiamato /accesstoken?user= o /accesstoken.
errore_server	Errore del server.
token_privato_non_valido	X-Privet-Token non è valido o è vuoto nella richiesta.

Se il dispositivo non espone l'API /privet/accesstoken, DEVE restituire l'errore HTTP 404. Se manca l'intestazione X-Privet-Token, il dispositivo DEVE restituire l'errore HTTP 400.

4.5. API /privet/capabilities

L'API /privet/capabilities è facoltativa. Si tratta di una richiesta GET HTTP. L'API /privet/capabilities DEVE verificare la presenza di un'intestazione "X-Privet-Token" valida. Il dispositivo DEVE implementare questa API su "/privet/capabilities" url:

GET /privet/capabilities HTTP/1.1

Quando il dispositivo riceve la chiamata all'API /capabilities, se il dispositivo è in grado di farlo, DEVE contattare il server per ottenere le funzionalità aggiornate. Ad esempio, se una stampante supporta l'invio di un processo di stampa (ricevuto localmente) a se stesso tramite il servizio Cloud Print, dovrebbe restituire le capacità che il servizio Cloud Print restituirebbe. In questo caso, Cloud Print potrebbe alterare le funzionalità originali della stampante aggiungendo nuove funzionalità che potrebbe eseguire prima di inviare il processo alla stampante. Il caso più comune è un elenco di tipi di documenti supportati. Se la stampante è offline, dovrebbe restituire i tipi di documenti supportati. Tuttavia, se la stampante è online e registrata con Cloud Print, DEVE restituire "*/*" come uno dei tipi supportati. In questo caso, il servizio Cloud Print eseguirà la conversione necessaria. Per la stampa offline, la stampante DEVE supportare almeno il formato "ℑpwg-raster".

4.5.1. Input

L'API /privet/capabilities ha i seguenti parametri di input:

Nome	Valore
offline	(Facoltativo) Può essere solo "offline=1". In questo caso il dispositivo dovrebbe restituire le funzionalità per l'utilizzo offline (se sono diverse dalle funzionalità online).

4.5.2. Andata e ritorno

L'API /privet/capabilities restituisce le funzionalità del dispositivo nel formato JSON Cloud Device Description (CDD) (vedi il documento sul CDD per i dettagli). Le stampanti come minimo DEVONO restituire un elenco dei tipi supportati qui. Ad esempio, una stampante pronta per il cloud che è attualmente online potrebbe restituire un codice simile al seguente (almeno):

{
        "version": "1.0",
        "printer": {
                "supported_content_type": [
                        {
                                "content_type": "application/pdf",
                                "min_version": "1.4"
                        },
                        { "content_type": "image/pwg-raster" },
                        { "content_type": "image/jpeg" },
                        { "content_type": "*/*" }
                ]
        }
}

e, dopo essere stata disconnessa dal server, potrebbe restituire:

{
        "version": "1.0",
        "printer": {
                "supported_content_type": [
                        {
                                "content_type": "application/pdf",
                                "min_version": "1.4"
                        },
                        { "content_type": "image/pwg-raster" },
                        { "content_type": "image/jpeg" }
                ]
        }
}

Nota: le stampanti esprimono la priorità dei tipi di contenuti supportati utilizzando l'ordine. Ad esempio, negli esempi sopra riportati, la stampante specifica che preferisce "quo/application/pdf" rispetto a "image/pwg-raster" e "image/jpeg". Se possibile, i clienti devono rispettare la priorità della stampante (per informazioni dettagliate, consulta il documento CDD).

4.5.3. Errori

L'API /privet/capabilities potrebbe restituire i seguenti errori (per informazioni dettagliate, consulta la sezione Errori):

Errore	Descrizione
token_privato_non_valido	X-Privet-Token non è valido o è vuoto nella richiesta.

Se il dispositivo non espone l'API /privet/capabilities, DEVE restituire l'errore HTTP 404. Se manca l'intestazione X-Privet-Token, il dispositivo DEVE restituire l'errore HTTP 400.

4.6. Errori

Gli errori vengono restituiti dalle API riportate sopra nel seguente formato:

Nome valore	Tipo di valore	Descrizione
errore	string	Tipo di errore (definito per API)
descrizione	stringa (facoltativa)	Descrizione leggibile dell'errore.
server_api	stringa (facoltativa)	In caso di errore del server, questo campo contiene l'API del server non riuscita.
codice_server	int (facoltativo)	In caso di errore del server, questo campo contiene il codice di errore restituito dal server.
server_http_code	int (facoltativo)	In caso di errore HTTP del server, questo campo contiene il codice di errore HTTP restituito dal server.
Timeout	int (facoltativo)	Numero di secondi che il client deve attendere prima di riprovare (solo per errori recuperabili). Il client DEVE randomizzare il timeout effettivo da questo valore a un valore superiore al 20%.

Tutte le API DEVONO restituire l'errore HTTP 400 se manca l'intestazione X-Privet-Token.

HTTP/1.1 400 Intestazione X-Privet-Token mancante.

Esempio 1:

{
        "error": "server_error",
        "description": "Service unavailable",
        "server_api": "/submit",
        "server_http_code": 503
}

Esempio 2:

{
        "error": "printer_busy",
        "description": "Printer is currently printing other job",
        "timeout": 15
}

5. API Printer

Uno dei tipi di dispositivi supportati da questo protocollo è il tipo di stampante. I dispositivi che supportano questo tipo POSSONO implementare alcune funzionalità specifiche per le stampanti. Idealmente, la stampa su stampanti pronte per il cloud passa attraverso un server Cloud Print:

In alcuni casi, il client potrebbe dover inviare un documento a livello locale. Potrebbe essere necessario quando il client non ha un ID Google o non è in grado di comunicare con il server di Cloud Print. In questo caso, il processo di stampa verrà inviato localmente alla stampante. La stampante utilizzerà a sua volta il servizio Cloud Print per la coda dei job e la conversione. La stampante ripubblica il job inviato in locale al servizio Cloud Print e poi lo richiede, poiché è stato inviato tramite cloud. Questo processo fornirà un'esperienza utente flessibile in termini di servizio (conversione) e gestione/monitoraggio dei processi di stampa.

Poiché il servizio Cloud Print implementa la conversione, la stampante DEVE pubblicizzare tutti i formati di input ("*/*") nell'elenco dei tipi di contenuti supportati:

{
        "version": "1.0",
        "printer": {
                "supported_content_type": [
                        { "content_type": "image/pwg-raster" },
                        { "content_type": "*/*" }
                ]
        }
}

In alcuni casi è consigliabile avere una soluzione completamente offline. Poiché le stampanti supportano un numero limitato di formati di input, un client dovrà convertire i documenti in alcuni formati di stampanti supportati in modo nativo.

Questa specifica richiede che tutte le stampanti supportino almeno il formato PWG Raster ("image/pwg-raster") per la custodia di stampa offline. Una stampante potrebbe supportare altri formati (ad esempio JPEG) e, se un client la supporta, potrebbe inviare documenti in quel formato. La stampante DEVE esporre i tipi supportati tramite l'API /capabilities, ad esempio:

{
        "version": "1.0",
        "printer": {
                "supported_content_type": [
                        { "content_type": "image/pwg-raster" },
                        { "content_type": "image/jpeg" }
                ]
        }
}

Esistono due modi in cui il client può avviare la stampa sulla rete locale.

Stampa semplice: il client invia il documento sulla rete locale all'API /submitdoc (senza specificare il parametro job_id). Il documento inviato verrà stampato utilizzando le impostazioni predefinite per i biglietti di stampa e non sono necessari stati dei processi di stampa. Se la stampante supporta SOLO questo tipo di stampa, DEVE pubblicizzare SOLO l'API /submitdoc nella risposta dell'API /privet/info.

"api": [
        "/privet/accesstoken",
        "/privet/capabilities",
        "/privet/printer/submitdoc",
]

Stampa avanzata: il cliente deve prima creare un processo di stampa sulla stampante chiamando l'API /privet/printer/createjob con un ticket di lavoro CJT valido nella richiesta. La stampante DEVE archiviare il ticket cartaceo in memoria e restituire un job_id al client. Quindi il client chiamerà l'API /printer/submitdoc e specificherà il job_id ricevuto in precedenza. In quel momento la stampante inizierà a stampare. Il client eseguirà il polling dello stato del processo di stampa della stampante chiamando l'API /privet/printer/jobstate.

In un ambiente multi-cliente, non esiste alcuna garanzia di come venga chiamata questa API. È possibile che un client chiami /createjob tra le chiamate /createjob->/submitdoc di un altro client. Per eliminare i deadlock e migliorare l'usabilità, ti consigliamo di avere una piccola coda di processi di stampa in sospeso sulla stampante (almeno 3-5):

/createjob occupa il primo posto disponibile in coda.
La durata del job (in coda) è di almeno cinque minuti.
Se tutti i posti in coda vengono occupati, il job di stampa meno recente meno recente verrà rimosso e ne verrà posizionato uno nuovo.
Se al momento è presente un processo di stampa sul dispositivo (stampa semplice o avanzata), /submitdoc dovrebbe restituire lo stato occupato e proporre un timeout per riprovare questo processo di stampa.
Se /submitdoc si riferisce a un job che è stato rimosso dalla coda (a causa di sostituzione o timeout), la stampante dovrebbe restituire un errore invalid_print_job e il client riproverà il processo dal passaggio /createjob. Il client DEVE attendere un periodo di timeout casuale di massimo 5 secondi prima di riprovare.

Se i vincoli di memoria impediscono l'archiviazione di più processi in sospeso sul dispositivo, è possibile disporre di una coda di 1 processo di stampa. Deve comunque seguire lo stesso protocollo indicato sopra. Dopo che un job è stato completato o non è andato a buon fine, la stampante deve archiviare le informazioni sullo stato del job per almeno cinque minuti. Le dimensioni della coda per l'archiviazione degli stati dei job completati devono essere almeno 10. Se è necessario archiviare più stati dei job, quello meno recente potrebbe essere rimosso dalla coda prima del timeout di 5 minuti.

Nota: per il momento, i clienti chiederanno lo stato del job. In futuro, potremmo richiedere che la stampante invii la notifica DNS TXT quando viene modificato lo stato di qualsiasi processo di stampa.

5.1. API /privet/printer/createjob

L'API /privet/printer/createjob è FACOLTATIVO (vedi Stampa semplice sopra). Si tratta di una richiesta POST HTTP. /privet/printer/createjob L'API DEVE verificare la presenza di un'intestazione "X-Privet-Token" valida. Il dispositivo DEVE implementare questa API su "/privet/printer/createjob" url:

POST /privet/printer/createjob HTTP/1.1

Quando ricevi la chiamata API /privet/printer/createjob, la stampante DEVE creare un nuovo ID processo di stampa, archiviare il ticket di stampa ricevuto in formato CJT e restituire l'ID processo di stampa al client.

5.1.1. Input

L'API /privet/printer/createjob non ha parametri di input nell'URL. Il corpo della richiesta deve contenere i dati del ticket di stampa nel formato CJT.

5.1.2. Andata e ritorno

L'API /privet/printer/createjob restituisce i seguenti dati:

Nome valore	Tipo di valore	Descrizione
job_id	string	ID del processo di stampa appena creato.
scade_in	int	Numero di secondi valido per questo processo di stampa.

Esempio:

{
        "job_id": "123",
        "expires_in": 600
}

5.1.2. Errori

L'API /privet/printer/createjob potrebbe restituire i seguenti errori (vedi la sezione Errori per i dettagli):

Errore	Descrizione
biglietto_non valido	Il biglietto cartaceo inviato non è valido.
stampante_occupato	La stampante è occupata e al momento non è possibile elaborare /createjob. Riprova dopo il timeout.
stampante_errore	La stampante è in stato di errore e richiede l'interazione dell'utente per risolverlo. La descrizione deve contenere una spiegazione più dettagliata (ad esempio "Inceppamento della carta nel vassoio 1").
token_privato_non_valido	X-Privet-Token non è valido o è vuoto nella richiesta.

Se il dispositivo non mostra /privet/printer/createjob DEVE restituire un errore HTTP 404. Se manca l'intestazione X-Privet-Token, il dispositivo DEVE restituire l'errore HTTP 400.

5.2. API /privet/printer/submitdoc

L'API /privet/printer/submitdoc è obbligatoria per implementare la stampa su una rete locale (offline o per la ripubblicazione su Cloud Print). Si tratta di una richiesta POST HTTP. /privet/printer/submitdoc API DEVE verificare la presenza di un'intestazione "X-Privet-Token" valida. Il dispositivo DEVE implementare questa API all'indirizzo "/privet/printer/submitdoc" url:

POST /privet/printer/submitdoc HTTP/1.1

Quando ricevi la chiamata API /privet/printer/submitdoc, la stampante dovrebbe iniziare a stampare. Se non è possibile iniziare a stampare, DEVE restituire l'errore stampante_occupato e un periodo di timeout consigliato affinché il client possa attendere prima di riprovare.

Se la stampante non è in grado di contenere tutti i dati nel suo buffer interno, DEVE utilizzare i meccanismi TCP per rallentare il trasferimento dei dati finché non stampa una parte del documento, rendendo di nuovo disponibile il buffer. (ad esempio, la stampante può impostare windowsize=0 sui livelli TCP, il che costringerà il client ad attendere).

L'invio di un documento alla stampante potrebbe richiedere molto tempo. Il client dovrebbe essere in grado di controllare lo stato della stampante e del processo (stampa avanzata) mentre è in corso la stampa. Per farlo, la stampante DEVE consentire al client di chiamare le API /privet/info e /privet/printer/jobstate durante l'elaborazione delle chiamate API /privet/printer/submitdoc. È consigliabile a tutti i client di avviare un nuovo thread per eseguire la chiamata API /privet/printer/submitdoc, in modo che il thread principale possa utilizzare le API /privet/info e /privet/printer/jobstate per controllare gli stati della stampante e del job.

Nota: una volta completato o l'aborto del processo di stampa locale, è vivamente consigliato (e obbligatorio in una versione futura di questa specifica) per segnalare lo stato finale del lavoro all'interfaccia /cloudprint/submit per scopi di contabilità e di esperienza utente. I parametri "printerid", "title", "contentType" e "final_semantic_state" (in formato PrintJobState) sono obbligatori e i parametri "tag" (parametro ripetuto) e "quot;ticket" (il biglietto del job Cloud). Tieni presente che l'oggetto PrintJobState fornito deve essere effettivamente finale, ovvero che il suo tipo deve essere DONE o ABORTED ed è necessario fornire una causa nel caso in cui sia ABORTED (vedi JobState per i dettagli). Tieni inoltre presente che questo uso dell'interfaccia /cloudprint/submit per segnalare i processi di stampa locale non è menzionato nella sua specifica perché la sezione ha lo scopo di descrivere l'uso principale dell'interfaccia: l'invio di un processo di stampa con il documento da stampare fornito nel parametro "&content".

5.2.1. Input

L'API /privet/printer/submitdoc ha i seguenti parametri di input:

Nome	Valore
job_id	(Facoltativo) ID processo di stampa. Può essere omesso per richieste di stampa semplici (vedi sopra). Deve corrispondere a quello restituito dalla stampante.
nome_utente	(Facoltativo) Nome utente leggibile. Questa opzione non è definitiva e deve essere utilizzata solo per le annotazioni dei processi di stampa. Se il job viene ripubblicato nel servizio Cloud Print, questa stringa deve essere collegata al job Cloud Print.
client_name [nome_client]	(Facoltativo) Nome dell'applicazione client che invia la richiesta. Solo a scopo di visualizzazione. Se il job viene ripubblicato nel servizio Cloud Print, questa stringa deve essere allegata al job Cloud Print.
job_name	(Facoltativo) Nome del processo di stampa da registrare. Se il job viene ripubblicato nel servizio Cloud Print, questa stringa deve essere collegata al job Cloud Print.
offline	(Facoltativo) Può essere solo "offline=1". In questo caso, la stampante dovrebbe provare a stampare solo offline (non è necessario ripubblicare il server Cloud Print).

Il corpo della richiesta deve contenere un documento valido per la stampa. "Content-Length" dovrebbe includere la lunghezza corretta della richiesta. "Content-Type" l'intestazione deve essere impostata per documentare il tipo MIME e corrispondere a uno dei tipi nel CDD (a meno che CDD non specifichi "*/*").

Per questa richiesta, consigliamo ai client di fornire un nome utente (o un indirizzo email), un nome e un nome job validi. Questi campi vengono utilizzati solo nelle UI per migliorare l'esperienza utente.

5.2.2. Andata e ritorno

L'API /privet/printer/submitdoc restituisce i seguenti dati:

Nome valore	Tipo di valore	Descrizione
job_id	string	ID del processo di stampa appena creato (stampa semplice) o del job_id specificato nella richiesta (stampa avanzata).
scade_in	int	Numero di secondi valido per questo processo di stampa.
job_type	string	Tipo di contenuti del documento inviato.
dimensioni_offerta	Int 64 bit	Dimensioni dei dati di stampa in byte.
job_name	string	(Facoltativo) Stesso nome del job inserito (se presente).

Esempio:

{
        "job_id": "123",
        "expires_in": 500,
        "job_type": "application/pdf",
        "job_size": 123456,
        "job_name": "My PDF document"
}

5.2.3. Errori

L'API /privet/printer/submitdoc può restituire i seguenti errori (vedi la sezione relativa agli errori per i dettagli):

Errore	Descrizione
job_di_stampa_non_valido	L'ID job non valido o scaduto è specificato nella richiesta. Riprova dopo il timeout.
tipo_documento_non_valido	Il tipo MIME del documento non è supportato dalla stampante.
documento_non_valido	Il documento inviato non è valido.
documento_troppo_grande	Le dimensioni del documento superano il limite massimo consentito.
stampante_occupato	La stampante è occupata e al momento non è in grado di elaborare il documento. Riprova dopo il timeout.
stampante_errore	La stampante è in stato di errore e richiede l'interazione dell'utente per risolverlo. La descrizione deve contenere una spiegazione più dettagliata (ad esempio "Inceppamento della carta nel vassoio 1").
parametri_non validi	Parametri non validi specificati nella richiesta. (I parametri sconosciuti devono essere ignorati in modo sicuro per compatibilità futura)
cancellazione_utente	L'utente ha annullato esplicitamente il processo di stampa dal dispositivo.
errore_server	Pubblicazione del documento in Cloud Print non riuscita.
token_privato_non_valido	X-Privet-Token non è valido o è vuoto nella richiesta.

Se il dispositivo non espone /privet/printer/submitdoc, DEVE restituire l'errore HTTP 404. Se manca l'intestazione X-Privet-Token, il dispositivo DEVE restituire l'errore HTTP 400.

Nota: l'API /privet/printer/submitdoc può richiedere una gestione speciale sul lato stampante (a causa del grande payload collegato). In alcuni casi (dipende dall'implementazione del server HTTP e dalla piattaforma), la stampante potrebbe chiudere il socket PRIMA di restituire l'errore HTTP. In altri casi, la stampante potrebbe restituire l'errore 503 (anziché l'errore Privet). Le stampanti DOVREBBERO provare a restituire Privet. Tuttavia, ogni client che implementa la specifica Privet DEVE essere in grado di gestire la chiusura del socket (nessun errore HTTP) e i casi di errore HTTP 503 per l'API /privet/printer/submitdoc. In questo caso, il client DEVE gestirlo come un errore "printer_occupato" con "timeout" impostato su 15 secondi. Per evitare nuovi tentativi infiniti, il client può interrompere i tentativi dopo un numero ragionevole di tentativi (ad esempio 3).

5.3. API /privet/printer/jobstate

L'API /privet/printer/jobstate è FACOLTATIVO (vedi Stampa semplice sopra). Si tratta di una richiesta GET HTTP. /privet/printer/jobstate API DEVE verificare la presenza di un'intestazione "X-Privet-Token" valida. Il dispositivo DEVE implementare questa API su "/privet/printer/jobstate" url:

GET /privet/printer/jobstate HTTP/1.1

Quando riceve una chiamata API /privet/printer/jobstate, una stampante dovrebbe restituire lo stato del processo di stampa richiesto o un errore di job_print_job non valido.

5.3.1. Input

L'API /privet/printer/jobstate presenta i seguenti parametri di input:

Nome	Valore
job_id	ID processo di stampa per il quale restituire lo stato.

5.3.2. Andata e ritorno

L'API /privet/printer/jobstate restituisce i seguenti dati:

Nome valore	Tipo di valore	Descrizione
job_id	string	ID processo di stampa per informazioni sullo stato.
state	string	bozza: sul dispositivo è stato creato un processo di stampa (non sono ancora state ricevute chiamate /privet/printer/submitdoc). in coda: il processo di stampa è stato ricevuto e messo in coda, ma la stampa non è ancora iniziata. in_progress: il processo di stampa è in corso di stampa. interrotto: il processo di stampa è stato messo in pausa, ma può essere riavviato manualmente o in modo automatico. Fine: il processo di stampa è terminato. interrotta: processo di stampa non riuscito.
descrizione	string	(Facoltativo) Descrizione leggibile dello stato del processo di stampa. Devono includere informazioni aggiuntive se lo stato< è interrotto o interrotto. Il campo semantic_state di solito fornisce una descrizione migliore e più significativa del client.
scade_in	int	Numero di secondi valido per questo processo di stampa.
job_type	string	(Facoltativo) Tipo di contenuti del documento inviato.
dimensioni_offerta	Int 64 bit	(Facoltativo) Le dimensioni dei dati di stampa in byte.
job_name	string	(Facoltativo) Stesso nome del job inserito (se presente).
server_job_id	string	(Facoltativo) ID del job restituito dal server (se il job è stato pubblicato sul servizio Cloud Print). Omesso per la stampa offline.
stato_semantico	JSON	(Facoltativo) Stato semantico del job in formato PrintJobState.

Esempio (stampa con un report tramite Cloud Print):

{
        "job_id": "123",
        "state": "in_progress",
        "expires_in": 100,
        "job_type": "application/pdf",
        "job_size": 123456,
        "job_name": "My PDF document",
        "server_job_id": "1111-2222-3333-4444"
}

Esempio (errore di stampa offline):

{
        "job_id": "123",
        "state": "stopped",
        "description": "Out of paper",
        "expires_in": 100,
        "job_type": "application/pdf",
        "job_size": 123456,
        "job_name": "My PDF document"
}

Esempio (processo di stampa interrotto dall'utente):

{
        "job_id": "123",
        "state": "aborted",
        "description": "User action",
        "expires_in": 100,
        "job_type": "application/pdf",
        "job_size": 123456,
        "job_name": "My PDF document",
        "semantic_state": {
                "version": "1.0",
                "state": {
                        "type": "ABORTED",
                        "user_action_cause": {"action_code": "CANCELLED"}
                },
                "pages_printed": 7
        }
}

Esempio (il processo di stampa è stato interrotto a causa della carta). Osserva il riferimento allo stato del dispositivo. Il client dovrà chiamare l'API /privet/info per ottenere maggiori dettagli sullo stato del dispositivo:

{
        "job_id": "123",
        "state": "stopped",
        "description": "Out of paper",
        "expires_in": 100,
        "job_type": "application/pdf",
        "job_size": "123456",
        "job_name": "My PDF document",
        "semantic_state": {
                "version": "1.0",
                "state": {
                        "type": "STOPPED",
                        "device_state_cause": {"error_code": "INPUT_TRAY"}
                },
                "pages_printed": 7
        }
}

5.3.3. Errori

L'API /privet/printer/jobstate potrebbe restituire i seguenti errori (vedi la sezione relativa agli errori per i dettagli):

Errore	Descrizione
job_di_stampa_non_valido	L'ID job non valido o scaduto è specificato nella richiesta.
errore_server	Recupero dello stato del processo di stampa (per i processi di stampa pubblicati in Cloud Print) non riuscito.
token_privato_non_valido	X-Privet-Token non è valido o è vuoto nella richiesta.

Se il dispositivo non mostra /privet/printer/jobstate, DEVE restituire l'errore HTTP 404. Se manca l'intestazione X-Privet-Token, il dispositivo DEVE restituire l'errore HTTP 400.

6. Appendix

6.1. Comportamento e impostazioni predefiniti

Questa sezione spiega il comportamento predefinito che ci aspettiamo da TUTTI i dispositivi compatibili con Privet.

I dispositivi pronti all'uso devono supportare solo le API /privet/info e /privet/register. Tutte le altre API (ad esempio /privet/accesstoken, stampa locale) devono essere disabilitate.
La registrazione richiede un'interazione fisica con un dispositivo.

L'utente DEVE compiere un'azione fisica sul dispositivo (ad esempio premere un pulsante) per confermare l'accesso al dispositivo.
Dopo che l'utente intraprende l'azione sopra indicata, la stampante dovrebbe inviare la richiesta /cloudprint/register. Non deve inviare questa richiesta fino all'esecuzione dell'azione (vedi il diagramma della sequenza 1).
Se il dispositivo sta elaborando una richiesta /privet/register (ad esempio in attesa dell'azione precedente), deve rifiutare tutte le altre richieste /privet/register. In questo caso il dispositivo DEVE restituire l'errore device_occupato.
Il dispositivo deve timeout di una richiesta /register che non riceva l'azione fisica descritta in precedenza entro 60 secondi. In questo caso, il dispositivo DEVE restituire l'errore confermare_timeout.
Facoltativo: consigliato ma non obbligatorio, i seguenti aspetti possono migliorare l'esperienza utente:

La stampante potrebbe lampeggiare una spia o lo schermo per indicare che l'utente deve intraprendere un'azione per confermare la registrazione.
La stampante potrebbe visualizzare sul suo schermo il messaggio "È in corso la registrazione a Google Cloud Print per l'utente "abc@def.com". Premi OK per continuare", dove abc@def.com è il parametro utente della chiamata API /register. Questo renderebbe più chiaro a un utente che:

è la loro richiesta di registrazione di confermare
Che cosa succede se non ha attivato la richiesta.

Oltre a un'azione fisica da confermare dalla stampante (ad es. "Premi il pulsante OK"), una stampante potrebbe anche offrire all'utente un pulsante per annullare la richiesta (ad esempio "Premi Annulla per rifiutare". In questo modo, gli utenti che non hanno attivato la richiesta di registrazione devono annullarla prima del timeout di 60 secondi. In questo caso, il dispositivo DEVE restituire l'errore user_cancel.

Trasferimenti della proprietà:

Il dispositivo potrebbe essere eliminato in modo esplicito dal servizio Cloud.

Se il dispositivo ha esito positivo, ma non è presente alcuna descrizione per la chiamata /cloudprint/printer (per GCP), DEVE tornare alla modalità predefinita (non in uso).
Se le credenziali del dispositivo non funzionano più (in modo esplicito per via di credenziali "non valide" come risposta dal server), DEVE tornare alla modalità predefinita (non in uso).

Il ripristino dei dati di fabbrica locale DEVE cancellare le credenziali del dispositivo e impostarlo sullo stato predefinito.
Facoltativo: il dispositivo potrebbe fornire una voce di menu per cancellare le credenziali e impostarla in modalità predefinita.

I dispositivi che supportano le notifiche XMPP DEVONO includere la possibilità di inviare un ping al server. Il timeout del ping DEVE essere controllabile dal server tramite "local_settings".
Il dispositivo potrebbe inviare esplicitamente un ping al server (API /cloudprint/printer per GCP, oltre ai ping XMPP) non più di una volta al giorno (24 ore) per assicurarsi che siano sincronizzati. Ti consigliamo di randomizzare la finestra di controllo in un periodo di 24-32 ore.
Facoltativo: per i dispositivi Cloud Print è consigliato, ma non è necessario, impostare una modalità manuale (pulsante) per consentire all'utente di avviare un controllo della presenza di nuovi processi di stampa dal dispositivo. Alcune stampanti hanno già questa impostazione.
(Facoltativo) Le stampanti aziendali potrebbero avere la possibilità di disattivare completamente il rilevamento locale. In tal caso, il dispositivo DEVE aggiornare queste impostazioni locali sul server. Le nuove impostazioni locali DEVONO essere vuote (impostazione "local_discovery" su "false" significa che possono essere riattivate dal servizio GCP).

6.1.2 Diagramma di registrazione predefinita

6.2. Attacchi e prevenzione XSSI e XSRF

Questa sezione spiega la possibilità di attacchi XSSI e XSRF sul dispositivo e come proteggerli (incluse le tecniche di generazione di token).
Ulteriori dettagli sono disponibili qui: http://Bigtablesecurity.blogspot.com/2011/05/website-security-for-webmasters.html
Normalmente, gli attacchi XSSI e XSRF sono possibili quando un sito utilizza meccanismi di autenticazione dei cookie. Anche se Google non utilizza i cookie con il proprio servizio Cloud Print, tali attacchi sono comunque possibili. L'accesso alla rete locale, per definizione, considera implicitamente le richieste.

6.2.1. Scansione XSSI

Un sito web dannoso può provare a indovinare l'indirizzo IP e il numero di porta di un dispositivo compatibile con Privet e provare a chiamare l'API Privet utilizzando ""src/#lt;api name>" all'interno di un tag <script>:

<script type="text/javascript" src="http://192.168.1.42:8080/privet/info"></script>

Senza la protezione, i siti web dannosi potrebbero eseguire chiamate API e accedere ai risultati.
Per evitare questo tipo di attacco, TUTTE le chiamate API Privet DEVONO richiedere l'intestazione "&-X-Privet-Token" nella richiesta. I tag "script" non possono aggiungere intestazioni, proteggendosi da questo tipo di attacco.

6.2.2. Logo XSRF

http://en.wikipedia.org/wiki/Cross-site_request_forgery
È possibile che un sito web dannoso supponga che l'indirizzo IP e il numero di porta di un dispositivo compatibile con Privet cerchino di chiamare l'API Privet utilizzando un modulo <iframe>, moduli o altri meccanismi di caricamento tra siti web. Gli utenti malintenzionati non sarebbero in grado di accedere ai risultati della richiesta, ma se la richiesta eseguisse un'azione (ad esempio la stampa), potrebbe attivarla.

Per impedire questo attacco, abbiamo bisogno della seguente protezione:

Lascia l'API /privet/info aperta per XSRF
L'API /privet/info NON DEVE eseguire azioni sul dispositivo
Utilizza l'API /privet/info per ricevere x-privet-token
Tutte le altre API DEVONO verificare la presenza di un x-privet-token valido nell'intestazione "X-Privet-Token"".
x-privet-token DEVE essere valido solo per 24 ore.

Anche se un utente malintenzionato è in grado di eseguire l'API /privet/info, non potrebbe leggere x-privet-token dalla risposta e non essere in grado di chiamare altre API.

Ti consigliamo vivamente di generare il token XSRF utilizzando il seguente algoritmo:

XSRF_token = base64( SHA1(device_secret + DELIMITER + issue_timecounter) + DELIMITER + issue_timecounter )

Elementi di generazione token XSRF:

DELIMITER è un carattere speciale, di solito ":"
issue_timeCounter è un numero di secondi dato che qualche evento (epoca per il timestamp) o tempo di avvio del dispositivo (per i contatori di CPU). issue_timeCounter aumenta costantemente quando il dispositivo è attivo e in esecuzione (vedi la verifica del token di seguito).
SHA1: la funzione hash che utilizza l'algoritmo SHA1.
base64: codifica base64
device_secret: un secret specifico del dispositivo. Il secret del dispositivo DEVE essere aggiornato a ogni riavvio.

Modi consigliati per generare il secret del dispositivo:

Genera un nuovo UUID a ogni riavvio
Genera un numero casuale a 64 bit a ogni riavvio

Il dispositivo non è tenuto ad archiviare tutti i token XSRF emessi. Quando il dispositivo deve verificare la validità di un token XSRF, deve decodificare base64. Recupera il valore issue_timeCounter dalla seconda metà (cleartext) e prova a produrre l'hash SHA1 di device_secret + + issue_timeCounter, dove issue_timeCounter è il token. Se l'algoritmo SHA1 appena generato corrisponde a quello nel token, il dispositivo deve verificare se issue_timeCounter è compreso nel periodo di validità da (24 ore) del contatore dell'ora corrente. Per farlo, il dispositivo prende il contatore del tempo attuale (ad esempio, il contatore CPU) e ne sottrae il valore issue_timeCounter. Il risultato DEVE essere il numero di secondi da cui si è verificato il problema del token.

Importante: questo è il modo consigliato per implementare la protezione XSRF. I client della specifica Privet non cercheranno di comprendere il token XSRF, ma tratteranno come una blackbox. La Figura 6.2.3 illustra un modo consigliato per implementare l'X-Privet-Token e la verifica di una richiesta tipica.

6.2.3 Generazione di token X-Privet e diagramma della sequenza di verifica

6.3 Diagrammi del flusso di lavoro

Questa sezione illustrerà un flusso di lavoro in diversi casi.

6.3.1. Flusso di lavoro delle stampanti pronte all'uso

6.3.2. Avvio di una stampante registrata

6.3.3 Flusso di lavoro di gestione delle notifiche XMPP

6.3.4. Controlla il flusso di lavoro delle impostazioni della stampante