Google Cloud Print wird ab dem 31. Dezember 2020 nicht mehr unterstützt. Informationen zur Migration finden Sie in diesem Hilfeartikel.

Diese Seite wurde von der Cloud Translation API übersetzt.

Liguster

Privet ist eine Cloud Device Local Discovery API, die von Cloud-Diensten verwendet wird. Dieses Dokument ist in die folgenden Abschnitte unterteilt:

Einführung: Einführung in Privet
Discovery: Lokale Discovery-Mechanismen
Ankündigungen: Ankündigungen für die lokale Suche
API: Private APIs für allgemeine Cloud-Geräte
Printer API: Privet-APIs, die von Druckern verwendet werden
Anhang: Zusätzliche Diagramme

1. Einführung

Cloudbasierte Geräte haben viele Vorteile. Sie können Online-Konvertierungsdienste nutzen, Jobwarteschlangen hosten, während das Gerät offline ist, und von überall auf der Welt darauf zugreifen. Da ein Nutzer jedoch auf viele Cloud-Geräte zugreifen kann, benötigen wir eine Methode, um das nächstgelegene Gerät anhand des Standorts zu finden. Das Privet-Protokoll soll die Flexibilität von Cloud-Geräten mit einem geeigneten lokalen Erkennungsmechanismus verbinden, damit Geräte in neuen Umgebungen leicht erkannt werden können.

Die Ziele dieses Protokolls sind:

Cloud-Geräte lokal erkennbar machen
Cloud-Geräte bei einem Clouddienst registrieren
Registrierte Geräte mit ihrer Cloud-Darstellung verknüpfen
Offlinefunktionen aktivieren
die Implementierung zu vereinfachen, damit sie auch auf kleinen Geräten genutzt werden kann

Das Privet-Protokoll besteht aus zwei Hauptteilen: Erkennung und API. Die Erkennung wird verwendet, um das Gerät im lokalen Netzwerk zu finden. Die API wird verwendet, um Informationen zum Gerät abzurufen und einige Aktionen auszuführen. In diesem Dokument bezieht sich das Gerät auf ein mit der Cloud verbundenes Gerät, das das Privet-Protokoll implementiert.

2. Discovery

Die Geräteerkennung basiert auf dem Zeroconf-Protokoll (mDNS + DNS-SD). Das Gerät MUSS die lokale IPv4-Link-Adressierung implementieren. Das Gerät MUSS den mDNS- und DNS-SD-Spezifikationen entsprechen.

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)

Das Gerät MUSS Namenskonflikte gemäß den oben genannten Spezifikationen auflösen.

2.1. Diensttyp

Die DNS-Dienstermittlung verwendet das folgende Format für Diensttypen: _applicationprotocol._transportprotocol. Im Fall des Privet-Protokolls sollte der Diensttyp für DNS-SD _privet._tcp sein.

Das Gerät kann auch andere Diensttypen implementieren. Es wird empfohlen, für alle vom Gerät implementierten Diensttypen denselben Dienstinstanznamen zu verwenden. Ein Drucker kann beispielsweise die Dienste „Printer XYZ._privet._tcp“ und „Printer XYZ._printer._tcp“ implementieren. Dadurch wird die Einrichtung für den Nutzer vereinfacht. Privet-Clients suchen jedoch nur nach „_privet._tcp“.

Zusätzlich zum Hauptdiensttyp MUSS das Gerät die PTR-Einträge für die entsprechenden Subtypen ankündigen (siehe DNS-SD-Spezifikation: „7.1. Selektive Instanzaufzählung (Untertypen)“). Das Format sollte so aussehen: _<subtype>._sub._privet._tcp

Derzeit wird nur der Gerätetyp printer unterstützt. Alle Drucker MÜSSEN also zwei PTR-Einträge ankündigen:

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

2.2. TXT‑Eintrag

DNS Service Discovery definiert Felder, mit denen optionale Informationen zu einem Dienst in den TXT-Einträgen hinzugefügt werden können. Ein TXT-Eintrag besteht aus Schlüssel/Wert-Paaren. Jedes Schlüssel/Wert-Paar beginnt mit dem Längenbyte, gefolgt von bis zu 255 Byte Text. Der Schlüssel ist der Text vor dem ersten Gleichheitszeichen (=) und der Wert ist der Text nach dem ersten Gleichheitszeichen (=) bis zum Ende. Die Spezifikation lässt keinen Wert im Datensatz zu. In diesem Fall gibt es kein „=“-Zeichen ODER keinen Text nach dem „=“-Zeichen. (Siehe DNS-SD-Spezifikation: „6.1. Allgemeine Formatierungsregeln für DNS-TXT-Einträge“ für das Format von DNS-TXT-Einträgen und „6.2. DNS-SD-TXT-Eintrag – Größe des Eintrags“ für die empfohlene Länge).

Für Privet muss das Gerät die folgenden Schlüssel/Wert-Paare im TXT-Eintrag senden. Bei Schlüssel/Wert-Strings wird die Groß-/Kleinschreibung nicht berücksichtigt. „CS=online“ und „cs=ONLINE“ sind beispielsweise identisch. Die Informationen im TXT-Eintrag MÜSSEN mit den Informationen übereinstimmen, die über die /info-API zugänglich sind (siehe 4.1). API-Abschnitt).

Wir empfehlen, die Größe von TXT-Einträgen auf unter 512 Byte zu beschränken.

2.2.1. txtvers

Version der TXT-Struktur. „txtvers“ MUSS der erste Eintrag der TXT-Struktur sein. Derzeit wird nur Version 1 unterstützt.

txtvers=1

2.2.2. ty

Stellt einen für Nutzer lesbaren Namen des Geräts bereit. Beispiel:

ty=Google Cloud Ready Printer Model XYZ

2.2.3. note (optional)

Stellt einen für Nutzer lesbaren Namen des Geräts bereit. Beispiel:

note=1st floor lobby printer

Hinweis:Dies ist ein optionaler Schlüssel, der übersprungen werden kann. Falls vorhanden, SOLLTE der Nutzer diesen Wert jedoch ändern können. Bei der Registrierung des Geräts MUSS dieselbe Beschreibung verwendet werden.

2.2.4. url

Server-URL, mit der dieses Gerät verbunden ist (einschließlich Protokoll). Beispiel:

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

2.2.5. type

Durch Kommas getrennte Liste der von diesem Gerät unterstützten Geräteuntertypen. Das Format ist: „type=_subtype1,_subtype2“. Derzeit ist printer der einzige unterstützte Gerätetyp.

type=printer

Für jeden aufgeführten Subtyp sollte ein entsprechender PTR-Eintrag vorhanden sein. Für jeden unterstützten Dienstuntertyp sollte es ein entsprechendes Element geben. Der Name des Dienstuntertyps (<subtype>._sub._privet._tcp) sollte hier dem Gerätetyp entsprechen.

2.2.6. id

Geräte-ID Wenn das Gerät noch nicht registriert wurde, sollte dieser Schlüssel vorhanden sein, der Wert sollte jedoch leer sein. Beispiel:

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

2.2.7. cs

Gibt den aktuellen Verbindungsstatus des Geräts an. In dieser Spezifikation sind vier mögliche Werte definiert.

„Online“ bedeutet, dass das Gerät derzeit mit der Cloud verbunden ist.
„Offline“ bedeutet, dass das Gerät im lokalen Netzwerk verfügbar ist, aber nicht mit dem Server kommunizieren kann.
„Wird verbunden“ bedeutet, dass das Gerät gerade hochfährt und noch nicht vollständig online ist.
„not-configured“ (nicht konfiguriert) gibt an, dass der Internetzugriff des Geräts noch nicht konfiguriert wurde. Dieser Wert wird derzeit nicht verwendet, kann aber in zukünftigen Versionen der Spezifikation nützlich sein.

Beispiel:

cs=online
cs=offline
cs=connecting

Wenn das Gerät bei einer Cloud registriert wurde, sollte es beim Start die Verbindung zu einem Server prüfen, um den Verbindungsstatus zu ermitteln (z. B. durch Aufrufen der Cloud-API, um Geräteeinstellungen abzurufen). Das Gerät kann den Verbindungsstatus seines Benachrichtigungskanals (z.B. XMPP) verwenden, um diesen Wert zu melden. Nicht registrierte Geräte pingen beim Start möglicherweise eine Domain an, um den Verbindungsstatus zu ermitteln (z. B. www.google.com für Cloud Print-Geräte).

3. Ankündigungen

Beim Starten, Herunterfahren oder Ändern des Status des Geräts MUSS das Gerät den Ankündigungsschritt gemäß der mDNS-Spezifikation ausführen. Die entsprechende Ankündigung SOLLTE mindestens zweimal mit einem Intervall von mindestens einer Sekunde zwischen den einzelnen Ankündigungen gesendet werden.

3.1. Starten

Beim Start des Geräts MUSS es die in der mDNS-Spezifikation beschriebenen Schritte zum Erkennen und Ankündigen ausführen. In diesem Fall sollten SRV-, PTR- und TXT-Einträge gesendet werden. Es wird empfohlen, alle Einträge nach Möglichkeit in einer DNS-Antwort zu gruppieren. Andernfalls wird die folgende Reihenfolge empfohlen: SRV-, PTR- und TXT-Einträge.

