// Copyright 2013 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

[
  {
    "namespace": "gcm",
    "description": "Use <code>chrome.gcm</code> to enable apps and extensions to send and receive messages through <a href='http://developer.android.com/google/gcm/index.html'>Google Cloud Messaging for Android</a>.",
    "properties": {
      "MAX_MESSAGE_SIZE": {
        "value": 4096,
        "description": "The maximum size (in bytes) of all key/value pairs in a message."
      }
    },
    "functions": [
      {
        "name": "register",
        "type": "function",
        "description": "Registers the application with GCM. The registration ID will be returned by the <code>callback</code>. If <code>register</code> is called again with the same list of <code>senderIds</code>, the same registration ID will be returned.",
        "parameters": [
          {
            "name": "senderIds",
            "type": "array",
            "items": { 
              "type": "string",
              "minLength": 1
            },
            "minItems": 1,
            "maxItems": 100,
            "description": "A list of server IDs that are allowed to send messages to the application. It should contain at least one and no more than 100 sender IDs."
          },
          {
            "name": "callback",
            "type": "function",
            "description": "Function called when registration completes. It should check $ref:runtime.lastError for error when <code>registrationId</code> is empty.",
            "parameters": [
              { 
                "name": "registrationId",
                "type": "string",
                "description": "A registration ID assigned to the application by the GCM."
              }
            ]
          }
        ]
      },
      {
        "name": "send",
        "type": "function",
        "description": "Sends a message according to its contents.",
        "parameters": [
          {
            "name": "message",
            "type": "object",
            "description": "A message to send to the other party via GCM.",
            "properties": {
              "destinationId": {
                "type": "string",
                "minLength": 1,
                "description": "The ID of the server to send the message to as assigned by <a href='https://code.google.com/apis/console'>Google API Console</a>."
              },
              "messageId": {
                "type": "string",
                "minLength": 1,
                "description": "The ID of the message. It must be unique for each message."
              },
              "timeToLive": {
                "type": "integer",
                "minimum": 0,
                "maximum": 2419200,
                "optional": true,
                "description": "Time-to-live of the message in seconds. If it is not possible to send the message wihtin that time an error will be raised. A time-to-live of 0 indicates that the message should be sent immediately or fail if it's not possible. The maximum and a default value of time-to-live is 2419200 seconds (4 weeks)."
              },
              "data": {
                "type": "object",
                "properties": {},
                "additionalProperties": {
                  "type": "string",
                  "minLength": 1
                },
                "description": "Message data to send to the server. <code>goog.</code> and <code>google</code> are disallowed as key prefixes. Sum of all key/value pairs should not exceed $ref:MAX_MESSAGE_SIZE."
              }
            }
          },
          {
            "name": "callback",
            "type": "function",
            "description": "A function called after the message is successfully queued for sending. $ref:runtime.lastError should be checked, to ensure a message was sent without problems.",
            "parameters": [
              {
                "name": "messageId",
                "type": "string",
                "description": "The ID of the message that the callback was issued for."
              }
            ]
          }
        ]
      }
    ],
    "events": [
      {
        "name": "onMessage",
        "type": "function",
        "description": "Fired when a message is received through GCM.",
        "parameters": [
          { 
            "name": "message",
            "type": "object",
            "description": "A message received from another party via GCM.",
            "properties": {
              "data": {
                "type": "object",
                "properties": {},
                "additionalProperties": {
                  "type": "string"
                },
                "description": "The message data."
              }
            }
          }
        ]
      },
      {
        "name": "onMessagesDeleted",
        "type": "function",
        "description": "Fired when a GCM server had to delete messages to the application from its queue in order to manage its size. The app is expected to handle that case gracefully, e.g. by running a full sync with its server."
      },
      {
        "name": "onSendError",
        "type": "function",
        "description": "Fired when it was not possible to send a message to the GCM server.",
        "parameters": [
          {
            "name": "error",
            "type": "object",
            "description": "An error related to sending a message raised by GCM.",
            "properties": {
              "errorMessage": {
                "type": "string",
                "description": "The error message describing the problem."
              },
              "messageId": {
                "type": "string",
                "optional": true,
                "description": "The ID of the message with this error, if error is related to a specific message."
              },
              "details": {
                "type": "object",
                "properties": {},
                "additionalProperties": {
                  "type": "string"
                },
                "description": "Additional details related to the error, when available."
              }
            },
            "description": "An error that occured while trying to send the message either in Chrome or on the GCM server. Application can retry sending the message with a reasonable backoff and possibly longer time-to-live."
          }
        ]
      }
    ]
  }
]