// Copyright (c) 2012 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": "experimental.socket",
    "nodoc": true,
    "types": [
      {
        "id": "SocketEvent",
        "type": "object",
        "description": "A socket event.",
        "properties": {
          "type": {
            "type": "string",
            "enum": ["connectComplete", "writeComplete", "dataRead"],
            "description": "A connectComplete event reports the result of a connect that blocked. A writeComplete event reports the result of a write that blocked. A dataRead event reports bytes that have arrived following a read call that blocked."
          },
          "resultCode": {
            "type": "integer",
            "description": "The result code, if the event type is writeComplete. The result code description matches that of <code>writeInfo.bytesWritten</code>.",
            "optional": true
          },
          "data": {
            "type": "string",
            "description": "The data read, if the event type is dataRead.",
            "optional": true
          },
          "isFinalEvent": {
            "type": "boolean",
            "description": "Whether this is the final event that this socket will send.",
            "nodoc": true
          },
          "srcId": {
            "type": "number",
            "description": "An ID unique to the calling function's context so that events can get routed back to the correct callback.",
            "nodoc": true,
            "optional": true
          }
        }
      }
    ],
    "functions": [
      {
        "name": "create",
        "type": "function",
        "description": "Creates a socket of the specified type that will connect to the specified remote machine.",
        "parameters": [
          {
            "name": "type",
            "type": "string",
            "description":
              "The type of socket to create. Must be <code>tcp</code> or <code>udp</code>.",
            "enum": ["tcp", "udp"]
          },
          {
            "name": "address",
            "type": "string",
            "description": "The address of the remote machine."
          },
          {
            "name": "port",
            "type": "integer",
            "description": "The port of the remote machine.",
            "minimum": 1,
            "maximum": 65535
          },
          {
            "type": "object",
            "name": "options",
            "optional": true,
            "description": "The socket options.",
            "properties": {
              "onEvent": {
                "type": "function",
                "optional": true,
                "description": "This function is called with events that occur during the lifetime of the socket.",
                "parameters": [
                  {
                    "name": "event",
                    "$ref": "SocketEvent",
                    "description": "The socket event."
                  }
                ]
              }
            }
          },
          {
            "name": "callback",
            "type": "function",
            "description": "Called when the socket has been created.",
            "parameters": [
              {
                "type": "object",
                "name": "socketInfo",
                "properties": {
                  "socketId": {
                    "type": "integer",
                    "minimum": 1,
                    "description": "The id of the newly created socket."
                  }
                }
              }
            ]
          }
        ]
      },
      {
        "name": "destroy",
        "type": "function",
        "description": "Destroys the socket. Each socket created should be destroyed after use.",
        "parameters": [
          {
            "name": "socketId",
            "type": "integer",
            "description": "The socketId.",
            "minimum": 1
          }
        ]
      },
      {
        "name": "connect",
        "type": "function",
        "description": "Connects the socket to the remote machine. For UDP sockets, <code>connect</code> is a non-operation but is safe to call.",
        "parameters": [
          {
            "name": "socketId",
            "type": "integer",
            "description": "The socketId.",
            "minimum": 1
          },
          {
            "name": "callback",
            "type": "function",
            "description": "Called when the connection attempt is complete.",
            "parameters": [
              {
                "type": "integer",
                "name": "result",
                "description": "Zero if connection was successful, negative otherwise (TODO: document error codes or switch to boolean). Always successful for UDP sockets."
              }
            ]
          }
        ]
      },
      {
        "name": "disconnect",
        "type": "function",
        "description": "Disconnects the socket. For UDP sockets, <code>disconnect</code> is a non-operation but is safe to call.",
        "parameters": [
          {
            "name": "socketId",
            "type": "integer",
            "description": "The socketId.",
            "minimum": 1
          }
        ]
      },
      {
        "name": "read",
        "type": "function",
        "description": "Reads data from the given socket.",
        "parameters": [
          {
            "name": "socketId",
            "type": "integer",
            "description": "The socketId.",
            "minimum": 1
          },
          {
            "name": "callback",
            "type": "function",
            "description": "Delivers data that was available to be read without blocking.",
            "parameters": [
              {
                "type": "object",
                "name": "readInfo",
                "properties": {
                  "message": {
                    "type": "string",
                    "description": "The data received. Warning: will probably become a blob or other appropriate binary-friendly type."
                  }
                }
              }
            ]
          }
        ]
      },
      {
        "name": "write",
        "type": "function",
        "description": "Writes data on the given socket.",
        "parameters": [
          {
            "name": "socketId",
            "type": "integer",
            "description": "The socketId.",
            "minimum": 1
          },
          {
            "name": "data",
            "type": "string",
            "description": "The data to write. Warning: will probably become a blob or other appropriate binary-friendly type."
          },
          {
            "name": "callback",
            "type": "function",
            "description": "Called when the first of any of the following happens: the write operation completes without blocking, the write operation blocked before completion (in which case onEvent() will eventually be called with a <code>writeComplete</code> event), or an error occurred.",
            "parameters": [
              {
                "type": "object",
                "name": "writeInfo",
                "properties": {
                  "bytesWritten": {
                    "type": "integer",
                    "description": "The number of bytes sent, or a negative error code."
                  }
                }
              }
            ]
          }
        ]
      }
    ],
    "events": [
      {
        "name": "onEvent",
        "type": "function",
        "nodoc": true,
        "parameters": [
          {
            "name": "event",
            "$ref": "SocketEvent",
            "description": "The event indicating socket status."
          }
        ],
        "description": "Used to pass events back to the socket creator."
      }
    ]
  }
]