|
|
@@ -0,0 +1,141 @@
|
|
|
+# PeerJS API Reference
|
|
|
+
|
|
|
+## Class: Peer
|
|
|
+
|
|
|
+This class is a the BinaryJS websocket server. It is an `EventEmitter`.
|
|
|
+
|
|
|
+### new peerjs.Peer([id], options)
|
|
|
+
|
|
|
+* `id` String. The id by which this peer will be identified when other peers try to connect to it. If no id is given, one will be generated by the server
|
|
|
+* `options` Object
|
|
|
+ * `key` String. API key for cloud PeerServer. Is not used for servers other than `cloud.peerjs.com`
|
|
|
+ * `host` String. Server host. Default `cloud.peerjs.com`
|
|
|
+ * `port` Number. Server port. Default `80`
|
|
|
+ * `config` Object. Configuration hash passed to `RTCPeerConnection`. This hash contains the ICE servers. Default `{ 'iceServers': [{ 'url': 'stun:stun.l.google.com:19302' }] }`
|
|
|
+ * `debug` Boolean. Prints verbose log messages. Default `false`
|
|
|
+
|
|
|
+Construct a new Peer object.
|
|
|
+
|
|
|
+The Peer object is used to connect to other Peer clients and also to receive connections from other clients.
|
|
|
+
|
|
|
+The first argument is the id that other peers will use to connect to this peer, thus it must be unique for the given `key` (if you're using PeerServer cloud) or server.
|
|
|
+
|
|
|
+In the options, either a PeerServer Cloud `key` must be provided or `host` and `port` for your own PeerServer. Note that the server is only for brokering connections and does not proxy data between peers.
|
|
|
+
|
|
|
+The `config` object is passed straight into instances of `RTCPeerConnection`. For compatibility with symmetric NATs, you can provide your own TURN server. By default the STUN server provided by Google is used.
|
|
|
+
|
|
|
+### peer.id
|
|
|
+
|
|
|
+The given id of this peer.
|
|
|
+
|
|
|
+If no id was specified in the constructor, this value will be `undefined` util the `open` event fires.
|
|
|
+
|
|
|
+### peer.connections
|
|
|
+
|
|
|
+A hash of all current connections with the current peer. Keys are ids and values are instances of `DataConnection`.
|
|
|
+
|
|
|
+### peer.connect(id, [meta])
|
|
|
+
|
|
|
+Connects to the remote peer specified by `id`.
|
|
|
+
|
|
|
+Returns a `DataConnection` object.
|
|
|
+
|
|
|
+* `id` String. The id of the remote peer to connect to
|
|
|
+* `meta` Optional metadata to pass to the remote peer. Can be any serializable type
|
|
|
+
|
|
|
+Before writing to / data will be emitted from the `DataConnection` object that is returned, the `open` event must fire. Also the `error` event should be checked in case a connection cannot be made.
|
|
|
+
|
|
|
+### peer.destroy()
|
|
|
+
|
|
|
+Close the server and terminate all connections.
|
|
|
+
|
|
|
+### Event: 'connection'
|
|
|
+
|
|
|
+`function (connection, meta) { }`
|
|
|
+
|
|
|
+When a new connection is established from another peer to this peer, the `DataConnection` object is emitted with this event. The `meta` argument contains whatever metadata values passed into `peer.connection(...)` by the remote peer.
|
|
|
+
|
|
|
+### Event: 'open'
|
|
|
+
|
|
|
+`function(id) { }`
|
|
|
+
|
|
|
+Fired when the PeerServer connection is fully open.
|
|
|
+This event does not need to fire before creating or receiving connections.
|
|
|
+
|
|
|
+`id` is the id of this `Peer` object, either provided in the constructor, or generated automatically by the PeerServer.
|
|
|
+
|
|
|
+### Event: 'error'
|
|
|
+
|
|
|
+`function (error) { }`
|
|
|
+
|
|
|
+Emitted when an unexpected event occurs. May or may not be fatal. This is the event emitted if you attempt to connect with an ID that is already being used.
|
|
|
+
|
|
|
+Errors from the underlying socket are forwarded here.
|
|
|
+
|
|
|
+### Event: 'close'
|
|
|
+
|
|
|
+`function (error) { }`
|
|
|
+
|
|
|
+Emitted when the Peer object has closed it's connection with PeerServer so no more remote peer connections can be made or received..
|
|
|
+
|
|
|
+## Class: peerjs.DataConnection
|
|
|
+
|
|
|
+This class is the interface two communicate between two peers. It is an `EventEmitter`.
|
|
|
+
|
|
|
+There is no constructor. A `DataConnection` object must be obtained in the callback of `peer.connect(...)` when initiating a peer-to-peer connection or emitted in the `peer.on('connection', ...)` event when receiving a connection.
|
|
|
+
|
|
|
+### connection.id
|
|
|
+
|
|
|
+The id of the local peer that this connection belongs to.
|
|
|
+
|
|
|
+### connection.peer
|
|
|
+
|
|
|
+The id of the remote peer this connection is connected to.
|
|
|
+
|
|
|
+### connection.open
|
|
|
+
|
|
|
+Whether the connection is open (ready for read and write).
|
|
|
+
|
|
|
+### connection.metadata
|
|
|
+
|
|
|
+The metadata passed in when the connection was created with `peer.connect(...)`.
|
|
|
+
|
|
|
+### connection.send(data)
|
|
|
+
|
|
|
+Accepts data of any JSON type or binary type.
|
|
|
+
|
|
|
+Data is serialized using BinaryPack and then sent to the remote peer.
|
|
|
+
|
|
|
+### connection.close()
|
|
|
+
|
|
|
+Gracefully closes the connection.
|
|
|
+
|
|
|
+### Event: 'data'
|
|
|
+
|
|
|
+`function (data) { }`
|
|
|
+
|
|
|
+Emitted when data is received from the remote peer.
|
|
|
+
|
|
|
+The `data` parameter contains values exactly as put into the `connection.send(...)`. Binary types will have been deserialized to `ArrayBuffer`.
|
|
|
+
|
|
|
+### Event: 'open'
|
|
|
+
|
|
|
+`function () { }`
|
|
|
+
|
|
|
+Emitted when the connection is established.
|
|
|
+
|
|
|
+### Event: 'error'
|
|
|
+
|
|
|
+`function (error) { }`
|
|
|
+
|
|
|
+If the client emits an error, this event is emitted (errors from the underlying `RTCPeerConnection` and `DataChannel` are forwarded here).
|
|
|
+
|
|
|
+### Event: 'close'
|
|
|
+
|
|
|
+`function () { }`
|
|
|
+
|
|
|
+Is emitted when the connection is closed.
|
|
|
+
|
|
|
+The `close` event is also emitted when the remote peer closes the connection.
|
|
|
+
|
|
|
+
|
ericz