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
Discovery: meccanismi di scoperta locali
Annunci: annunci di scoperta locale
API: API private per dispositivi cloud generici
API Printer: API private utilizzate dalle stampanti
Appendice: diagrammi supplementari

1. Introduzione

I dispositivi connessi al cloud offrono molti vantaggi. Possono utilizzare servizi di conversione online, ospitare code di lavoro mentre il dispositivo è offline ed essere accessibili da qualsiasi parte del 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 è quello di combinare la flessibilità dei dispositivi cloud con un meccanismo di rilevamento locale adatto, in modo che i dispositivi vengano rilevati facilmente in nuovi ambienti.

Gli obiettivi di questo protocollo sono:

rendere rilevabili localmente i dispositivi cloud
registrare dispositivi cloud con un servizio cloud
associare i dispositivi registrati alla relativa rappresentazione cloud
abilitare le funzionalità offline.
semplificare l'implementazione in modo che possa essere utilizzata da dispositivi di piccole dimensioni

Il protocollo Privet è composto da due parti principali: individuazione 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. In questo documento, il dispositivo si riferisce a un dispositivo connesso al cloud <x0A> che implementa il protocollo Privet.

2. Discovery

Discovery è un protocollo basato su Zeroconf (mDNS + DNS-SD). Il dispositivo DEVE implementare l'indirizzamento locale rispetto al collegamento IPv4. Il dispositivo DEVE essere conforme alle specifiche mDNS e DNS-SD.

http://www.rfc-editor.org/rfc/rfc3927.txt (IPv4 Link-local)
http://www.rfc-editor.org/rfc/rfc4862.txt (IPv6 Link-local)
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

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

Il dispositivo può implementare anche altri tipi di servizi. Ti consigliamo di utilizzare lo stesso nome dell'istanza del servizio per tutti i tipi di servizi implementati dal dispositivo. Ad esempio, una stampante può implementare i servizi "Printer XYZ._privet._tcp" e "Printer XYZ._printer._tcp". Semplificherà la configurazione per l'utente. Tuttavia, i client Privet cercheranno solo "_privet._tcp".

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

Al momento l'unico sottotipo di dispositivo supportato è printer. Pertanto, 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 con il byte di lunghezza seguito da un massimo di 255 byte di testo. La chiave è il testo prima del primo carattere "=" e il valore è il testo dopo il primo carattere "=" fino alla fine. La specifica non prevede alcun valore nel record, in questo caso non sarà presente il carattere "=" NÉ testo dopo il carattere "=". (Consulta la specifica DNS-SD: "6.1. Regole generali di formato per i record DNS TXT" per il formato del record DNS TXT e "6.2. DNS-SD TXT Record Size" (Dimensioni record) per la lunghezza consigliata.

Privet richiede che il dispositivo invii le seguenti coppie chiave/valore nel record TXT. Le stringhe 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). sezione API).

Si consiglia di mantenere le dimensioni del record TXT al di sotto di 512 byte.

2.2.1. txtvers

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

txtvers=1

2.2.2. ty

Fornisce un nome del dispositivo leggibile dall'utente. Ad esempio:

ty=Google Cloud Ready Printer Model XYZ

2.2.3. Nota (facoltativa)

Fornisce un nome del dispositivo leggibile dall'utente. Ad esempio:

note=1st floor lobby printer

Nota: questa è una chiave facoltativa e può essere ignorata. Tuttavia, se presente, l'utente DOVREBBE essere in grado di modificare questo valore. La stessa descrizione DEVE essere utilizzata durante la registrazione del dispositivo.

2.2.4. url

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

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

2.2.5. type

Elenco separato da virgole dei sottotipi di dispositivi supportati da questo dispositivo. Il formato è: "type=_subtype1,_subtype2". Al momento, l'unico sottotipo di dispositivo supportato è printer.

type=printer

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

2.2.6. id

ID dispositivo. Se il dispositivo non è ancora stato registrato, questa chiave deve essere presente, 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 sono definiti quattro valori possibili.

"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 in corso" 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 viene attualmente utilizzato, ma potrebbe essere utile nelle versioni future della specifica.

Ad esempio:

cs=online
cs=offline
cs=connecting

Se il dispositivo è stato registrato con un cloud, all'avvio deve verificare la connettività con un server per rilevare lo stato della connessione (ad esempio, chiamando l'API cloud per ottenere le impostazioni del dispositivo). Il dispositivo potrebbe utilizzare lo stato della connessione del canale di notifica (ad es. XMPP) per segnalare questo valore. I dispositivi non registrati all'avvio potrebbero eseguire il ping di un dominio per rilevare il proprio stato di connessione (ad esempio, il ping di www.google.com per i dispositivi di stampa cloud).

3. Annunci

All'avvio, all'arresto o al cambio di stato del dispositivo, quest'ultimo DEVE eseguire il passaggio di annuncio come descritto nella specifica mDNS. DEVE inviare l'annuncio corrispondente almeno due volte con un intervallo di almeno un secondo tra un invio e l'altro.

3.1. Avvio

All'avvio del dispositivo, DEVE eseguire i passaggi di probing e annuncio descritti nella specifica mDNS. In questo caso, devono essere inviati i record SRV, PTR e TXT. Ti consigliamo di raggruppare tutti i record in un'unica risposta DNS, se possibile. In caso contrario, è consigliato il seguente ordine: SRV, PTR, TXT.

3.2. Arresto

Allo spegnimento del dispositivo, DOVREBBE tentare di comunicarlo a tutte le parti interessate inviando un "pacchetto di saluto" con TTL=0 (come descritto nella documentazione mDNS).