3.2 Herunterfahren

Beim Herunterfahren des Geräts SOLLTE versucht werden, alle Interessenten darüber zu informieren, indem ein „Goodbye-Paket“ mit TTL=0 gesendet wird (wie in der mDNS-Dokumentation beschrieben).

3.3 Aktualisieren

Wenn sich Informationen im TXT-Eintrag geändert haben, MUSS das Gerät eine Aktualisierung senden. In diesem Fall reicht es aus, nur den neuen TXT-Eintrag zu senden. Nach der Registrierung eines Geräts MUSS beispielsweise eine Aktualisierungsankündigung mit der neuen Geräte-ID gesendet werden.

4. API

Nachdem ein Cloud-Gerät erkannt wurde, wird die Clientkommunikation mit dem Gerät direkt über das lokale Netzwerk aktiviert. Alle APIs basieren auf HTTP 1.1. Die Datenformate basieren auf JSON. API-Anfragen können GET- oder POST-Anfragen sein.

Jede Anfrage MUSS einen gültigen X-Privet-Token-Header enthalten. Die EINZIGE Anfrage, die einen leeren „X-Privet-Token“-Header haben darf, ist die /privet/info-Anfrage. Der Header MUSS jedoch vorhanden sein. Wenn der Header „X-Privet-Token“ fehlt, MUSS das Gerät mit dem folgenden HTTP-400-Fehler antworten:

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

Wenn der Header „X-Privet-Token“ leer oder ungültig ist, MUSS das Gerät mit dem Fehler „invalid X-Privet-Token“ (invalid_x_privet_token, siehe Abschnitt „Fehler“ für Details) antworten. Die einzige Ausnahme ist die /info-API. Weitere Informationen dazu, warum dies geschieht und wie Tokens generiert werden sollten, finden Sie in Anhang A: XSSI- und XSRF-Angriffe und ‑Prävention.

Wenn eine angeforderte API nicht vorhanden oder nicht unterstützt wird, MUSS das Gerät einen HTTP 404-Fehler zurückgeben.

4.1. API-Verfügbarkeit

Bevor eine API verfügbar gemacht wird (einschließlich der /info-API), MUSS das Gerät den Server kontaktieren, um die lokalen Einstellungen zu prüfen. Lokale Einstellungen MÜSSEN zwischen Neustarts beibehalten werden. Wenn der Server nicht verfügbar ist, sollten die letzten bekannten lokalen Einstellungen verwendet werden. Wenn das Gerät noch nicht registriert wurde, sollten die Standardeinstellungen gelten.

Cloud Print-Geräte MÜSSEN die folgenden Schritte ausführen, um sich zu registrieren, lokale Einstellungen zu empfangen und zu aktualisieren.

4.1.1. Anmeldung

Wenn sich das Gerät registriert, MUSS der Parameter „local_settings“ wie folgt angegeben werden:

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

Die folgenden Einstellungen können festgelegt werden:

Wertname	Werttyp	Beschreibung
local_discovery	boolean	Gibt an, ob die Funktion zur lokalen Suche zulässig ist. Wenn „false“, müssen alle lokalen APIs (einschließlich /info) und die DNS-SD-Erkennung deaktiviert werden. Standardmäßig sollte für neu registrierte Geräte „true“ zurückgegeben werden.
access_token_enabled	boolesch (optional)	Gibt an, ob die /accesstoken-API im lokalen Netzwerk verfügbar gemacht werden soll. Der Standardwert sollte „true“ sein.
printer/local_printing_enabled	boolesch (optional)	Gibt an, ob die Funktionen für lokales Drucken (/printer/createjob, /printer/submitdoc, /printer/jobstate) im lokalen Netzwerk verfügbar gemacht werden sollen. Der Standardwert sollte „true“ sein.
printer/conversion_printing_enabled	boolesch (optional)	Gibt an, ob beim lokalen Drucken ein Job zur Konvertierung an den Server gesendet werden darf. Ist nur sinnvoll, wenn der lokale Druck aktiviert ist.
xmpp_timeout_value	int (optional)	Gibt die Anzahl der Sekunden zwischen den Pings des XMPP-Kanals an. Der Standardwert MUSS mindestens 300 (5 Minuten) betragen.

Wichtig:Wenn kein optionaler Wert angegeben ist, wird die entsprechende Funktion vom Gerät nicht unterstützt.

4.1.2. Starten

Beim Start des Geräts sollte es den Server kontaktieren, um zu prüfen, welche APIs im lokalen Netzwerk verfügbar sind. Bei Druckern, die mit Cloud Print verbunden sind, sollte Folgendes aufgerufen werden:

/cloudprint/printer?printerid=<printer_id>

oder

/cloudprint/list

/cloudprint/printer wird gegenüber /cloudprint/list bevorzugt, aber beide funktionieren.

Diese API gibt aktuelle Geräteparameter zurück, einschließlich Einstellungen für die lokale API. Die Antwort des Servers hat das folgende Format:

"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
         }
}

Das Objekt „current“ gibt die Einstellungen an, die derzeit gelten.

Das Objekt „pending“ gibt Einstellungen an, die auf das Gerät angewendet werden sollen. Dieses Objekt ist möglicherweise nicht vorhanden.

Sobald das Gerät ausstehende Einstellungen sieht, MUSS es seinen Status aktualisieren (siehe unten).

4.1.3. Aktualisieren

Wenn eine Aktualisierung der Einstellungen erforderlich ist, wird eine XMPP-Benachrichtigung an das Gerät gesendet. Die Benachrichtigung hat folgendes Format:

<device_id>/update_settings

Nach Erhalt einer solchen Benachrichtigung MUSS das Gerät den Server abfragen, um die neuesten Einstellungen zu erhalten. Cloud Print-Geräte MÜSSEN Folgendes verwenden:

/cloudprint/printer?printerid=<printer_id>

Sobald das Gerät den Bereich „Ausstehend“ als Ergebnis der API „/cloudprint/printer“ (beim Start oder aufgrund der Benachrichtigung) sieht, MUSS es seinen internen Status aktualisieren, um sich die neuen Einstellungen zu merken. Es MUSS die Server-API aufrufen, um die neuen Einstellungen zu bestätigen. Bei Cloud-Druckern MUSS das Gerät die API „/cloudprint/update“ aufrufen und den Parameter „local_settings“ wie bei der Registrierung verwenden.

Beim erneuten Verbinden mit dem XMPP-Channel MUSS das Gerät die /cloudprint/printer-API aufrufen, um zu prüfen, ob sich die lokalen Einstellungen seit dem letzten Mal geändert haben.

4.1.3.1. Ausstehende lokale Einstellungen

Der Parameter „local_settings“, den das Gerät zum Aufrufen der Server-API verwendet, darf NIEMALS den Abschnitt „pending“ enthalten.

4.1.3.2. Aktuelle lokale Einstellungen

NUR das Gerät kann den Abschnitt „current“ der „local_settings“ ändern. Alle anderen ändern den Bereich „Ausstehend“ und warten, bis die Änderungen vom Gerät in den Bereich „Aktuell“ übertragen werden.

4.1.4. Offline

Wenn der Server beim Starten nicht kontaktiert werden kann, MUSS das Gerät nach der Benachrichtigung die zuletzt bekannten lokalen Einstellungen verwenden.

4.1.5. Gerät aus dem Dienst löschen

Wenn das Gerät aus dem Dienst (z. B. GCP) gelöscht wurde, wird eine XMPP-Benachrichtigung an das Gerät gesendet. Die Benachrichtigung hat folgendes Format:

<device_id>/delete

Nach Erhalt einer solchen Benachrichtigung MUSS das Gerät den Server aufrufen, um seinen Status zu prüfen. Cloud Print-Geräte MÜSSEN Folgendes verwenden:

/cloudprint/printer?printerid=<printer_id>

Das Gerät MUSS eine erfolgreiche HTTP-Antwort mit „success=false“ und ohne Geräte-/Druckerbeschreibung erhalten. Das Gerät wurde vom Server entfernt und MUSS seine Anmeldedaten löschen und in den Standardmodus für die Werkseinstellungen wechseln.

JEDES Mal, wenn das Gerät eine Antwort erhält, die darauf hinweist, dass es aufgrund der /cloudprint/printer API (Start, Benachrichtigung über aktualisierte Einstellungen, täglicher Ping) gelöscht wurde, MUSS es seine Anmeldedaten löschen und in den Standardmodus wechseln.

4.2. /privet/info API

Die Info API ist OBLIGATORISCH und MUSS von jedem Gerät implementiert werden. Es handelt sich um eine HTTP-GET-Anfrage für die URL „/privet/info“: GET /privet/info HTTP/1.1

Die Info API gibt grundlegende Informationen zu einem Gerät und den von ihm unterstützten Funktionen zurück. Diese API darf den Gerätestatus NIEMALS ändern oder eine Aktion ausführen, da sie anfällig für XSRF-Angriffe ist. Dies ist die EINZIGE API, für die ein leerer „X-Privet-Token“-Header zulässig ist. Clients sollten die /privet/info-API mit dem Header „X-Privet-Token“ aufrufen, der auf X-Privet-Token: „“ gesetzt ist.

