CheckForUpdates

A /osc/checkForUpdates API identifica atualizações de estado comparando a última stateFingerprint do cliente à fingerprint atual da câmera.

Entrada

Nome Tipo Descrição
stateFingerprint String Impressão digital do estado da câmera desde a última vez que o cliente chamou /osc/state ou /osc/checkForUpdates.
waitTimeout Número inteiro (opcional) O número de segundos a serem aguardados para a alteração do estado da câmera antes de retornar a resposta. Quando waitTimeout expira, a câmera deve retornar uma resposta mesmo que a impressão digital não tenha sido alterada. Se uma mudança de estado for detectada antes da expiração de waitTimeout ou se waitTimeout for omitido, a câmera deverá retornar a resposta imediatamente.Observação: a câmera pode retornar uma resposta antes da expiração de waitTimeout mesmo que a impressão digital não tenha sido alterada, mas é recomendável aguardar até que waitTimeout expire.

Observações de implementação da câmera:

  • Ao receber essa chamada, a câmera a compara à impressão digital do estado atual com o parâmetro stateFingerprint recebido. Se a impressão digital tiver sido alterada, a câmera deverá retornar a nova impressão digital imediatamente.

Saída

Nome Tipo Descrição
stateFingerprint String Nova impressão digital do estado da câmera (a mesma da /osc/state API).
throttleTimeout Número inteiro Número recomendado de segundos que o cliente deve aguardar antes da próxima chamada de checkForUpdates. Os clientes podem fazer chamadas antes da expiração do throttleTimeout e as câmeras devem permitir essas solicitações antecipadas, se possível.

Observações de implementação do cliente:

  • Ao receber uma resposta, o cliente deve comparar a stateFingerprint recebida com sua cópia. Se os valores não corresponderem, o cliente deve solicitar o estado atual da câmera usando a _/osc/state API.
  • Clientes inteligentes usam solicitações de limitação independentemente da resposta da câmera. Por exemplo, se uma câmera retornar uma resposta não padrão (imediatamente sem alterações e com um throttleTimeout) baixo ou de 0), o cliente deve impor o próprio throttleTimeout antes de solicitar outro checkForUpdates da câmera.

Observações de implementação da câmera:

  • Ao responder a checkForUpdates, a câmera deve determinar um throttleTimeout razoável. Se a câmera é compatível com lógica de solicitação de longa data (responder somente após waitTimeout se o estado não tiver sido alterado), é possível retornar throttleTimeout como 0. Nesse caso, os clientes podem solicitar atualizações imediatamente.
  • Se a câmera é compatível apenas com respostas rápidas (não recomendável), ela deve retornar um throttleTimeout razoável para evitar um tráfego constante de solicitações/respostas para o cliente. Por exemplo, um throttleTimeout seria 60 segundos, para permitir que o cliente envie uma solicitação por minuto.
  • A prática recomendada é retornar um throttleTimeout apropriado para os recursos da câmera. Se o servidor não puder determinar um throttleTimeout apropriado devido a um problema, a câmera deverá responder com um código de status 5XX e um corpo JSON contendo o código de erro serverError.

Erro

Código de erro Descrição
missingParameter stateFingerprint não foi especificado.
invalidParameterName Um ou mais nomes de parâmetros de entrada não foram reconhecidos.
invalidParameterValue Os nomes dos parâmetros foram reconhecidos, mas um ou mais valores são inválidos. Por exemplo, waitTimeout está fora do intervalo permitido ou seu tipo está incorreto.
serverError O servidor não conseguiu determinar um valor de throttleTimeout apropriado para sua resposta. O problema do servidor será identificado pelo valor 5XX retornado na resposta. Fabricantes de câmeras devem fornecer uma tabela de códigos 5XX e os estados de servidor correspondentes que podem acionar esse erro.

Exemplo
Solicitação 
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
}
Resposta 
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
}
Solicitação 
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
}
Resposta 
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."
    }
}