3.3 Aggiorna

Se una qualsiasi informazione descritta nel record TXT è cambiata, il dispositivo DEVE inviare un annuncio di aggiornamento. In questo caso, è sufficiente inviare solo il nuovo record TXT. Ad esempio, dopo la registrazione di un dispositivo, questo DEVE inviare un annuncio di aggiornamento che includa il nuovo ID dispositivo.

4. API

Una volta 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 che può avere un'intestazione "X-Privet-Token" vuota è la richiesta /privet/info (nota che l'intestazione DEVE comunque essere presente). Se l'intestazione "X-Privet-Token" non è presente, 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 "invalid X-Privet-Token error" (invalid_x_privet_token, vedi la sezione Errori per i dettagli). L'unica eccezione è l'API /info. Per ulteriori informazioni sul motivo per cui viene eseguita questa operazione e su come devono essere generati i token, consulta l'appendice A: Attacchi XSSI e XSRF e prevenzione.

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

4.1. Disponibilità API

Prima che venga esposta QUALSIASI API (inclusa l'API /info), il dispositivo DEVE contattare il server per controllare le impostazioni locali. Le impostazioni locali DEVONO essere mantenute tra i riavvii. Se il server non è disponibile, devono essere utilizzate le ultime impostazioni locali note. Se il dispositivo non è ancora stato registrato, deve seguire le impostazioni predefinite.

I dispositivi Cloud Print DEVONO seguire i passaggi riportati di seguito per registrarsi, 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 impostare le seguenti impostazioni:

Nome valore	Tipo di valore	Descrizione
local_discovery	booleano	Indica se la funzionalità di rilevamento locale è consentita. Se il valore è "false", tutte le API locali (inclusa /info) e il rilevamento DNS-SD devono essere disattivati. Per impostazione predefinita, i dispositivi appena registrati devono superare il test con il valore "true".
access_token_enabled	booleano (facoltativo)	Indica se l'API /accesstoken deve essere esposta sulla rete locale. Per impostazione predefinita, dovrebbe essere "true".
printer/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, dovrebbe essere "true".
printer/conversion_printing_enabled	booleano (facoltativo)	Indica se la stampa locale può inviare il lavoro al server per la conversione. Ha senso solo se la stampa locale è abilitata.
xmpp_timeout_value	int (facoltativo)	Indica il numero di secondi tra i ping del canale XMPP. Per impostazione predefinita DEVE essere 300 (5 minuti) o più.

Importante: la mancanza di qualsiasi valore facoltativo indica che la funzionalità corrispondente non è completamente supportata dal dispositivo.

4.1.2. Avvio

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

/cloudprint/printer?printerid=<printer_id>

oppure

/cloudprint/list

/cloudprint/printer è preferibile a /cloudprint/list, ma entrambi funzionano.

Questa API restituisce i parametri attuali del dispositivo, incluse le impostazioni per l'API locale. La risposta del 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
         }
}

L'oggetto "current" indica le impostazioni in vigore al momento.

L'oggetto "pending" indica le impostazioni da applicare al dispositivo (questo oggetto potrebbe non essere presente).

Una volta che il dispositivo visualizza le impostazioni "In attesa", DEVE aggiornare il proprio stato (vedi sotto).

4.1.3. Aggiorna

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

<device_id>/update_settings

Alla ricezione di una notifica di questo tipo, il dispositivo DEVE interrogare il server per ottenere le impostazioni più recenti. I dispositivi Cloud Print DEVONO utilizzare:

/cloudprint/printer?printerid=<printer_id>

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

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

4.1.3.1. Impostazioni locali in attesa

Il parametro "local_settings" che il dispositivo utilizza per chiamare l'API server NON deve mai contenere la sezione "pending".

4.1.3.2. Impostazioni locali attuali

SOLO il dispositivo può modificare la sezione "current" 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.4. Offline

Se 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

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

<device_id>/delete

Alla ricezione di una notifica di questo tipo, il dispositivo DEVE connettersi al server per controllare il proprio stato. I dispositivi di stampa nel cloud DEVONO utilizzare:

/cloudprint/printer?printerid=<printer_id>

Il dispositivo DEVE ricevere una risposta HTTP positiva con success=false e nessuna descrizione di dispositivo/stampante. Significa che il dispositivo è stato rimosso dal server e DEVE cancellare le credenziali e passare alla modalità di impostazioni di fabbrica predefinite.

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

4.2. API /privet/info

L'API info è OBBLIGATORIA e DEVE essere implementata da ogni dispositivo. Si tratta di una richiesta HTTP GET per l'URL "/privet/info": GET /privet/info HTTP/1.1

L'API info restituisce informazioni di base su un dispositivo e sulle funzionalità che supporta. Questa API NON deve mai modificare lo stato del dispositivo o eseguire alcuna azione, poiché è vulnerabile agli attacchi XSRF. Questa è l'UNICA API autorizzata ad avere un'intestazione "X-Privet-Token" vuota. I client devono chiamare l'API /privet/info con l'intestazione "X-Privet-Token" impostata su X-Privet-Token: ""

L'API info DEVE restituire dati coerenti con quelli disponibili nel record TXT durante l'individuazione.

4.2.1. Input

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