Die Info API MUSS Daten zurückgeben, die mit den Daten im TXT-Eintrag während der Erkennung übereinstimmen.

4.2.1. Eingabe

Die /privet/info API hat keine Eingabeparameter.

4.2.2. Rückflug

Die API „/privet/info“ gibt grundlegende Informationen zum Gerät und zu den unterstützten Funktionen zurück.

In der Spalte „TXT“ wird das entsprechende Feld im DNS-SD-TXT-Eintrag angegeben.

Wertname	Werttyp	Beschreibung	TXT
Version	String	Höchste unterstützte Version (major.minor) der API, derzeit 1.0
name	String	Für Menschen lesbarer Name des Geräts.	ty
Beschreibung	String	(optional) Gerätebeschreibung. SOLLTE vom Nutzer geändert werden können.	note
URL	String	URL des Servers, mit dem dieses Gerät kommuniziert. Die URL MUSS eine Protokollspezifikation enthalten, z. B. https://www.google.com/cloudprint.	URL
Typ	Liste mit Strings	Liste der unterstützten Gerätetypen.	Typ
id	String	Geräte-ID, leer, wenn das Gerät noch nicht registriert wurde.	id
device_state	String	Status des Geräts: idle bedeutet, dass das Gerät bereit ist. processing bedeutet, dass das Gerät beschäftigt ist und die Funktionalität für einige Zeit eingeschränkt sein kann. stopped bedeutet, dass das Gerät nicht funktioniert und ein Nutzereingriff erforderlich ist.
connection_state	String	Status der Verbindung zum Server (base_url) online – Verbindung verfügbar offline – keine Verbindung connecting – Startschritte werden ausgeführt not-configured – Verbindung wurde noch nicht konfiguriert Ein registriertes Gerät kann seinen Verbindungsstatus basierend auf dem Status des Benachrichtigungskanals (z.B. XMPP-Verbindungsstatus) melden.	cs
Hersteller	String	Name des Geräteherstellers
Modell	String	Modell des Geräts
serial_number	String	Eindeutige Geräte-ID. In dieser Spezifikation MUSS es sich um eine UUID handeln. (GCP 1.1-Spezifikation) (optional): Wir empfehlen dringend, überall dieselbe Seriennummer-ID zu verwenden, damit verschiedene Clients dasselbe Gerät identifizieren können. Drucker, die IPP implementieren, können diese Seriennummer-ID beispielsweise im Feld „printer-device-id“ verwenden.
Firmware	String	Version der Gerätefirmware
Betriebszeit	int	Anzahl der Sekunden seit dem Start des Geräts.
setup_url	String	(optional) URL (einschließlich Protokoll) der Seite mit Einrichtungsanleitung
support_url	String	(optional) URL (einschließlich Protokoll) der Seite mit Support- und FAQ-Informationen
update_url	String	(optional) URL (einschließlich Protokoll) der Seite mit der Anleitung zum Aktualisieren der Firmware
x-privet-token	String	Wert des X-Privet-Token-Headers, der an alle APIs übergeben werden muss, um XSSI- und XSRF-Angriffe zu verhindern. Weitere Informationen finden Sie in Abschnitt 6.1.
API	Beschreibung von APIs	Liste der unterstützten APIs (siehe unten)
semantic_state	JSON	(Optional) Semantischer Status des Geräts im CloudDeviceState-Format.

api: Eine JSON-Liste mit den über das lokale Netzwerk verfügbaren APIs. Hinweis: Möglicherweise sind nicht alle APIs gleichzeitig über das lokale Netzwerk verfügbar. Ein neu verbundenes Gerät sollte beispielsweise nur die /register-API unterstützen:

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

Nach Abschluss der Geräteregistrierung SOLLTE das Gerät die /register API nicht mehr unterstützen. Das Gerät sollte auch beim Dienst nachfragen, welche APIs über das lokale Netzwerk verfügbar gemacht werden können. Beispiel:

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

Derzeit sind die folgenden APIs verfügbar:

/privet/register: API für die Geräteregistrierung über das lokale Netzwerk. Weitere Informationen finden Sie unter /privet/register API. Diese API MUSS ausgeblendet werden, sobald das Gerät erfolgreich in der Cloud registriert wurde.
/privet/accesstoken: API zum Anfordern eines Zugriffstokens vom Gerät (siehe /privet/accesstoken API für Details).
/privet/capabilities: API zum Abrufen von Gerätefunktionen (siehe /privet/capabilities API für Details).
/privet/printer/*: API, die für den Gerätetyp „Drucker“ spezifisch ist. Weitere Informationen finden Sie in den druckerspezifischen APIs.

Hier sehen Sie ein Beispiel für die Antwort auf /privet/info. Beachten Sie, dass die API „/privet/register“ fehlt, da das Gerät bereits registriert ist:

{
        "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",
        ]
}

Hier ist ein Beispiel für die /privet/info-Antwort für einen Drucker, bei dem die Tinte leer ist (siehe Feld „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. Fehler

Die /privet/info API sollte NUR dann einen Fehler zurückgeben, wenn der Header X-Privet-Token fehlt. Es MUSS ein HTTP 400-Fehler sein:

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

4.3. /privet/register API

Die API „/privet/register“ ist OPTIONAL. Es handelt sich um eine HTTP-POST-Anfrage. Die /privet/register API MUSS den Header X-Privet-Token auf Gültigkeit prüfen. Das Gerät MUSS diese API unter der URL „/privet/register“ implementieren:

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

Das Gerät sollte die API „/privet/register“ NUR dann bereitstellen, wenn es derzeit eine anonyme Registrierung zulässt. Beispiel:

Wenn das Gerät eingeschaltet ist (oder nachdem ein Nutzer auf eine spezielle Schaltfläche auf dem Gerät geklickt hat) und noch nicht registriert wurde, sollte die API „/privet/register“ verfügbar sein, damit ein Nutzer aus dem lokalen Netzwerk den Drucker beanspruchen kann.
Nach Abschluss der Registrierung sollte das Gerät die /privet/register-API nicht mehr zur Verfügung stellen, um zu verhindern, dass ein anderer Nutzer im lokalen Netzwerk das Gerät zurückfordert.
Auf einigen Geräten gibt es möglicherweise andere Möglichkeiten, Geräte zu registrieren, und die API „/privet/register“ sollte überhaupt nicht verfügbar sein (z. B. beim Chrome Cloud Print-Connector).

Der Registrierungsprozess besteht aus drei Schritten (siehe anonyme Registrierung für Cloud Print).

Anonyme Registrierung starten
Ein Client initiiert diesen Prozess durch Aufrufen der API „/privet/register“. Das Gerät wartet möglicherweise auf die Bestätigung durch den Nutzer.
Verknüpfungstoken abrufen

Der Client fragt ab, wann das Gerät bereit ist, fortzufahren. Sobald das Gerät bereit ist, sendet es eine Anfrage an den Server, um das Registrierungstoken und die Registrierungs-URL abzurufen. Das empfangene Token und die URL SOLLTEN an den Client zurückgegeben werden. Wenn das Gerät in diesem Schritt einen weiteren Aufruf zur Initialisierung der Registrierung erhält, sollte es Folgendes tun:

Wenn es sich um denselben Nutzer handelt, der die Registrierung gestartet hat, löschen Sie alle vorherigen Daten (falls vorhanden) und starten Sie einen neuen Registrierungsvorgang.
Wenn es sich um einen anderen Nutzer handelt, gib den Fehler „device_busy“ zurück und lege ein Zeitlimit von 30 Sekunden fest.

Schließen Sie die Registrierung ab.

Nachdem der Client das Gerät beansprucht hat, sollte er das Gerät benachrichtigen, um die Registrierung abzuschließen. Nach Abschluss der Registrierung sollte das Gerät eine Update-Ankündigung mit der neu erworbenen Geräte-ID senden.

Hinweis: Wenn das Gerät einen /privet/register-API-Aufruf verarbeitet, dürfen keine anderen /privet/register-API-Aufrufe gleichzeitig verarbeitet werden. Das Gerät MUSS den Fehler „device_busy“ und ein Zeitlimit von 30 Sekunden zurückgeben.

Es wird DRINGEND empfohlen, dass Nutzer die Registrierung auf dem Gerät bestätigen. Wenn die Funktion implementiert ist, MUSS das Gerät nach dem Empfang eines API-Aufrufs für /privet/register?action=start auf die Bestätigung des Nutzers warten. Der Client ruft die API „/privet/register?action=getClaimToken“ auf, um herauszufinden, wann die Nutzerbestätigung abgeschlossen ist und das Anspruchstoken verfügbar ist. Wenn der Nutzer die Registrierung auf dem Gerät abbricht (z.B. die Schaltfläche „Abbrechen“ drückt), MUSS der Fehler „user_cancel“ zurückgegeben werden. Wenn der Nutzer die Registrierung nicht innerhalb eines bestimmten Zeitraums bestätigt hat, MUSS der Fehler „confirmation_timeout“ zurückgegeben werden. Weitere Informationen finden Sie im Abschnitt „Standardeinstellungen“.

4.3.1. Eingabe

Die API „/privet/register“ hat die folgenden Eingabeparameter:

Name	Wert
Aktion	Kann einer der folgenden Werte sein: start: Registrierungsprozess starten getClaimToken: Anspruchstoken für das Gerät abrufen cancel: Registrierungsprozess abbrechen complete: Registrierungsprozess abschließen
Nutzer	E-Mail-Adresse des Nutzers, der dieses Gerät beanspruchen wird.

Das Gerät MUSS prüfen, ob die E‑Mail-Adresse aller Aktionen (start, getClaimToken, cancel, complete) übereinstimmt.

4.3.2. Rückflug

Die API „/privet/register“ gibt die folgenden Daten zurück:

Wertname	Werttyp	Beschreibung
Aktion	String	Dieselbe Aktion wie im Eingabeparameter.
Nutzer	String (optional)	Derselbe Nutzer wie im Eingabeparameter (kann fehlen, wenn er in der Eingabe ausgelassen wurde).
Token	String (optional)	Registrierungs-Token (erforderlich für die Antwort „getClaimToken“, nicht angegeben für „start“, „complete“, „cancel“).
claim_url	String (optional)	Registrierungs-URL (erforderlich für die Antwort „getClaimToken“, nicht angegeben für „start“, „complete“, „cancel“). Bei Cloud-Druckern muss es sich um die vom Server empfangene „complete_invite_url“ handeln.
automated_claim_url	String (optional)	Registrierungs-URL (erforderlich für die Antwort „getClaimToken“, nicht angegeben für „start“, „complete“, „cancel“). Bei Cloud-Druckern muss es sich um die vom Server empfangene „automated_invite_url“ handeln.
device_id	String (optional)	Neue Geräte-ID (bei der Antwort „start“ ausgelassen, bei „complete“ erforderlich).

Das Gerät MUSS seine Geräte-ID in der API-Antwort /privet/info NUR nach Abschluss der Registrierung zurückgeben.

Beispiel 1:

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

Beispiel 2:

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

Beispiel 3:

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

4.3.3. Fehler

Die API „/privet/register“ kann die folgenden Fehler zurückgeben (siehe Abschnitt „Fehler“ für weitere Informationen):

Fehler	Beschreibung
device_busy	Das Gerät ist beschäftigt und kann die angeforderte Aktion nicht ausführen. Versuchen Sie es nach Ablauf des Zeitlimits noch einmal.
pending_user_action	Als Antwort auf „getClaimToken“ weist dieser Fehler darauf hin, dass die Bestätigung durch den Nutzer für das Gerät noch aussteht und der „getClaimToken“-Request nach dem Timeout noch einmal versucht werden sollte.
user_cancel	Der Nutzer hat den Registrierungsvorgang auf dem Gerät explizit abgebrochen.
confirmation_timeout	Die Nutzerbestätigung ist abgelaufen.
invalid_action	Es wird eine ungültige Aktion aufgerufen. Wenn der Client beispielsweise „action=complete“ aufgerufen hat, bevor „action=start“ und „action=getClaimToken“ aufgerufen wurden.
invalid_params	In der Anfrage wurden ungültige Parameter angegeben. Unbekannte Parameter sollten aus Gründen der zukünftigen Kompatibilität sicher ignoriert werden. Geben Sie diesen Wert beispielsweise zurück, wenn der Client „action=unknown“ oder „user=“ aufgerufen hat.
device_config_error	Datum/Uhrzeit (oder andere Einstellungen) sind auf dem Gerät falsch. Der Nutzer muss die interne Website des Geräts aufrufen und die Geräteeinstellungen konfigurieren.
Offline	Das Gerät ist derzeit offline und kann nicht mit dem Server kommunizieren.
server_error	Beim Registrierungsvorgang ist ein Serverfehler aufgetreten.
invalid_x_privet_token	Der X-Privet-Token in der Anfrage ist ungültig oder leer.

Das Gerät MUSS die /privet/register API nicht mehr zur Verfügung stellen, nachdem die Registrierung abgeschlossen wurde. Wenn das Gerät die API „/privet/register“ nicht bereitstellt, MUSS es den HTTP-Fehler 404 zurückgeben. Wenn ein Gerät bereits registriert ist, MUSS beim Aufrufen dieser API der Fehlercode 404 zurückgegeben werden. Wenn der Header „X-Privet-Token“ fehlt, MUSS das Gerät den HTTP-Fehler 400 zurückgeben.

4.4. /privet/accesstoken API

Die /privet/accesstoken API ist OPTIONAL. Es handelt sich um eine HTTP GET-Anfrage. Die /privet/accesstoken API MUSS einen gültigen „X-Privet-Token“-Header prüfen. Das Gerät MUSS diese API unter der URL „/privet/accesstoken“ implementieren:

GET /privet/accesstoken HTTP/1.1

Wenn das Gerät den API-Aufruf „/accesstoken“ empfängt, sollte es den Server aufrufen, um das Zugriffstoken für den angegebenen Nutzer abzurufen und das Token an den Client zurückzugeben. Der Client verwendet dann das Zugriffstoken, um über die Cloud auf dieses Gerät zuzugreifen.

Cloud Print-Geräte MÜSSEN die folgende API aufrufen:

/cloudprint/proximitytoken

und übergeben Sie den Parameter „printerid=<printer_id>“ und den Parameter „user“ aus der lokalen API. Bei erfolgreicher Ausführung enthält die Serverantwort das folgende Objekt:

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

Cloud Print-Geräte MÜSSEN den Wert des „proximity_token“-Objekts in der Antwort an lokale /privet/accesstoken-API-Aufrufe übergeben. Es ist vorteilhafter (zukunftssicher), wenn das Gerät ALLE Parameter (auch solche, die nicht in dieser Spezifikation beschrieben sind) bestehen kann.

4.4.1. Eingabe

Die API „/privet/accesstoken“ hat die folgenden Eingabeparameter:

Name	Wert
Nutzer	E-Mail-Adresse des Nutzers, der dieses Zugriffstoken verwenden wollte. Kann in der Anfrage leer sein.

4.4.2. Rückflug

Die /privet/accesstoken API gibt die folgenden Daten zurück:

Wertname	Werttyp	Beschreibung
token	String	Vom Server zurückgegebenes Zugriffstoken
Nutzer	String	Derselbe Nutzer wie im Eingabeparameter.
expires_in	int	Anzahl der Sekunden bis zum Ablauf dieses Tokens. Vom Server empfangen und in dieser Antwort übergeben.

Beispiel:

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

4.4.3. Fehler

Die /privet/accesstoken API kann die folgenden Fehler zurückgeben (siehe Abschnitt „Fehler“ für Details):

Fehler	Beschreibung
Offline	Das Gerät ist derzeit offline und kann nicht mit dem Server kommunizieren.
access_denied	Unzureichende Rechte. Zugriff verweigert. Das Gerät sollte diesen Fehler zurückgeben, wenn die Anfrage vom Server explizit abgelehnt wurde.
invalid_params	In der Anfrage wurden ungültige Parameter angegeben. Unbekannte Parameter sollten aus Gründen der zukünftigen Kompatibilität sicher ignoriert werden. Wenn ein Client beispielsweise /accesstoken?user= oder /accesstoken aufruft.
server_error	Serverfehler.
invalid_x_privet_token	X-Privet-Token ist in der Anfrage ungültig oder leer.

Wenn das Gerät die API „/privet/accesstoken“ nicht bereitstellt, MUSS es den HTTP-Fehler 404 zurückgeben. Wenn der Header „X-Privet-Token“ fehlt, MUSS das Gerät den HTTP-Fehler 400 zurückgeben.

4.5. /privet/capabilities API

Die API „/privet/capabilities“ ist OPTIONAL. Es handelt sich um eine HTTP GET-Anfrage. Die /privet/capabilities API MUSS einen gültigen „X-Privet-Token“-Header prüfen. Das Gerät MUSS diese API unter der URL „/privet/capabilities“ implementieren:

GET /privet/capabilities HTTP/1.1

Wenn das Gerät den API-Aufruf „/capabilities“ empfängt, SOLLTE es, sofern möglich, den Server kontaktieren, um aktualisierte Funktionen abzurufen. Wenn ein Drucker beispielsweise das Senden eines (lokal empfangenen) Druckauftrags an sich selbst über den Cloud Print-Dienst unterstützt, sollten die zurückgegebenen Funktionen denen entsprechen, die der Cloud Print-Dienst zurückgeben würde. Cloud Print kann in diesem Fall die ursprünglichen Druckerfunktionen ändern, indem neue Funktionen hinzugefügt werden, die vor dem Senden des Auftrags an den Drucker ausgeführt werden. Der häufigste Fall ist eine Liste der unterstützten Dokumenttypen. Wenn der Drucker offline ist, sollten die unterstützten Dokumenttypen zurückgegeben werden. Wenn der Drucker jedoch online und bei Cloud Print registriert ist, MUSS er „*/*“ als einen der unterstützten Typen zurückgeben. Der Cloud Print-Dienst führt in diesem Fall die erforderliche Konvertierung durch. Für das Offline-Drucken MUSS der Drucker mindestens das Format „image/pwg-raster“ unterstützen.

4.5.1. Eingabe

Die API „/privet/capabilities“ hat die folgenden Eingabeparameter:

