// 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 writeInfo.bytesWritten.", "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 tcp or udp.", "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, connect 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, disconnect 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 writeComplete 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." } ] } ]