4.2.2. Indietro

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	stringa	Versione più recente (principale.secondaria) dell'API supportata, attualmente 1.0
nome	stringa	Nome del dispositivo leggibile.	ty
descrizione	stringa	(Facoltativo) Descrizione del dispositivo. DEVE essere modificabile dall'utente.	nota
url	stringa	L'URL del server con cui comunica questo dispositivo. L'URL DEVE includere la specifica del protocollo, ad esempio: https://www.google.com/cloudprint.	url
tipo	elenco di stringhe	Elenco dei tipi di dispositivi supportati.	tipo
id	stringa	ID dispositivo, vuoto se il dispositivo non è ancora stato registrato.	id
device_state	stringa	Stato del dispositivo. idle significa che il dispositivo è pronto processing significa che il dispositivo è occupato e la funzionalità potrebbe essere limitata per un po' di tempo stopped significa che il dispositivo non funziona ed è necessario l'intervento dell'utente
connection_state	stringa	Stato della connessione al server (base_url) online: connessione disponibile offline: nessuna connessione connecting: esecuzione dei passaggi di avvio not-configured: la connessione non è ancora stata 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	stringa	Nome del produttore del dispositivo
modello	stringa	Il modello del dispositivo
serial_number	stringa	Identificatore univoco del dispositivo. In questa specifica, questo valore DEVE essere un UUID. (GCP 1.1 spec) (facoltativo) Ti consigliamo vivamente di utilizzare lo stesso ID numero di serie ovunque, in modo che i diversi client possano identificare lo stesso dispositivo. Ad esempio, le stampanti che implementano IPP possono utilizzare questo numero di serie nel campo "printer-device-id".
firmware	stringa	Versione firmware dispositivo
periodo di attività	int	Numero di secondi dall'avvio del dispositivo.
setup_url	stringa	(facoltativo) URL (incluso il protocollo) della pagina con le istruzioni di configurazione
support_url	stringa	(facoltativo) URL (incluso il protocollo) della pagina con informazioni di assistenza e domande frequenti
update_url	stringa	(facoltativo) URL (incluso il protocollo) della pagina con le istruzioni per l'aggiornamento del firmware
x-privet-token	stringa	Valore dell'intestazione X-Privet-Token da trasmettere a tutte le API per impedire attacchi XSSI e XSRF. Per i dettagli, consulta la sezione 6.1.
api	descrizione delle API	Elenco delle API supportate (descritte di seguito)
semantic_state	JSON	(facoltativo) Stato semantico del dispositivo nel formato CloudDeviceState.

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

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