Name	Wert
Offline	(optional) Kann nur „offline=1“ sein. In diesem Fall sollte das Gerät Funktionen für die Offline-Nutzung zurückgeben, sofern diese sich von den Online-Funktionen unterscheiden.

4.5.2. Rückflug

Die API „/privet/capabilities“ gibt Gerätefunktionen im JSON-Format des Cloud Device Description (CDD) zurück. Weitere Informationen finden Sie im CDD-Dokument. Drucker MÜSSEN hier mindestens eine Liste der unterstützten Typen zurückgeben. Ein Beispiel: Ein cloudfähiger Drucker, der derzeit online ist, gibt möglicherweise Folgendes zurück (mindestens):

{
        "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": "*/*" }
                ]
        }
}

Wenn die Verbindung zum Server getrennt ist, kann Folgendes zurückgegeben werden:

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

Hinweis: Drucker geben die Priorität unterstützter Inhaltstypen über die Reihenfolge an. In den obigen Beispielen gibt der Drucker beispielsweise an, dass er „application/pdf“-Daten gegenüber „image/pwg-raster“ und „image/jpeg“ bevorzugt. Clients sollten die Priorisierung von Druckern nach Möglichkeit berücksichtigen (siehe CDD-Dokument für Details).

4.5.3. Fehler

Die API „/privet/capabilities“ kann die folgenden Fehler zurückgeben (siehe Abschnitt „Fehler“ für Details):

Fehler	Beschreibung
invalid_x_privet_token	Der X-Privet-Token in der Anfrage ist ungültig oder leer.

Wenn das Gerät die API „/privet/capabilities“ nicht bereitstellt, MUSS es den HTTP-Fehler 404 zurückgeben. Wenn der Header „X-Privet-Token“ fehlt, MUSS das Gerät den HTTP-Fehler 400 zurückgeben.

4.6. Fehler

Fehler werden von den oben genannten APIs im folgenden Format zurückgegeben:

Wertname	Werttyp	Beschreibung
Fehler	String	Fehlertyp (pro API definiert)
Beschreibung	String (optional)	Für Menschen lesbare Beschreibung des Fehlers.
server_api	String (optional)	Bei einem Serverfehler enthält dieses Feld die Server-API, bei der der Fehler aufgetreten ist.
server_code	int (optional)	Im Falle eines Serverfehlers enthält dieses Feld den Fehlercode, den der Server zurückgegeben hat.
server_http_code	int (optional)	Im Falle eines HTTP-Serverfehlers enthält dieses Feld den vom Server zurückgegebenen HTTP-Fehlercode.
Zeitüberschreitung	int (optional)	Anzahl der Sekunden, die der Client vor einem Neuversuch warten soll (nur bei behebbaren Fehlern). Der Client MUSS das tatsächliche Zeitlimit von diesem Wert auf einen Wert randomisieren, der + 20 % beträgt.

Alle APIs MÜSSEN den HTTP-Fehler 400 zurückgeben, wenn der Header „X-Privet-Token“ fehlt.

HTTP/1.1 400 Missing X-Privet-Token header. (HTTP/1.1 400 Fehlender X-Privet-Token-Header)

Beispiel 1:

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

Beispiel 2:

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

5. Printer API

Einer der Gerätetypen, die dieses Protokoll unterstützt, ist der Typ „Drucker“. Geräte, die diesen Typ unterstützen, KÖNNEN einige spezifische Druckerfunktionen implementieren. Im Idealfall erfolgt das Drucken auf cloudfähigen Druckern über einen Cloud Print-Server:

In einigen Fällen muss ein Kunde ein Dokument lokal senden. Sie ist möglicherweise erforderlich, wenn der Client keine Google-ID hat oder nicht mit dem Cloud Print-Server kommunizieren kann. In diesem Fall wird der Druckauftrag lokal an den Drucker gesendet. Der Drucker verwendet wiederum den Cloud Print-Dienst für die Warteschlange und die Konvertierung von Aufträgen. Der Drucker sendet den lokal eingereichten Job noch einmal an den Cloud Print-Dienst und fordert ihn dann an, da er über die Cloud eingereicht wurde. Dieser Prozess bietet eine flexible Nutzererfahrung in Bezug auf die Dienstkonvertierung und die Verwaltung/Nachverfolgung von Druckaufträgen.

