Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

docs first draft

  • Loading branch information...
commit e2f9f15580894eee8f89728d60b032f8f98cf0be 1 parent 8ae567a
@ericz ericz authored
Showing with 141 additions and 0 deletions.
  1. +141 −0 docs/api.md
View
141 docs/api.md
@@ -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.
+
+
Please sign in to comment.
Something went wrong with that request. Please try again.