CheckForUpdates

Die API /osc/checkForUpdates ermittelt Zustandsaktualisierungen durch einen Vergleich des letzten bekannten Client-stateFingerprint mit dem aktuellen fingerprint der Kamera.

Eingabe

Name Typ Beschreibung
stateFingerprint Zeichenfolge Fingerabdruck des Kamerazustands zum Zeitpunkt des letzten Clientaufrufs von /osc/state oder /osc/checkForUpdates.
waitTimeout Ganzzahl (optional) Gibt an, wie viele Sekunden auf eine Änderung des Kamerazustands gewartet werden soll, bevor die Antwort zurückgegeben wird. Nach Ablauf von waitTimeout sollte die Kamera eine Antwort zurückgeben, auch wenn der Fingerabdruck unverändert ist. Wenn eine Zustandsänderung vor Ablauf von waitTimeout erkannt wird oder waitTimeout nicht angegeben ist, sollte die Kamera die Antwort sofort zurückgeben.Hinweis: Die Kamera im Falle eines unveränderten Fingerabdrucks kann auch eine Antwort vor Ablauf von waitTimeout zurückgeben, das bewährte Verfahren ist jedoch, bis zum Ablauf von waitTimeout zu warten.

Hinweise zur Kameraimplementierung:

  • Beim Eingang dieses Aufrufs wird in der Kamera der aktuelle Zustandsfingerabdruck mit dem erhaltenen Parameter stateFingerprint verglichen. Wenn der Fingerabdruck sich verändert hat, muss der neue Fingerabdruck sofort von der Kamera zurückgegeben werden.

Ausgabe

Name Typ Beschreibung
stateFingerprint Zeichenfolge Der neue Fingerabdruck des Kamerazustands (identisch mit dem Wert in der API /osc/state).
throttleTimeout Ganzzahl Empfohlene Anzahl Sekunden, die der Client vor dem nächsten Aufruf von checkForUpdates warten soll. Clients können Anforderungen vor Ablauf von throttleTimeout stellen, und in den Kameras sollten diese Anforderungen nach Möglichkeit zulässig sein.

Hinweise zur Clientimplementierung:

  • Beim Eingang einer Antwort sollte der erhaltene Wert von stateFingerprint im Client mit seiner Kopie abgeglichen werden. Stimmen die Werte nicht überein, sollte vom Client mithilfe der API _/osc/state der aktuelle Zustand der Kamera angefordert werden.
  • Intelligente Clients begrenzen Anforderungen unabhängig von der Kameraantwort. Wenn von einer Kamera beispielsweise eine nicht dem Standard entsprechende Antwort zurückgegeben wird (sofort, mit dem Wert keine Änderung und mit einem niedrigen Wert oder Wert null für throttleTimeout)) sollte vom Client ein eigener throttleTimeout erzwungen werden, bevor checkForUpdates erneut von der Kamera angefordert wird.

Hinweise zur Kameraimplementierung:

  • Beim Senden einer Antwort auf checkForUpdates sollte von der Kamera ein angemessener Wert für throttleTimeout festgelegt werden. Wenn von der Kamera eine Logik für lange Daueranforderungen unterstützt wird (Antwort erst nach waitTimeout, wenn der Zustand unverändert ist), ist es OK, throttleTimeout mit dem Wert 0 zurückzugeben. In diesem Fall können Clients Aktualisierungen sofort anfordern.
  • Wenn von der Kamera nur schnelle Antworten unterstützt werden (nicht empfohlen), sollte von der Kamera ein angemessener throttleTimeout zurückgegeben werden, um einen ununterbrochenen Anforderungs-/Antwortverkehr mit dem Client zu vermeiden. Ein angemessener Wert für throttleTimeout wären beispielsweise 60 Sekunden, um eine Clientanforderung pro Minute zuzulassen.
  • Die bewährte Methode ist die Rückgabe eines Wertes für throttleTimeout, der an die Kameraleistung angepasst ist. Wenn vom Server aufgrund von Serverproblemen kein angemessener Wert für throttleTimeout ermittelt werden kann, sollte die Kameraantwort in Form eines Statuscodes 5XX und eines JSON-Textkörpers mit dem Fehlercode serverError erfolgen.

Fehler

Fehlercode Beschreibung
missingParameter stateFingerprint ist nicht angegeben.
invalidParameterName Mindestens ein Eingabeparameter wurde nicht erkannt.
invalidParameterValue Die Parameternamen wurden erkannt, aber mindestens ein Wert ist unzulässig; beispielsweise liegt waitTimeout außerhalb des zulässigen Bereichs, oder sein Typ ist nicht korrekt.
serverError Vom Server konnte kein angemessener Wert throttleTimeout für seine Antwort ermittelt werden. Das Serverproblem wird in der Antwort durch den Wert 5XX gekennzeichnet. Kamerahersteller sollten eine Tabelle mit 5XX-Codes und den entsprechenden Serverzuständen, die diesen Fehler auslösen können, bereitstellen.

Beispiel
Anforderung 
POST /osc/checkForUpdates HTTP/1.1
Host: [camera ip address]:[httpUpdatesPort]
Content-Type: application/json;charset=utf-8
Accept: application/jsonContent-Length: {CONTENT_LENGTH}
X-XSRF-Protected: 1

{
    "stateFingerprint": "12EGA33",
    "waitTimeout": 300
}
Antwort 
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
Content-Length: {CONTENT_LENGTH}
X-Content-Type-Options: nosniff

{
    "stateFingerprint": "12EGA86",
    "throttleTimeout": 60
}
Anforderung 
POST /osc/checkForUpdates HTTP/1.1
Host: [camera ip address]:[httpUpdatesPort]
Content-Type: application/json;charset=utf-8
Accept: application/jsonContent-Length: {CONTENT_LENGTH}
X-XSRF-Protected: 1

{
    "stateFingerprint": "12EGA33",
    "waitTimeout": 300
}
Antwort 
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=utf-8
Content-Length: {CONTENT_LENGTH}
X-Content-Type-Options: nosniff

{
    "name": "camera.checkForUpdates",
    "state": "error",
    "error": {
        "code": "missingParameter",
        "message": "parameter stateFingerprint is missing."
    }
}