Da der Cloud Print-Dienst die Konvertierung implementiert, SOLLTE der Drucker alle Eingabeformate („*/*“) in der Liste der unterstützten Inhaltstypen angeben:

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

In einigen Fällen ist eine vollständig Offline-Lösung gewünscht. Da Drucker nur eine begrenzte Anzahl von Eingabeformaten unterstützen, muss ein Client Dokumente in einige nativ unterstützte Druckerformate konvertieren.

Gemäß dieser Spezifikation MÜSSEN alle Drucker für das Offline-Drucken mindestens das PWG-Rasterformat („image/pwg-raster“) unterstützen. Ein Drucker unterstützt möglicherweise andere Formate (z. B. JPEG). Wenn ein Client dies unterstützt, kann er Dokumente in diesem Format senden. Der Drucker MUSS unterstützte Typen über die /capabilities-API verfügbar machen, z. B.:

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

Es gibt zwei Möglichkeiten, wie ein Client das Drucken über das lokale Netzwerk initiieren kann.

Einfaches Drucken: Der Client sendet das Dokument über das lokale Netzwerk an die /submitdoc API (ohne Angabe des Parameters „job_id“). Das eingereichte Dokument wird mit den Standardeinstellungen für das Druckticket gedruckt und es sind keine Druckauftragsstatus erforderlich. Wenn der Drucker NUR diesen Drucktyp unterstützt, MUSS er in der /privet /info-API-Antwort NUR die/submitdoc-API ankündigen.

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

Erweiterter Druck: Der Client sollte zuerst einen Druckauftrag auf dem Drucker erstellen, indem er die API /privet/printer/createjob mit einem gültigen CJT-Jobticket im Antrag aufruft. Der Drucker MUSS das Druckticket im Speicher speichern und eine job_id an den Client zurückgeben. Der Client ruft dann die API „/printer/submitdoc“ auf und gibt die zuvor empfangene job_id an. Zu diesem Zeitpunkt beginnt der Drucker mit dem Drucken. Der Client ruft den Drucker auf, um den Status des Druckauftrags abzurufen, indem er die API /privet/printer/jobstate aufruft.

In einer Umgebung mit mehreren Clients gibt es keine Garantie dafür, wie diese API aufgerufen wird. Es ist möglich, dass ein Client /createjob zwischen den /createjob->/submitdoc-Aufrufen eines anderen Clients aufruft. Um mögliche Deadlocks zu vermeiden und die Benutzerfreundlichkeit zu verbessern, empfehlen wir, dass sich auf dem Drucker eine kleine Warteschlange mit ausstehenden Druckaufträgen befindet (mindestens 3–5):

/createjob nimmt den ersten verfügbaren Platz in der Warteschlange ein.
Die Lebensdauer des Jobs (in der Warteschlange) beträgt mindestens 5 Minuten.
Wenn alle Plätze in der Warteschlange belegt sind, wird der älteste Job, der nicht gedruckt wird, entfernt und ein neuer Job wird dort platziert.
Wenn auf dem Gerät gerade ein Druckauftrag gedruckt wird (einfacher oder erweiterter Druck), sollte /submitdoc den Status „busy“ zurückgeben und ein Zeitlimit für den erneuten Versuch dieses Druckauftrags vorschlagen.
Wenn sich /submitdoc auf einen Job bezieht, der aus der Warteschlange entfernt wurde (aufgrund von Ersatz oder Zeitüberschreitung), sollte der Drucker den Fehler invalid_print_job zurückgeben und der Client versucht den Vorgang ab dem Schritt /createjob noch einmal. Der Client MUSS vor dem Wiederholungsversuch einen zufälligen Zeitraum von bis zu 5 Sekunden abwarten.

Wenn aufgrund von Speicherbeschränkungen nicht mehrere ausstehende Jobs auf dem Gerät gespeichert werden können, ist es möglich, dass die Warteschlange nur einen Druckjob umfasst. Es sollte weiterhin dem oben beschriebenen Protokoll folgen. Nachdem ein Job abgeschlossen oder mit einem Fehler fehlgeschlagen ist, sollte der Drucker Informationen zum Status des Jobs mindestens 5 Minuten lang speichern. Die Warteschlangengröße zum Speichern von Status abgeschlossener Jobs sollte mindestens 10 betragen. Wenn mehr Jobstatus gespeichert werden müssen, wird der älteste möglicherweise vor dem 5-Minuten-Zeitlimit aus der Warteschlange entfernt.

Hinweis:Derzeit fragen Clients den Jobstatus ab. In Zukunft müssen Drucker möglicherweise eine TXT-DNS-Benachrichtigung senden, wenn sich der Status eines Druckauftrags ändert.

5.1. /privet/printer/createjob API

Die API „/privet/printer/createjob“ ist OPTIONAL (siehe „Einfaches Drucken“ oben). Es handelt sich um eine HTTP-POST-Anfrage. Die API „/privet/printer/createjob“ MUSS nach einem gültigen „X-Privet-Token“-Header suchen. Das Gerät MUSS diese API unter der URL „/privet/printer/createjob“ implementieren:

POST /privet/printer/createjob HTTP/1.1

Beim Empfang des API-Aufrufs /privet/printer/createjob MUSS der Drucker eine neue Druckjob-ID erstellen, das empfangene Druckticket im CJT-Format speichern und die Druckjob-ID an den Client zurückgeben.

5.1.1. Eingabe

Die API „/privet/printer/createjob“ hat keine Eingabeparameter in der URL. Der Anfragetext sollte die Daten des Druckauftragstickets im CJT-Format enthalten.

5.1.2. Rückflug

Die API „/privet/printer/createjob“ gibt die folgenden Daten zurück:

Wertname	Werttyp	Beschreibung
job_id	String	ID des neu erstellten Druckauftrags.
expires_in	int	Anzahl der Sekunden, die dieser Druckauftrag gültig ist.

Beispiel:

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

5.1.3. Fehler

Die API „/privet/printer/createjob“ kann die folgenden Fehler zurückgeben (siehe Abschnitt „Fehler“ für weitere Informationen):

Fehler	Beschreibung
invalid_ticket	Das eingereichte Druckticket ist ungültig.
printer_busy	Der Drucker ist beschäftigt und kann /createjob derzeit nicht verarbeiten. Versuchen Sie es nach Ablauf des Zeitlimits noch einmal.
printer_error	Der Drucker befindet sich im Fehlerstatus und erfordert eine Nutzerinteraktion, um das Problem zu beheben. Die Beschreibung sollte eine detailliertere Erklärung enthalten (z.B. „Papierstau in Fach 1“).
invalid_x_privet_token	Der X-Privet-Token in der Anfrage ist ungültig oder leer.

Wenn das Gerät /privet/printer/createjob nicht verfügbar macht, MUSS es den HTTP-Fehler 404 zurückgeben. Wenn der X-Privet-Token-Header fehlt, MUSS das Gerät den HTTP-Fehler 400 zurückgeben.

5.2. /privet/printer/submitdoc API

Die API „/privet/printer/submitdoc“ ist ERFORDERLICH, um das Drucken über ein lokales Netzwerk (offline oder erneutes Senden an Cloud Print) zu implementieren. Es handelt sich um eine HTTP-POST-Anfrage. Die /privet/printer/submitdoc API MUSS nach einem gültigen „X-Privet-Token“-Header suchen. Das Gerät MUSS diese API unter der URL „/privet/printer/submitdoc“ implementieren:

POST /privet/printer/submitdoc HTTP/1.1

Wenn der Drucker den API-Aufruf /privet/printer/submitdoc empfängt, sollte er mit dem Drucken beginnen. Wenn der Druck nicht gestartet werden kann, MUSS der Fehler „printer_busy“ und ein empfohlenes Zeitlimit zurückgegeben werden, das der Client abwarten soll, bevor er es noch einmal versucht.

Wenn der Drucker nicht alle Daten in seinem internen Puffer speichern kann, SOLLTE er TCP-Mechanismen verwenden, um die Datenübertragung zu verlangsamen, bis ein Teil des Dokuments gedruckt wurde und ein Teil des Puffers wieder verfügbar ist. Beispiel: Der Drucker legt möglicherweise „windowsize=0“ auf TCP-Ebenen fest, wodurch der Client warten muss.

Das Senden eines Dokuments an den Drucker kann einige Zeit in Anspruch nehmen. Der Client sollte den Status des Druckers und des Jobs (erweiterter Druck) während des Druckvorgangs prüfen können. Dazu MUSS der Drucker dem Client erlauben, die APIs „/privet/info“ und „/privet/printer/jobstate“ aufzurufen, während er API-Aufrufe von „/privet/printer/submitdoc“ verarbeitet. Es wird empfohlen, dass alle Clients einen neuen Thread starten, um den API-Aufruf /privet/printer/submitdoc auszuführen, damit der Hauptthread die APIs /privet/info und /privet/printer/jobstate verwenden kann, um den Drucker- und Jobstatus zu prüfen.

Hinweis: Nach Abschluss oder Abbruch des lokalen Druckauftrags wird dringend empfohlen (und in einer zukünftigen Version dieser Spezifikation erforderlich), den endgültigen Status des Auftrags an die Schnittstelle „/cloudprint/submit“ zu melden, um die Abrechnung und Nutzerfreundlichkeit zu verbessern. Die Parameter „printerid“, „title“, „contentType“ und „final_semantic_state“ (im PrintJobState-Format) sind erforderlich. Die Parameter „tag“ (wiederholter Parameter) und „ticket“ (das Ticket des Jobs im CloudJobTicket-Format) sind optional. Der angegebene PrintJobState muss endgültig sein, d. h. sein Typ muss DONE oder ABORTED sein. Wenn er ABORTED ist, muss ein Grund angegeben werden (siehe JobState für weitere Informationen). Außerdem wird die Verwendung der Schnittstelle /cloudprint/submit zum Melden lokaler Druckaufträge nicht in der Spezifikation erwähnt, da in diesem Abschnitt die primäre Verwendung der Schnittstelle beschrieben wird: das Senden eines Druckauftrags mit dem zu druckenden Dokument, das im Parameter „content“ angegeben ist.

5.2.1. Eingabe

Die API „/privet/printer/submitdoc“ hat die folgenden Eingabeparameter:

Name	Wert
job_id	(Optional) Druckjob-ID. Kann für einfache Druckvorgänge weggelassen werden (siehe oben). Muss mit dem vom Drucker zurückgegebenen Wert übereinstimmen.
user_name	Optional: Für Menschen lesbarer Nutzername. Dies ist nicht endgültig und sollte nur für Anmerkungen zu Druckaufträgen verwendet werden. Wenn der Job noch einmal an den Cloud Print-Dienst gesendet wird, sollte dieser String an den Cloud Print-Job angehängt werden.
client_name	(Optional) Name der Clientanwendung, die diese Anfrage stellt. Nur zu Anzeigezwecken. Wenn der Job noch einmal an den Cloud Print-Dienst gesendet wird, sollte dieser String an den Cloud Print-Job angehängt werden.
job_name	(Optional) Name des aufzuzeichnenden Druckauftrags. Wenn der Job noch einmal an den Cloud Print-Dienst gesendet wird, sollte dieser String an den Cloud Print-Job angehängt werden.
Offline	(optional) Kann nur „offline=1“ sein. In diesem Fall sollte der Drucker nur versuchen, offline zu drucken (kein erneutes Senden an den Cloud Print-Server).

Der Anfragetext sollte ein gültiges Dokument zum Drucken enthalten. „Content-Length“ sollte die korrekte Länge der Anfrage enthalten. Der Header „Content-Type“ sollte auf den MIME-Typ des Dokuments festgelegt werden und einem der Typen im CDD entsprechen (sofern im CDD nicht „*/*“ angegeben ist).

Es wird DRINGEND empfohlen, mit dieser Anfrage einen gültigen Nutzernamen (oder eine E‑Mail-Adresse), einen Kundennamen und einen Jobnamen anzugeben. Diese Felder werden nur in Benutzeroberflächen verwendet, um die Nutzerfreundlichkeit zu verbessern.

5.2.2. Rückflug

Die API „/privet/printer/submitdoc“ gibt die folgenden Daten zurück:

Wertname	Werttyp	Beschreibung
job_id	String	ID des neu erstellten Druckauftrags (einfaches Drucken) oder job_id, die in der Anfrage angegeben ist (erweitertes Drucken).
expires_in	int	Anzahl der Sekunden, die dieser Druckauftrag gültig ist.
job_type	String	Inhaltstyp des eingereichten Dokuments.
job_size	int 64 Bit	Größe der Druckdaten in Byte.
job_name	String	Optional: Derselbe Jobname wie in der Eingabe (falls vorhanden).

Beispiel:

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

5.2.3. Fehler

Die API „/privet/printer/submitdoc“ kann die folgenden Fehler zurückgeben (siehe Abschnitt „Fehler“ für weitere Informationen):

Fehler	Beschreibung
invalid_print_job	In der Anfrage wurde eine ungültige/abgelaufene Job-ID angegeben. Versuchen Sie es nach der Zeitüberschreitung noch einmal.
invalid_document_type	Der MIME-Typ des Dokuments wird vom Drucker nicht unterstützt.
invalid_document	Das eingereichte Dokument ist ungültig.
document_too_large	Das Dokument überschreitet die maximal zulässige Größe.
printer_busy	Der Drucker ist beschäftigt und kann das Dokument derzeit nicht verarbeiten. Versuchen Sie es nach Ablauf des Zeitlimits noch einmal.
printer_error	Der Drucker befindet sich im Fehlerstatus und erfordert eine Nutzerinteraktion, um das Problem zu beheben. Die Beschreibung sollte eine detailliertere Erklärung enthalten (z.B. „Papierstau in Fach 1“).
invalid_params	In der Anfrage wurden ungültige Parameter angegeben. (Unbekannte Parameter sollten aus Gründen der zukünftigen Kompatibilität ignoriert werden.)
user_cancel	Der Nutzer hat den Druckvorgang explizit über das Gerät abgebrochen.
server_error	Das Dokument konnte nicht in Cloud Print gepostet werden.
invalid_x_privet_token	Der X-Privet-Token in der Anfrage ist ungültig oder leer.