Una volta completata la registrazione del dispositivo, il dispositivo NON DEVE più supportare l'API /register. Il dispositivo deve anche verificare con il servizio quali API 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: API per la registrazione del dispositivo sulla rete locale. (per i dettagli, consulta l'API /privet/register). Questa API DEVE essere nascosta una volta che il dispositivo è stato registrato correttamente nel cloud.
/privet/accesstoken: API per richiedere il token di accesso dal dispositivo (vedi l'API /privet/accesstoken per i dettagli).
/privet/capabilities: API per recuperare le funzionalità del dispositivo (vedi /privet/capabilities API per i dettagli).
/privet/printer/*: API specifica per il tipo di dispositivo "stampante". Per maggiori dettagli, consulta le API specifiche per la stampante.

Ecco un esempio di risposta di /privet/info. (Nota l'assenza dell'API /privet/register, poiché questo è un 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 della 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

L'API /privet/info deve 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. /privet/register API

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

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.
Una volta completata la registrazione, il dispositivo deve interrompere l'esposizione dell'API /privet/register per impedire a un altro utente della rete locale di rivendicare il dispositivo.
Alcuni dispositivi potrebbero avere modi diversi per registrare i dispositivi e non devono esporre l'API /privet/register (ad esempio, il connettore Chrome Cloud Print).

La procedura di registrazione è composta da tre passaggi (vedi Registrazione anonima per Cloud Print).

Avvia la procedura di registrazione anonima.
Un client avvia questo processo chiamando l'API /privet/register. Il dispositivo potrebbe attendere la conferma dell'utente in quel momento.
Ottieni il token di richiesta.

Il client esegue il polling per scoprire 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 DEVONO 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 altro utente, restituisci l'errore device_busy e un timeout di 30 secondi.

Completa la procedura di registrazione.

Una volta rivendicato il dispositivo, il client deve inviare una notifica al dispositivo per completare la registrazione. Una volta completata la procedura di registrazione, il dispositivo deve inviare un annuncio di aggiornamento, incluso l'ID dispositivo appena acquisito.

Nota: quando il dispositivo elabora una chiamata API /privet/register, non possono essere elaborate contemporaneamente altre chiamate API /privet/register. Il dispositivo DEVE restituire l'errore device_busy e un timeout di 30 secondi.

La conferma dell'utente per la registrazione sul dispositivo è VIVAMENTE consigliata. Se implementato, il dispositivo DEVE attendere la conferma dell'utente DOPO aver ricevuto una chiamata API /privet/register?action=start. Il client chiamerà l'API /privet/register?action=getClaimToken per scoprire quando la conferma dell'utente è completata e il token di rivendicazione è disponibile. Se l'utente annulla la registrazione sul dispositivo (ad es. preme il pulsante Annulla), deve essere restituito l'errore user_cancel. Se l'utente non ha confermato la registrazione entro un determinato periodo di tempo, DEVE essere restituito l'errore confirmation_timeout. Per maggiori dettagli, consulta la sezione 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: per recuperare il token di rivendicazione per il dispositivo cancel: per annullare la procedura di registrazione complete: per completare la procedura di registrazione
utente	Email dell'utente che rivendicherà questo dispositivo.

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

4.3.2. Indietro

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

Nome valore	Tipo di valore	Descrizione
azione	stringa	Stessa azione del parametro di input.
utente	stringa (facoltativo)	Lo stesso utente del parametro di input (potrebbe mancare se omesso nell'input).
token	stringa (facoltativo)	Token di registrazione (obbligatorio per la risposta "getClaimToken", omesso per "start", "complete", "cancel").
claim_url	stringa (facoltativo)	URL di registrazione (obbligatorio per la risposta "getClaimToken", omesso per "start", "complete", "cancel"). Per le stampanti cloud deve essere l'"complete_invite_url" ricevuta dal server.
automated_claim_url	stringa (facoltativo)	URL di registrazione (obbligatorio per la risposta "getClaimToken", omesso per "start", "complete", "cancel"). Per le stampanti cloud deve essere l'"automated_invite_url" ricevuta dal server.
device_id	stringa (facoltativo)	Nuovo ID dispositivo (omesso per la risposta "start", obbligatorio per "complete").

Il dispositivo DEVE restituire il proprio ID dispositivo nella risposta dell'API /privet/info SOLO dopo il completamento 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 può restituire i seguenti errori (vedi la sezione Errori per i dettagli):

Errore	Descrizione
device_busy	Il dispositivo è occupato e non può eseguire l'azione richiesta. Riprova dopo il timeout.
pending_user_action	In risposta a "getClaimToken", questo errore indica che il dispositivo è ancora in attesa di conferma da parte dell'utente e che la richiesta "getClaimToken" deve essere ritentata dopo il timeout.
user_cancel	L'utente ha annullato esplicitamente la procedura di registrazione dal dispositivo.
confirmation_timeout	Il tempo per la conferma dell'utente scade.
invalid_action	Viene chiamata un'azione non valida. Ad esempio, se il client ha chiamato action=complete prima di chiamare action=start e action=getClaimToken.
invalid_params	Parametri non validi specificati nella richiesta. (I parametri sconosciuti devono essere ignorati in modo sicuro per la compatibilità futura). Ad esempio, restituisci questo valore se il client ha chiamato action=unknown o user=.
device_config_error	Data/ora (o altre impostazioni) errate sul dispositivo. L'utente deve andare (al sito web interno del dispositivo) e configurare le impostazioni del dispositivo.
offline	Il dispositivo è attualmente offline e non può comunicare con il server.
server_error	Errore del server durante la procedura di registrazione.
invalid_x_privet_token	X-Privet-Token non è valido o è vuoto nella richiesta.

Il dispositivo DEVE interrompere l'esposizione dell'API /privet/register dopo il completamento 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 l'intestazione X-Privet-Token non è presente, il dispositivo DEVE restituire l'errore HTTP 400.

4.4. API /privet/accesstoken

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

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 restituirlo al client. Il client utilizzerà quindi il token di accesso per accedere a questo dispositivo tramite il cloud.

I dispositivi Cloud Print DEVONO chiamare la seguente API:

/cloudprint/proximitytoken

e trasmetti i parametri "printerid=<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 trasmettere 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. Può essere vuoto nella richiesta.

4.4.2. Indietro

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

Nome valore	Tipo di valore	Descrizione
token	stringa	Token di accesso restituito dal server
utente	stringa	Lo stesso utente del parametro di input.
expires_in	int	Numero di secondi fino 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 i dettagli, consulta la sezione Errori):

Errore	Descrizione
offline	Il dispositivo è attualmente offline e non può comunicare con il server.
access_denied	Diritti insufficienti. Accesso negato. Il dispositivo deve restituire questo errore quando la richiesta è stata esplicitamente rifiutata dal server.
invalid_params	Parametri non validi specificati nella richiesta. (I parametri sconosciuti devono essere ignorati in modo sicuro per la compatibilità futura). Ad esempio, se il client ha chiamato /accesstoken?user= o /accesstoken.
server_error	Errore del server.
invalid_x_privet_token	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 l'intestazione X-Privet-Token non è presente, il dispositivo DEVE restituire l'errore HTTP 400.

4.5. API /privet/capabilities

L'API /privet/capabilities è FACOLTATIVA. Si tratta di una richiesta HTTP GET. L'API /privet/capabilities DEVE controllare la presenza di un'intestazione "X-Privet-Token" valida. Il dispositivo DEVE implementare questa API sull'URL "/privet/capabilities":

GET /privet/capabilities HTTP/1.1

Quando il dispositivo riceve la chiamata API /capabilities, se è in grado, DEVE contattare il server per ottenere le funzionalità aggiornate. Ad esempio, se una stampante supporta la pubblicazione di un lavoro di stampa (ricevuto localmente) su se stessa tramite il servizio Cloud Print, deve restituire le funzionalità 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 lavoro alla stampante. Il caso più comune è un elenco di tipi di documenti supportati. Se la stampante è offline, dovrebbe restituire i tipi di documenti che supporta. 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 "image/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 deve restituire le funzionalità per l'utilizzo offline (se sono diverse da quelle "online").

4.5.2. Indietro

L'API /privet/capabilities restituisce le funzionalità del dispositivo nel formato JSON Cloud Device Description (CDD) (consulta il documento CDD per i dettagli). Le stampanti DEVONO restituire almeno un elenco di tipi supportati qui. Ad esempio, una stampante cloud attualmente online potrebbe restituire un risultato simile a questo (come minimo):

{
        "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 quando è disconnesso 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 precedenti, la stampante specifica che preferisce i dati "application/pdf" a "image/pwg-raster" e "image/jpeg". Se possibile, i client devono rispettare la priorità della stampante (per i dettagli, consulta il documento CDD).

4.5.3. Errori

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

Errore	Descrizione
invalid_x_privet_token	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 l'intestazione X-Privet-Token non è presente, il dispositivo DEVE restituire l'errore HTTP 400.

4.6. Errori

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

Nome valore	Tipo di valore	Descrizione
errore	stringa	Tipo di errore (definito per API)
descrizione	stringa (facoltativo)	Descrizione dell'errore leggibile.
server_api	stringa (facoltativo)	In caso di errore del server, questo campo contiene l'API server che non è riuscita.
server_code	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 di attesa del client prima di riprovare (solo per errori recuperabili). Il client DEVE randomizzare il timeout effettivo da questo valore a un valore pari al +20%.

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

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

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 dispositivo supportati da questo protocollo è la stampante. I dispositivi che supportano questo tipo POSSONO implementare alcune funzionalità specifiche per le stampanti. Idealmente, la stampa su stampanti cloud avviene tramite un server Cloud Print:

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

Poiché il servizio Cloud Print implementa la conversione, la stampante DEVE pubblicizzare il supporto di 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 è preferibile una soluzione completamente offline. Poiché le stampanti supportano un numero limitato di formati di input, un client dovrà convertire i documenti in alcuni formati supportati nativamente dalla stampante.

Questa specifica RICHIEDE che tutte le stampanti supportino almeno il formato PWG Raster ("image/pwg-raster") per la stampa offline. Una stampante potrebbe supportare altri formati (ad esempio JPEG) e, se un client lo 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 un client può avviare la stampa sulla rete locale.

Stampa semplice: il client invia il documento tramite la rete locale all'API /submitdoc (senza specificare il parametro job_id). Il documento inviato verrà stampato utilizzando le impostazioni predefinite del ticket di stampa e non sono necessari stati del processo 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 client 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 memorizzare il ticket di stampa e restituire un job_id al client. Il client chiamerà l'API /printer/submitdoc e specificherà l'job_id ricevuto in precedenza. A quel punto la stampante inizierà a stampare. Il client eseguirà il polling della stampante per lo stato del processo di stampa chiamando l'API /privet/printer/jobstate.

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

/createjob prende il primo posto disponibile nella coda.
La durata del job (nella coda) è di almeno 5 minuti.
Se tutti gli spazi della coda sono occupati, il processo di stampa più vecchio e non ancora stampato verrà rimosso e sostituito con uno nuovo.
Se sul dispositivo è in corso un processo di stampa (semplice o avanzata), /submitdoc deve restituire lo stato occupato e proporre un timeout per riprovare a stampare il documento.
Se /submitdoc fa riferimento a un job rimosso dalla coda (a causa di sostituzione o timeout), la stampante deve restituire un errore invalid_print_job e il client riproverà la procedura dal passaggio /createjob. Il client DEVE attendere un periodo di timeout casuale fino a 5 secondi prima di riprovare.

Se i vincoli di memoria impediscono l'archiviazione di più job in attesa sul dispositivo, è possibile avere una coda di un solo job di stampa. Dovrebbe comunque seguire lo stesso protocollo indicato sopra. Dopo che un job è stato completato o non è riuscito con un errore, la stampante deve memorizzare le informazioni sullo stato del job per almeno 5 minuti. La dimensione della coda per l'archiviazione degli stati dei job completati deve essere almeno 10. Se sono presenti più stati del job da archiviare, quello meno recente potrebbe essere rimosso dalla coda prima del timeout di 5 minuti.

Nota:per il momento i client eseguiranno il polling dello stato del job. In futuro, potremmo richiedere alla stampante di inviare una notifica DNS TXT quando lo stato di QUALSIASI processo di stampa è cambiato.

5.1. API /privet/printer/createjob

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

POST /privet/printer/createjob HTTP/1.1

Quando riceve 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 in formato CJT.

5.1.2. Indietro

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

Nome valore	Tipo di valore	Descrizione
job_id	stringa	ID del nuovo processo di stampa creato.
expires_in	int	Numero di secondi di validità di questo lavoro di stampa.

Esempio:

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

5.1.3. Errori

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

Errore	Descrizione
invalid_ticket	Il ticket di stampa inviato non è valido.
printer_busy	La stampante è occupata e al momento non può elaborare /creare il lavoro. Riprova dopo il timeout.
printer_error	La stampante è in stato di errore e richiede l'interazione dell'utente per essere riparata. La descrizione deve contenere una spiegazione più dettagliata (ad es. "Inceppamento carta nel vassoio 1").
invalid_x_privet_token	X-Privet-Token non è valido o è vuoto nella richiesta.

Se il dispositivo non espone /privet/printer/createjob, DEVE restituire l'errore HTTP 404. Se l'intestazione X-Privet-Token non è presente, 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 invio a Cloud Print). Si tratta di una richiesta POST HTTP. L'API /privet/printer/submitdoc DEVE verificare la presenza di un'intestazione "X-Privet-Token" valida. Il dispositivo DEVE implementare questa API sull'URL "/privet/printer/submitdoc":

POST /privet/printer/submitdoc HTTP/1.1

Quando riceve la chiamata API /privet/printer/submitdoc, la stampante deve iniziare a stampare. Se non è in grado di iniziare la stampa, DEVE restituire l'errore printer_busy e un periodo di timeout consigliato che il client deve attendere prima di riprovare.

Se la stampante non è in grado di contenere tutti i dati nel buffer interno, DEVE utilizzare i meccanismi TCP per rallentare il trasferimento dei dati finché non stampa una parte del documento, rendendo nuovamente disponibile una parte del buffer. Ad esempio, la stampante potrebbe impostare windowsize=0 sui livelli TCP, il che farà attendere il client.

L'invio di un documento alla stampante potrebbe richiedere molto tempo. Il client deve essere in grado di controllare lo stato della stampante e del processo (stampa avanzata) durante 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 che tutti i client inizino 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 lo stato della stampante e del lavoro.

Nota: al termine o all'interruzione del job di stampa locale, è vivamente consigliato (e sarà obbligatorio in una versione futura di questa specifica) segnalare lo stato finale del job all'interfaccia /cloudprint/submit per scopi di contabilità ed esperienza utente. I parametri "printerid", "title", "contentType" e "final_semantic_state" (in formato PrintJobState) sono obbligatori, mentre i parametri "tag" (parametro ripetuto) e "ticket" (il ticket del lavoro in formato CloudJobTicket). Tieni presente che PrintJobState fornito deve essere effettivamente finale, ovvero il suo tipo deve essere DONE o ABORTED e deve essere fornita una causa nel caso in cui sia ABORTED (vedi JobState per i dettagli). Tieni presente inoltre che questo utilizzo dell'interfaccia /cloudprint/submit per segnalare i lavori di stampa locali non è menzionato nella relativa specifica perché questa sezione ha lo scopo di descrivere l'utilizzo principale dell'interfaccia: l'invio di un lavoro 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 lavoro di stampa. Può essere omesso per la stampa semplice (vedi sopra). Deve corrispondere a quello restituito dalla stampante.
user_name	(facoltativo) Nome utente leggibile. Questa non è definitiva e deve essere utilizzata solo per le annotazioni dei processi di stampa. Se il lavoro viene ripubblicato nel servizio Cloud Print, questa stringa deve essere allegata al lavoro Cloud Print.
client_name	(facoltativo) Nome dell'applicazione client che effettua questa richiesta. Solo per la visualizzazione. Se il lavoro viene ripubblicato nel servizio Cloud Print, questa stringa deve essere allegata al lavoro Cloud Print.
job_name	(facoltativo) Nome del processo di stampa da registrare. Se il lavoro viene ripubblicato nel servizio Cloud Print, questa stringa deve essere allegata al lavoro Cloud Print.
offline	(facoltativo) Può essere solo "offline=1". In questo caso, la stampante deve tentare la stampa offline (nessun nuovo invio al server Cloud Print).

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

È VIVAMENTE consigliato ai clienti di fornire un nome utente (o email) valido, un nome cliente e un nome lavoro con questa richiesta. Questi campi vengono utilizzati solo nelle UI per migliorare l'esperienza utente.

5.2.2. Indietro

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

Nome valore	Tipo di valore	Descrizione
job_id	stringa	ID del processo di stampa appena creato (stampa semplice) o job_id specificato nella richiesta (stampa avanzata).
expires_in	int	Numero di secondi di validità di questo lavoro di stampa.
job_type	stringa	Il tipo di contenuti del documento inviato.
job_size	int 64 bit	Dimensioni dei dati di stampa in byte.
job_name	stringa	(facoltativo) Stesso nome del job dell'input (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 (per i dettagli, consulta la sezione Errori):

Errore	Descrizione
invalid_print_job	Nella richiesta è specificato un ID job non valido/scaduto. Riprova dopo il timeout.
invalid_document_type	Il tipo MIME del documento non è supportato dalla stampante.
invalid_document	Il documento inviato non è valido.
document_too_large	Il documento supera le dimensioni massime consentite.
printer_busy	La stampante è occupata e al momento non può elaborare il documento. Riprova dopo il timeout.
printer_error	La stampante è in stato di errore e richiede l'interazione dell'utente per essere riparata. La descrizione deve contenere una spiegazione più dettagliata (ad es. "Inceppamento carta nel vassoio 1").
invalid_params	Parametri non validi specificati nella richiesta. (I parametri sconosciuti devono essere ignorati in modo sicuro per la compatibilità futura)
user_cancel	L'utente ha annullato esplicitamente il processo di stampa dal dispositivo.
server_error	L'invio del documento a Cloud Print non è riuscito.
invalid_x_privet_token	X-Privet-Token non è valido o è vuoto nella richiesta.

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

Nota: l'API /privet/printer/submitdoc potrebbe richiedere una gestione speciale sul lato stampante (a causa del payload di grandi dimensioni allegato). In alcuni casi (a seconda dell'implementazione e della piattaforma del server HTTP della stampante), 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 DEVONO cercare il più possibile di restituire Privet. Tuttavia, ogni client che implementa la specifica Privet DOVREBBE 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 DOVREBBE gestirlo come un errore privato "printer_busy" con "timeout" impostato su 15 secondi. Per evitare tentativi infiniti, il client potrebbe interrompere i tentativi dopo un numero ragionevole di tentativi (ad esempio, 3).

5.3. API /privet/printer/jobstate

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

GET /privet/printer/jobstate HTTP/1.1

Quando riceve una chiamata API /privet/printer/jobstate, una stampante deve restituire lo stato del processo di stampa richiesto o l'errore invalid_print_job.

5.3.1. Input

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

Nome	Valore
job_id	ID del job di stampa per cui restituire lo stato.

5.3.2. Indietro

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

Nome valore	Tipo di valore	Descrizione
job_id	stringa	ID processo di stampa per cui sono disponibili le informazioni sullo stato.
stato	stringa	bozza: il processo di stampa è stato creato sul dispositivo (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. interrotto: il processo di stampa è stato messo in pausa, ma può essere riavviato manualmente o automaticamente. done: il processo di stampa è stato completato. interrotto: il processo di stampa non è riuscito.
descrizione	stringa	(facoltativo) Descrizione leggibile dello stato del processo di stampa. Devono includere informazioni aggiuntive se lo stato è interrotto o interrotto. Il campo semantic_state in genere fornisce una descrizione migliore e più significativa al client.
expires_in	int	Numero di secondi di validità di questo lavoro di stampa.
job_type	stringa	(facoltativo) Tipo di contenuti del documento inviato.
job_size	int 64 bit	(facoltativo) Dimensioni dei dati di stampa in byte.
job_name	stringa	(facoltativo) Stesso nome del job dell'input (se presente).
server_job_id	stringa	(facoltativo) ID del job restituito dal server (se il job è stato pubblicato nel servizio Cloud Print). Omesso per la stampa offline.
semantic_state	JSON	(facoltativo) Stato semantico del lavoro nel formato PrintJobState.

Esempio (stampa tramite 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 perché la carta è terminata. Nota 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 può restituire i seguenti errori (per i dettagli, consulta la sezione Errori):

Errore	Descrizione
invalid_print_job	Nella richiesta è specificato un ID job non valido/scaduto.
server_error	Recupero dello stato del processo di stampa (per i processi di stampa pubblicati su Cloud Print) non riuscito.
invalid_x_privet_token	X-Privet-Token non è valido o è vuoto nella richiesta.

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

6. Appendice

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 es. /privet/accesstoken, stampa locale) devono essere disattivate.
La registrazione richiede l'interazione fisica con un dispositivo.

L'utente DEVE eseguire un'azione fisica sul dispositivo (ad es. premere un pulsante) per confermare il proprio accesso al dispositivo.
Dopo che l'utente ha eseguito l'azione indicata sopra, la stampante deve inviare la richiesta /cloudprint/register. Non deve inviare questa richiesta finché non viene eseguita l'azione (vedi il diagramma di sequenza 1).
Se il dispositivo sta elaborando una richiesta /privet/register (ad esempio, è in attesa dell'azione sopra), deve rifiutare tutte le altre richieste /privet/register. In questo caso, il dispositivo DEVE restituire l'errore device_busy.
Il dispositivo deve andare in timeout per qualsiasi richiesta /register che non riceve l'azione fisica menzionata sopra entro 60 secondi. In questo caso, il dispositivo DEVE restituire l'errore confirmation_timeout.
Facoltativo: consigliato ma non obbligatorio, quanto segue può migliorare l'esperienza utente:

La stampante potrebbe lampeggiare o il suo schermo potrebbe indicare che l'utente deve intraprendere un'azione per confermare la registrazione.
Sullo schermo della stampante potrebbe essere visualizzato il messaggio "Registrazione in corso su Google Cloud Print per l'utente "abc@def.com" - premi OK per continuare", dove abc@def.com è il parametro utente della chiamata API /register. In questo modo, per un utente sarà più chiaro che:

si tratta della richiesta di registrazione che sta confermando
cosa sta succedendo se non ha attivato la richiesta.

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

Trasferimenti di proprietà:

Il dispositivo potrebbe essere eliminato esplicitamente dal servizio cloud.

Se il dispositivo riceve una risposta positiva, ma nessuna descrizione del dispositivo a seguito della chiamata /cloudprint/printer (per GCP), DEVE tornare alla modalità predefinita (pronta all'uso).
Se le credenziali del dispositivo non funzionano più (esplicitamente a causa della risposta "credenziali non valide" del server), DEVE tornare alla modalità predefinita (pronta all'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 impostare la modalità predefinita.

I dispositivi che supportano le notifiche XMPP DEVONO includere la possibilità di eseguire il ping del server. Il timeout del ping DEVE essere controllabile dal server tramite "local_settings".
Il dispositivo potrebbe eseguire il ping del server in modo esplicito (API /cloudprint/printer per GCP, oltre ai ping XMPP) non più di una volta al giorno (24 ore) per assicurarsi che sia sincronizzato. È consigliabile randomizzare la finestra di controllo entro 24-32 ore.
(Facoltativo) Per i dispositivi Cloud Print, è consigliabile, ma non obbligatorio, disporre di un modo manuale (pulsante) per consentire all'utente di avviare un controllo di nuovi processi di stampa dal dispositivo. Alcune stampanti hanno già questa funzionalità.
(Facoltativo) Le stampanti aziendali potrebbero avere un'opzione per disattivare completamente la ricerca locale. In questo caso, il dispositivo DEVE aggiornare queste impostazioni locali sul server. Le nuove impostazioni locali DEVONO essere vuote (l'impostazione "local_discovery" su "false" significa che possono essere riattivate dal servizio GCP).

6.1.2 Diagramma di registrazione predefinito

6.2. Attacchi XSSI e XSRF e prevenzione

Questa sezione spiegherà la possibilità di attacchi XSSI e XSRF sul dispositivo e come proteggersi da questi (incluse le tecniche di generazione dei token).
Per ulteriori dettagli, visita la pagina: http://googleonlinesecurity.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. Sebbene Google non utilizzi cookie con il servizio Cloud Print, questi attacchi sono comunque possibili. L'accesso alla rete locale, per sua natura, considera implicitamente attendibili le richieste.

6.2.1. XSSI

È possibile che un sito web dannoso indovini l'indirizzo IP e il numero di porta di un dispositivo compatibile con Privet e tenti di chiamare l'API Privet utilizzando "src=<nome API>" all'interno di un tag <script>:

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

Senza protezione, i siti web dannosi sarebbero in grado di eseguire chiamate API e accedere ai risultati.
Per impedire questo tipo di attacco, TUTTE le chiamate API Privet DEVONO richiedere l'intestazione "X-Privet-Token" nella richiesta. I tag script "src=<api>" non sono in grado di aggiungere intestazioni, proteggendo efficacemente da questo tipo di attacco.

6.2.2. XSRF

http://en.wikipedia.org/wiki/Cross-site_request_forgery
È possibile che un sito web dannoso indovini l'indirizzo IP e il numero di porta di un dispositivo compatibile con Privet e tenti di chiamare l'API Privet utilizzando un <iframe>, moduli o un altro meccanismo di caricamento cross-site. Gli autori degli attacchi non sarebbero in grado di accedere ai risultati della richiesta, ma se la richiesta eseguisse un'azione (ad es. la stampa), potrebbero attivarla.

Per prevenire questo attacco, richiediamo la seguente protezione:

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

Anche se un malintenzionato è in grado di eseguire l'API /privet/info, non sarebbe in grado di leggere x-privet-token dalla risposta e quindi non sarebbe 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 del token XSRF:

DELIMITER è un carattere speciale, di solito ":"
issue_timecounter è un numero di secondi trascorsi da un evento (epoca per il timestamp) o dall'ora di avvio del dispositivo (per i contatori della CPU). issue_timecounter aumenta costantemente quando il dispositivo è in funzione (vedi la verifica del token di seguito).
SHA1: funzione hash che utilizza l'algoritmo SHA1
base64: codifica Base64
device_secret: segreto specifico del dispositivo. Il secret del dispositivo DEVE essere aggiornato a ogni riavvio.

Modi consigliati per generare il segreto del dispositivo:

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

Il dispositivo non è tenuto a memorizzare tutti i token XSRF che ha emesso. Quando il dispositivo deve verificare la validità di un token XSRF, deve decodificarlo in base64. Recupera issue_timecounter dalla seconda metà (testo non crittografato) e prova a generare l'hash SHA1 di device_secret + DELIMITER + issue_timecounter, dove issue_timecounter proviene dal token. Se l'SHA1 appena generato corrisponde a quello nel token, il dispositivo deve ora controllare se il issue_timecounter rientra nel periodo di validità (24 ore) del contatore dell'ora corrente. A questo scopo, il dispositivo prende il contatore del tempo corrente (ad esempio il contatore della CPU) e sottrae issue_timecounter. Il risultato DEVE essere il numero di secondi dall'emissione del token.

Importante:questo è il modo consigliato per implementare la protezione XSRF. I client della specifica Privet non devono tentare di comprendere il token XSRF, ma devono trattarlo come una scatola nera. La Figura 6.2.3 illustra un modo consigliato per implementare X-Privet-Token e la verifica di una richiesta tipica.

6.2.3 Diagramma di sequenza di generazione e verifica del token X-Privet

6.3. Diagrammi di workflow

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

6.3.1. Workflow della stampante pronto all'uso

6.3.2. Avvio della stampante registrato

6.3.3 Flusso di lavoro di gestione delle notifiche XMPP

6.3.4. Controllare il flusso di lavoro delle impostazioni della stampante

Privet Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

1. Introduzione

2. Discovery

2.1. Tipo di servizio

2.2. Record TXT

2.2.1. txtvers

2.2.2. ty

2.2.3. Nota (facoltativa)

2.2.4. url

2.2.5. type

2.2.6. id

2.2.7. cs

3. Annunci

3.1. Avvio

3.2. Arresto

3.3 Aggiorna

4. API

4.1. Disponibilità API

4.1.1. Registrazione

4.1.2. Avvio

4.1.3. Aggiorna

4.1.3.1. Impostazioni locali in attesa

4.1.3.2. Impostazioni locali attuali

4.1.4. Offline

4.1.5. Eliminazione del dispositivo dal servizio

4.2. API /privet/info

4.2.1. Input

4.2.2. Indietro

4.2.3. Errori

4.3. /privet/register API

4.3.1. Input

4.3.2. Indietro

4.3.3. Errori

4.4. API /privet/accesstoken

4.4.1. Input

4.4.2. Indietro

4.4.3. Errori

4.5. API /privet/capabilities

4.5.1. Input

4.5.2. Indietro

4.5.3. Errori

4.6. Errori

5. API Printer

5.1. API /privet/printer/createjob

5.1.1. Input

5.1.2. Indietro

5.1.3. Errori

5.2. API /privet/printer/submitdoc

5.2.1. Input

5.2.2. Indietro

5.2.3. Errori

5.3. API /privet/printer/jobstate

5.3.1. Input

5.3.2. Indietro

5.3.3. Errori

6. Appendice

6.1. Comportamento e impostazioni predefiniti

6.1.2 Diagramma di registrazione predefinito

6.2. Attacchi XSSI e XSRF e prevenzione

6.2.1. XSSI

6.2.2. XSRF

6.2.3 Diagramma di sequenza di generazione e verifica del token X-Privet

6.3. Diagrammi di workflow

6.3.1. Workflow della stampante pronto all'uso

6.3.2. Avvio della stampante registrato

6.3.3 Flusso di lavoro di gestione delle notifiche XMPP

6.3.4. Controllare il flusso di lavoro delle impostazioni della stampante

Privet