CheckForUpdates

L'API /osc/checkForUpdates détecte les modifications de statut en comparant le dernier paramètre stateFingerprint connu du client avec le paramètre fingerprint actuel de l'appareil photo.

Entrée

Nom Type Description
stateFingerprint Chaîne Empreinte de statut de l'appareil photo depuis le dernier appel du client à /osc/state ou /osc/checkForUpdates.
waitTimeout Entier (facultatif) Nombre de secondes d'attente de la modification du statut sur l'appareil photo avant de renvoyer la réponse. Lorsque le délai waitTimeout expire, l'appareil photo doit renvoyer une réponse même si l'empreinte n'a pas changé. Si une modification de statut est identifiée avant l'expiration du délai waitTimeout ou si le paramètre waitTimeout est ignoré, l'appareil photo doit renvoyer immédiatement la réponse.Remarque : l'appareil photo peut renvoyer une réponse avant l'expiration du délai waitTimeout même si l'empreinte n'a pas changé, mais il est recommandé d'attendre l'expiration du délai waitTimeout.

Remarques sur l'implémentation de l'appareil photo :

  • À la réception de cet appel, l'appareil photo compare son empreinte de statut actuelle avec le paramètre stateFingerprint reçu. Si l'empreinte a changé, elle doit renvoyer immédiatement la nouvelle empreinte.

Sortie

Nom Type Description
stateFingerprint Chaîne Nouvelle empreinte de statut de l'appareil photo (comme dans l'API /osc/state).
throttleTimeout Entier Nombre de secondes d'attente recommandé avant le prochain appel à checkForUpdates. Les clients peuvent lancer des requêtes avant l'expiration du délai throttleTimeout et les appareils photos doivent permettre ces requêtes anticipées, si possible.

Remarques sur l'implémentation du client :

  • À la réception d'une réponse, le client doit comparer le paramètre stateFingerprint reçu avec sa copie. S'ils diffèrent, le client doit demander le statut actuel de l'appareil photo à l'aide de l'API _/osc/state.
  • Les clients intelligents envoient des requêtes, quelle que soit la réponse de l'appareil photo. Par exemple, si un appareil photo renvoie une réponse non standard (immédiatement, avec aucune modification et une valeur faible ou 0 pour le paramètre throttleTimeout)), le client doit imposer son propre paramètre throttleTimeout avant d'envoyer une autre requête checkForUpdates à l'appareil photo.

Remarques sur la mise en œuvre de l'appareil photo :

  • En réponse à la requête checkForUpdates, l'appareil photo doit déterminer un paramètre throttleTimeout raisonnable. Si l'appareil photo prend en charge la logique de requête longue (répondre uniquement après le délai waitTimeout si le statut n'a pas changé), il est possible de renvoyer throttleTimeout avec la valeur 0. Dans ce cas, les clients peuvent demander immédiatement des mises à jour.
  • Si l'appareil photo prend en charge uniquement les réponses rapides (non recommandé), il doit renvoyer un paramètre throttleTimeout raisonnable afin d'éviter un trafic requête/réponse permanent avec le client. Par exemple, un paramètre throttleTimeout raisonnable de 60 secondes permet une requête client par minute.
  • Il est recommandé de renvoyer un paramètre throttleTimeout correspondant aux capacités de l'appareil photo. Si le serveur ne peut pas déterminer un paramètre throttleTimeout approprié en raison d'une erreur serveur, l'appareil photo doit répondre avec un code de statut 5XX et un message JSON contenant un code d'erreur serverError.

Erreur

Code d'erreur Description
missingParameter stateFingerprint n'est pas spécifié.
invalidParameterName Un ou plusieurs noms de paramètre d'entrée sont inconnus.
invalidParameterValue Les noms de paramètre sont reconnus, mais une ou plusieurs valeurs ne sont pas valides, par exemple, waitTimeout est hors limites ou son type est incorrect.
serverError Le serveur n'a pu déterminer aucune valeur throttleTimeout appropriée pour sa réponse. L'erreur serveur est identifiée par la valeur 5XX renvoyée dans la réponse. Les fabricants d'appareils photo doivent fournir une liste des codes 5XX et des statuts de serveur correspondants susceptibles de renvoyer cette erreur.

Exemple
Requête 
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
}
Réponse 
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
}
Requête 
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
}
Réponse 
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."
    }
}