Wenn das Gerät /privet/printer/submitdoc nicht verfügbar macht, MUSS es den HTTP-Fehler 404 zurückgeben. Wenn der Header „X-Privet-Token“ fehlt, MUSS das Gerät den HTTP-Fehler 400 zurückgeben.

Hinweis: Die API „/privet/printer/submitdoc“ erfordert möglicherweise eine spezielle Verarbeitung auf der Druckerseite (aufgrund der großen angehängten Nutzlast). In einigen Fällen (abhängig von der Implementierung des HTTP-Servers des Druckers und der Plattform) schließt der Drucker den Socket, BEVOR er einen HTTP-Fehler zurückgibt. In anderen Fällen gibt der Drucker möglicherweise den Fehler 503 (anstelle eines Privet-Fehlers) zurück. Drucker SOLLTEN nach Möglichkeit Privet zurückgeben. Jeder Client, der die Privet-Spezifikation implementiert, SOLLTE jedoch in der Lage sein, das Schließen von Sockets (kein HTTP-Fehler) und HTTP-Fehler 503 für die /privet/printer/submitdoc-API zu verarbeiten. In diesem Fall SOLLTE der Client ihn als Privet-Fehler „printer_busy“ mit dem Wert „timeout“ von 15 Sekunden behandeln. Um unendliche Wiederholungen zu vermeiden, kann der Client nach einer angemessenen Anzahl von Versuchen (z. B. 3) aufhören, es noch einmal zu versuchen.

5.3. /privet/printer/jobstate API

Die API „/privet/printer/jobstate“ ist OPTIONAL (siehe „Einfaches Drucken“ oben). Es handelt sich um eine HTTP GET-Anfrage. Die /privet/printer/jobstate-API MUSS einen gültigen „X-Privet-Token“-Header prüfen. Das Gerät MUSS diese API unter der URL „/privet/printer/jobstate“ implementieren:

GET /privet/printer/jobstate HTTP/1.1

Wenn ein /privet/printer/jobstate-API-Aufruf empfangen wird, sollte ein Drucker den Status des angeforderten Druckauftrags oder den Fehler „invalid_print_job“ zurückgeben.

5.3.1. Eingabe

Die API „/privet/printer/jobstate“ hat die folgenden Eingabeparameter:

Name	Wert
job_id	Die ID des Druckauftrags, für den der Status zurückgegeben werden soll.

5.3.2. Rückflug

Die API „/privet/printer/jobstate“ gibt die folgenden Daten zurück:

Wertname	Werttyp	Beschreibung
job_id	String	Die ID des Druckauftrags, für den Statusinformationen angezeigt werden.
Bundesstaat	String	draft: Der Druckauftrag wurde auf dem Gerät erstellt. Es wurden noch keine /privet/printer/submitdoc-Aufrufe empfangen. queued (in der Warteschlange) – Der Druckauftrag wurde empfangen und in die Warteschlange gestellt, der Druckvorgang hat aber noch nicht begonnen. in_progress: Der Druckauftrag wird gerade gedruckt. stopped (angehalten): Der Druckauftrag wurde pausiert, kann aber manuell oder automatisch neu gestartet werden. done: Der Druckauftrag ist abgeschlossen. aborted (abgebrochen): Der Druckauftrag ist fehlgeschlagen.
Beschreibung	String	(optional) Eine für Menschen lesbare Beschreibung des Status des Druckauftrags. Sollte zusätzliche Informationen enthalten, wenn state< stopped oder aborted ist. Das Feld semantic_state enthält in der Regel eine bessere und aussagekräftigere Beschreibung für den Client.
expires_in	int	Anzahl der Sekunden, die dieser Druckauftrag gültig ist.
job_type	String	(Optional) Inhaltstyp des eingereichten Dokuments.
job_size	int 64 Bit	(optional) Größe der Druckdaten in Byte.
job_name	String	Optional: Derselbe Jobname wie in der Eingabe (falls vorhanden).
server_job_id	String	(optional) ID des vom Server zurückgegebenen Jobs (falls der Job an den Cloud Print-Dienst gesendet wurde). Für den Offlinedruck ausgelassen.
semantic_state	JSON	(optional) Semantischer Status des Jobs im Format PrintJobState.

Beispiel (Drucken durch Berichterstellung über 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"
}

Beispiel (Fehler beim Offlinedruck):

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

Beispiel (Druckauftrag vom Nutzer abgebrochen):

{
        "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
        }
}

Beispiel: Der Druckauftrag wurde aufgrund von Papiermangel angehalten. Beachten Sie den Verweis auf den Gerätestatus. Der Client muss die /privet/info API aufrufen, um weitere Informationen zum Gerätestatus zu erhalten:

{
        "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. Fehler

Die API „/privet/printer/jobstate“ kann die folgenden Fehler zurückgeben (siehe Abschnitt „Fehler“ für weitere Informationen):

Fehler	Beschreibung
invalid_print_job	In der Anfrage wurde eine ungültige oder abgelaufene Job-ID angegeben.
server_error	Der Status von Druckaufträgen, die in Cloud Print gepostet wurden, konnte nicht abgerufen werden.
invalid_x_privet_token	Der X-Privet-Token in der Anfrage ist ungültig oder leer.

Wenn das Gerät /privet/printer/jobstate nicht verfügbar macht, MUSS es den HTTP-Fehler 404 zurückgeben. Wenn der Header „X-Privet-Token“ fehlt, MUSS das Gerät den HTTP-Fehler 400 zurückgeben.

6. Anhang

6.1. Standardverhalten und ‑einstellungen

In diesem Abschnitt wird das Standardverhalten beschrieben, das wir von ALLEN Privet-kompatiblen Geräten erwarten.

Out-of-the-box-Geräte sollten nur die APIs /privet/info und /privet/register unterstützen. Alle anderen APIs (z.B. /privet/accesstoken, lokales Drucken) sollten deaktiviert werden.
Für die Registrierung ist eine physische Interaktion mit einem Gerät erforderlich.

Der Nutzer MUSS eine physische Aktion auf dem Gerät ausführen (z.B. eine Taste drücken), um seinen Zugriff auf das Gerät zu bestätigen.
Nachdem der Nutzer die oben genannte Aktion ausgeführt hat, sollte der Drucker die Anfrage /cloudprint/register senden. Diese Anfrage sollte erst nach der Ausführung der Aktion gesendet werden (siehe Ablaufdiagramm 1).
Wenn das Gerät eine /privet/register-Anfrage verarbeitet (z. B. auf die oben genannte Aktion wartet), muss es alle anderen /privet/register-Anfragen ablehnen. Das Gerät MUSS in diesem Fall den Fehler „device_busy“ zurückgeben.
Das Gerät sollte für jede /register-Anfrage, die nicht innerhalb von 60 Sekunden die oben genannte physische Aktion erhält, ein Zeitlimit festlegen. Das Gerät MUSS in diesem Fall den Fehler „confirmation_timeout“ zurückgeben.
Optional: Die folgenden Empfehlungen sind nicht erforderlich, können aber die Nutzerfreundlichkeit verbessern:

Möglicherweise blinkt eine LED oder auf dem Display wird eine Meldung angezeigt, um darauf hinzuweisen, dass der Nutzer die Registrierung bestätigen muss.
Auf dem Display des Druckers wird möglicherweise angezeigt, dass er für Google Cloud Print für den Nutzer abc@def.com registriert wird. Drücken Sie zum Fortfahren auf „OK“. Dabei ist abc@def.com der Nutzerparameter aus dem API-Aufruf /register. So wird für Nutzer deutlicher, dass

dass sie ihren Registrierungsantrag bestätigen.
Was passiert, wenn er/sie die Anfrage nicht ausgelöst hat?

Zusätzlich zu einer physischen Aktion zur Bestätigung über den Drucker (z.B. „Drücken Sie die OK-Taste“). Ein Drucker kann dem Nutzer auch eine Schaltfläche zum Abbrechen der Anfrage anbieten (z. B. „Drücken Sie auf ‚Abbrechen‘, um abzulehnen.“) Dadurch können Nutzer, die die Registrierungsanfrage nicht ausgelöst haben, sie vor dem 60-Sekunden-Zeitlimit abbrechen. Das Gerät MUSS in diesem Fall den Fehler „user_cancel“ zurückgeben.

Übertragungen von Eigentumsrechten:

Das Gerät wurde möglicherweise explizit aus dem Cloud-Dienst gelöscht.

Wenn das Gerät eine Erfolgsmeldung, aber keine Gerätebeschreibung als Ergebnis des Aufrufs von /cloudprint/printer (für GCP) erhält, MUSS es in den Standardmodus (Out-of-the-Box-Modus) zurückkehren.
Wenn die Anmeldedaten des Geräts nicht mehr funktionieren (explizit aufgrund der Antwort „Ungültige Anmeldedaten“ vom Server), MUSS das Gerät in den Standardmodus (Out-of-the-Box-Modus) zurückkehren.

Beim lokalen Zurücksetzen auf die Werkseinstellungen MÜSSEN die Anmeldedaten des Geräts gelöscht und das Gerät auf den Standardzustand zurückgesetzt werden.
Optional: Das Gerät bietet möglicherweise ein Menüelement zum Löschen von Anmeldedaten und zum Zurücksetzen in den Standardmodus.

Geräte, die XMPP-Benachrichtigungen unterstützen, MÜSSEN die Möglichkeit bieten, den Server anzupingen. Das Ping-Zeitlimit MUSS vom Server über „local_settings“ gesteuert werden können.
Das Gerät darf den Server (/cloudprint/printer API für GCP zusätzlich zu XMPP-Pings) nicht häufiger als einmal täglich (24 Stunden) pingen, um sicherzustellen, dass die Daten synchronisiert sind. Es wird empfohlen, das Prüffenster innerhalb eines Zeitraums von 24 bis 32 Stunden zu randomisieren.
Optional: Für Cloud Print-Geräte wird empfohlen, aber nicht vorgeschrieben, dass der Nutzer über eine manuelle Methode (Schaltfläche) eine Suche nach neuen Druckaufträgen vom Gerät aus starten kann. Einige Drucker haben diese Funktion bereits.
Optional. Bei Unternehmensdruckern kann die lokale Suche möglicherweise vollständig deaktiviert werden. In diesem Fall MUSS das Gerät diese lokalen Einstellungen auf dem Server aktualisieren. Neue lokale Einstellungen MÜSSEN leer sein. Wenn Sie „local_discovery“ auf „false“ setzen, kann die Funktion über den GCP-Dienst wieder aktiviert werden.

6.1.2 Standardregistrierungsdiagramm

6.2. XSSI- und XSRF-Angriffe und Schutzmaßnahmen

In diesem Abschnitt wird die Möglichkeit von XSSI- und XSRF-Angriffen auf das Gerät erläutert und beschrieben, wie Sie sich davor schützen können (einschließlich Techniken zur Token-Generierung).
Weitere Informationen finden Sie hier: http://googleonlinesecurity.blogspot.com/2011/05/website-security-for-webmasters.html
Normalerweise sind XSSI- und XSRF-Angriffe möglich, wenn eine Website Cookie-Authentifizierungsmechanismen verwendet. Google verwendet zwar keine Cookies für den Cloud Print Service, solche Angriffe sind aber dennoch möglich. Beim Zugriff auf das lokale Netzwerk werden Anfragen standardmäßig implizit als vertrauenswürdig eingestuft.

6.2.1. XSSI

Es ist möglich, dass eine schädliche Website die IP-Adresse und Portnummer eines Privet-kompatiblen Geräts errät und versucht, die Privet API mit „src=<api name>“ in einem <script>-Tag aufzurufen:

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

Ohne Schutz könnten schädliche Websites API-Aufrufe ausführen und auf Ergebnisse zugreifen.
Um diese Art von Angriff zu verhindern, MUSS für ALLE privaten API-Aufrufe der Header „X-Privet-Token“ in der Anfrage erforderlich sein. Mit „src=<api>“-Script-Tags können keine Header hinzugefügt werden, was diese Art von Angriffen verhindert.

6.2.2. XSRF

http://en.wikipedia.org/wiki/Cross-site_request_forgery
Eine schädliche Website kann die IP-Adresse und Portnummer eines Privet-kompatiblen Geräts erraten und versuchen, die Privet API über ein <iframe>, Formulare oder einen anderen websiteübergreifenden Lademechanismus aufzurufen. Angreifer könnten nicht auf die Ergebnisse der Anfrage zugreifen, aber wenn durch die Anfrage eine Aktion ausgeführt würde (z.B. Drucken), könnten sie diese auslösen.

Um diesen Angriff zu verhindern, benötigen wir den folgenden Schutz:

/privet/info API für XSRF offen lassen
Die /privet/info API darf keine Aktionen auf dem Gerät ausführen.
/privet/info-API verwenden, um x-privet-token zu erhalten
Alle anderen APIs MÜSSEN im Header „X-Privet-Token“ nach einem gültigen x-privet-Token suchen.
Das x-privet-Token SOLLTE nur 24 Stunden lang gültig sein.

Selbst wenn ein Angreifer die API /privet/info ausführen kann, kann er das x-privet-Token nicht aus der Antwort lesen und daher keine andere API aufrufen.

Es wird dringend empfohlen, das XSRF-Token mit dem folgenden Algorithmus zu generieren:

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

Elemente für die XSRF-Token-Generierung:

DELIMITER ist ein Sonderzeichen, in der Regel „:“
issue_timecounter ist die Anzahl der Sekunden seit einem Ereignis (Epoche für Zeitstempel) oder der Startzeit des Geräts (für CPU-Zähler). issue_timecounter nimmt ständig zu, wenn das Gerät in Betrieb ist (siehe Token-Bestätigung unten).
SHA1: Hash-Funktion mit dem SHA1-Algorithmus
base64: Base64-Codierung
device_secret: Gerätespezifisches Secret. Das Gerätesecret MUSS bei jedem Neustart aktualisiert werden.

Empfohlene Methoden zum Generieren eines Gerätesecrets:

Bei jedem Neustart eine neue UUID generieren
Bei jedem Neustart eine 64‑Bit-Zufallszahl generieren

Das Gerät muss nicht alle XSRF-Tokens speichern, die es ausgestellt hat. Wenn das Gerät ein XSRF-Token auf Gültigkeit prüfen muss, sollte es das Token base64-decodieren. Rufen Sie den issue_timecounter aus der zweiten Hälfte (Klartext) ab und versuchen Sie, den SHA1-Hash von device_secret + DELIMITER + issue_timecounter zu erstellen, wobei issue_timecounter aus dem Token stammt. Wenn der neu generierte SHA1 mit dem im Token übereinstimmt, muss das Gerät jetzt prüfen, ob der issue_timecounter innerhalb des Gültigkeitszeitraums (24 Stunden) des aktuellen Zeitcounters liegt. Dazu wird der aktuelle Zeitcounter (z. B. der CPU-Counter) genommen und issue_timecounter davon subtrahiert. Das Ergebnis MUSS die Anzahl der Sekunden seit der Ausstellung des Tokens sein.

Wichtig:Dies ist die empfohlene Methode zum Implementieren des XSRF-Schutzes. Clients der Privet-Spezifikation sollten nicht versuchen, das XSRF-Token zu verstehen, sondern es als Blackbox behandeln. Abbildung 6.2.3 zeigt eine empfohlene Methode zum Implementieren des X-Privet-Tokens und zum Überprüfen einer typischen Anfrage.

6.2.3 Sequenzdiagramm für die Erstellung und Bestätigung von X-Privet-Tokens

6.3. Workflow-Diagramme

In diesem Abschnitt wird ein Workflow in verschiedenen Fällen veranschaulicht.

6.3.1. Workflow für die Einrichtung eines Druckers

6.3.2. Registrierter Druckerstart

6.3.3 Workflow für die Verarbeitung von XMPP-Benachrichtigungen

6.3.4. Workflow für Druckereinstellungen prüfen

Liguster Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

1. Einführung

2. Discovery

2.1. Diensttyp

2.2. TXT‑Eintrag

2.2.1. txtvers

2.2.2. ty

2.2.3. note (optional)

2.2.4. url

2.2.5. type

2.2.6. id

2.2.7. cs

3. Ankündigungen

3.1. Starten

3.2 Herunterfahren

3.3 Aktualisieren

4. API

4.1. API-Verfügbarkeit

4.1.1. Anmeldung

4.1.2. Starten

4.1.3. Aktualisieren

4.1.3.1. Ausstehende lokale Einstellungen

4.1.3.2. Aktuelle lokale Einstellungen

4.1.4. Offline

4.1.5. Gerät aus dem Dienst löschen

4.2. /privet/info API

4.2.1. Eingabe

4.2.2. Rückflug

4.2.3. Fehler

4.3. /privet/register API

4.3.1. Eingabe

4.3.2. Rückflug

4.3.3. Fehler

4.4. /privet/accesstoken API

4.4.1. Eingabe

4.4.2. Rückflug

4.4.3. Fehler

4.5. /privet/capabilities API

4.5.1. Eingabe

4.5.2. Rückflug

4.5.3. Fehler

4.6. Fehler

5. Printer API

5.1. /privet/printer/createjob API

5.1.1. Eingabe

5.1.2. Rückflug

5.1.3. Fehler

5.2. /privet/printer/submitdoc API

5.2.1. Eingabe

5.2.2. Rückflug

5.2.3. Fehler

5.3. /privet/printer/jobstate API

5.3.1. Eingabe

5.3.2. Rückflug

5.3.3. Fehler

6. Anhang

6.1. Standardverhalten und ‑einstellungen

6.1.2 Standardregistrierungsdiagramm

6.2. XSSI- und XSRF-Angriffe und Schutzmaßnahmen

6.2.1. XSSI

6.2.2. XSRF

6.2.3 Sequenzdiagramm für die Erstellung und Bestätigung von X-Privet-Tokens

6.3. Workflow-Diagramme

6.3.1. Workflow für die Einrichtung eines Druckers

6.3.2. Registrierter Druckerstart

6.3.3 Workflow für die Verarbeitung von XMPP-Benachrichtigungen

6.3.4. Workflow für Druckereinstellungen prüfen

Liguster