|
|
@@ -6,210 +6,168 @@
|
|
|
<body>
|
|
|
<section class="api">
|
|
|
|
|
|
- <h1>PeerJS API Reference</h1>
|
|
|
+ <h2>API Reference</h2>
|
|
|
|
|
|
-<p><strong>Due to browsers' incomplete support of the WebRTC DataChannel specification, many features of PeerJS have caveats.
|
|
|
-<a href="http://peerjs.com/status">View the status page for full details</a>.</strong></p>
|
|
|
+ <div class="peer toplevel">
|
|
|
+ <h3>
|
|
|
+ Peer
|
|
|
+ <span class="labels">
|
|
|
+ <span class="label class">class</span>
|
|
|
+ </span>
|
|
|
+ <span class="snippet">var peer = new Peer([id], [options]);</span>
|
|
|
+ </h3>
|
|
|
|
|
|
-<ul><li><a href="#class-peerjspeer">Class: peerjs.Peer</a><ul><li><a href="#new-peerid-options">new Peer([id], [options])</a></li><li><a href="#peerbrowser">Peer.browser</a></li><li><a href="#peerid">peer.id</a></li><li><a href="#peerconnections">peer.connections</a></li><li><a href="#peerconnectid-options">peer.connect(id, [options])</a></li><li><a href="#peerdestroy">peer.destroy()</a></li><li><a href="#peerdisconnect">peer.disconnect()</a></li><li><a href="#peerdisconnected">peer.disconnected</a></li><li><a href="#peerdestroyed">peer.destroyed</a></li><li><a href="#event-connection">Event: 'connection'</a></li><li><a href="#event-open">Event: 'open'</a></li><li><a href="#event-error">Event: 'error'</a></li><li><a href="#event-close">Event: 'close'</a></li></ul></li><li><a href="#class-peerjsdataconnection">Class: peerjs.DataConnection</a><ul><li><a href="#experimental-reliable-and-large-file-transfer">EXPERIMENTAL reliable and large file transfer:</a></li><li><a href="#connectionpeer">connection.peer</a></li><li><a href="#connectionopen">connection.open</a></li><li><a href="#connectionmetadata">connection.metadata</a></li><li><a href="#connectionlabel">connection.label</a></li><li><a href="#connectionserialization">connection.serialization</a></li><li><a href="#connectionsenddata">connection.send(data)</a></li><li><a href="#connectionclose">connection.close()</a></li><li><a href="#event-data">Event: 'data'</a></li><li><a href="#event-open-1">Event: 'open'</a></li><li><a href="#event-error-1">Event: 'error'</a></li><li><a href="#event-close-1">Event: 'close'</a></li></ul></li></ul>
|
|
|
-
|
|
|
-<h2>Class: peerjs.Peer</h2>
|
|
|
-
|
|
|
-<p>This class is a Peer, which can connect to other peers and listen for connections. It is an <code>EventEmitter</code>.</p>
|
|
|
-
|
|
|
-<h3>new Peer([id], [options])</h3>
|
|
|
-
|
|
|
-<ul><li><code>id</code> 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. <strong>Note that this ID is mainly used for brokering and that it is not recommended that you use it to identify peers. Also note that you can set a <code>metadata</code> option to send other identifying information.</strong></li><li><code>options</code> Object<ul><li><code>key</code> String. API key for cloud PeerServer. Is not used for servers other than <code>cloud.peerjs.com</code></li><li><code>host</code> String. Server host. Default <code>cloud.peerjs.com</code>. Also accepts <code>'/'</code> for relative hostname.</li><li><code>port</code> Number. Server port. Default <code>80</code></li><li><code>config</code> Object. Configuration hash passed to <code>RTCPeerConnection</code>. This hash contains the ICE servers. Default <code>{ 'iceServers': [{ 'url': 'stun:stun.l.google.com:19302' }] }</code></li><li><code>debug</code> Boolean. Prints verbose log messages. Default <code>false</code> </li></ul></li></ul>
|
|
|
-
|
|
|
-<p>Construct a new Peer object.</p>
|
|
|
-
|
|
|
-<p>The Peer object is used to connect to other Peer clients and also to receive connections from other clients.</p>
|
|
|
-
|
|
|
-<p>The first argument is the id that other peers will use to connect to this peer, thus it must be unique for the given <code>key</code> (if you're using PeerServer cloud) or server.</p>
|
|
|
-
|
|
|
-<p>In the options, either a PeerServer Cloud <code>key</code> must be provided or <code>host</code> and <code>port</code> for your own PeerServer. <strong>Note that the server is only for brokering connections and does not proxy data between peers.</strong></p>
|
|
|
-
|
|
|
-<p>The <code>config</code> object is passed straight into instances of <code>RTCPeerConnection</code>. For compatibility with symmetric NATs, you can provide your own TURN server. By default the STUN server provided by Google is used.</p>
|
|
|
-
|
|
|
-<h3>Peer.browser</h3>
|
|
|
-
|
|
|
-<p>The type of browser the client is on. Currently WebRTC DataChannels are not
|
|
|
-interoperable so different browser types should not be connected.</p>
|
|
|
-
|
|
|
-<h3>peer.id</h3>
|
|
|
-
|
|
|
-<p>The given id of this peer.</p>
|
|
|
-
|
|
|
-<p>If no id was specified in the constructor, this value will be <code>undefined</code> util the <code>open</code> event fires.</p>
|
|
|
-
|
|
|
-<h3>peer.connections</h3>
|
|
|
-
|
|
|
-<p>A hash of all current connections with the current peer. Keys are ids and values are hashes of label => <code>DataConnection</code> pairs.</p>
|
|
|
-
|
|
|
-<p><strong>You are recommended to keep track of connections yourself rather than to manipulate this hash.</strong></p>
|
|
|
-
|
|
|
-<h3>peer.connect(id, [options])</h3>
|
|
|
-
|
|
|
-<p>Connects to the remote peer specified by <code>id</code>.</p>
|
|
|
-
|
|
|
-<p>This function can be called multiple times for multiplexed connections between
|
|
|
-two peers. In Firefox however this functionality is only available before the
|
|
|
-first connection is established.</p>
|
|
|
-
|
|
|
-<p>Returns a <code>DataConnection</code> object.</p>
|
|
|
-
|
|
|
-<ul><li><code>id</code> String. The id of the remote peer to connect to.</li><li><code>options</code> Object.<ul><li><code>label</code> Optional label for the underlying DataChannel, to differentiate between DataConnections between the same two peers. If left unspecified, a label will be assigned at random.</li><li><code>metadata</code> Optional metadata to pass to the remote peer. Can be any serializable type.</li><li><code>serialization</code> String, which can be <code>binary</code>, <code>binary-utf8</code>, <code>json</code>, or <code>none</code>. This will be the serialization format of all data sent over the P2P DataConnection. Defaults to <code>binary</code>.</li><li><code>reliable</code> Boolean, which if <code>true</code> activates experimental reliable transfer in Chrome (while waiting for actual reliable transfer to be implemented in Chrome). Defaults to <code>false</code> until Chrome implements reliable/large data transfer. Defaults to true in Firefox.</li></ul></li></ul>
|
|
|
-
|
|
|
-<p>Before writing to / data will be emitted from the <code>DataConnection</code> object that is returned, the <code>open</code> event must fire. Also the <code>error</code> event should be checked in case a connection cannot be made.</p>
|
|
|
-
|
|
|
-<h3>peer.destroy()</h3>
|
|
|
-
|
|
|
-<p>Close the connection to the server and terminate all connections.</p>
|
|
|
-
|
|
|
-<p><strong>Warning: This cannot be undone; the respective peer object will no longer be able to create or receive any connections and its ID will be forfeited on the (cloud) server.</strong></p>
|
|
|
-
|
|
|
-<h3>peer.disconnect()</h3>
|
|
|
-
|
|
|
-<p>Close the connection to the server, leaving all existing DataConnections intact.</p>
|
|
|
-
|
|
|
-<p><strong>Warning: This cannot be undone; the respective peer object will no longer be able to create or receive any connections and its ID will be forfeited on the (cloud) server.</strong></p>
|
|
|
-
|
|
|
-<h3>peer.disconnected</h3>
|
|
|
-
|
|
|
-<p>Is false if there is an active connection to the PeerServer.</p>
|
|
|
-
|
|
|
-<h3>peer.destroyed</h3>
|
|
|
-
|
|
|
-<p>Is true if this peer is destroyed and can no longer be used.</p>
|
|
|
-
|
|
|
-<h3>Event: 'connection'</h3>
|
|
|
-
|
|
|
-<p><code>function (connection, meta) { }</code></p>
|
|
|
-
|
|
|
-<p>When a new connection is established from another peer to this peer, the <code>DataConnection</code> object is emitted with this event. The <code>meta</code> argument contains whatever metadata values passed into <code>peer.connection(...)</code> by the remote peer.</p>
|
|
|
-
|
|
|
-<p><strong>Note:</strong> the <code>open</code> event must fire on the <code>DataConnection</code> before it is ready to read/write.</p>
|
|
|
-
|
|
|
-<h3>Event: 'open'</h3>
|
|
|
-
|
|
|
-<p><code>function(id) { }</code></p>
|
|
|
-
|
|
|
-<p>Fired when the PeerServer connection is succesfully, fully, open.
|
|
|
-This event does not need to fire before creating or receiving connections.
|
|
|
-<strong>You should not wait for open before connecting to other peers or expecting to receive connections if connection speed is important.</strong></p>
|
|
|
-
|
|
|
-<p><code>id</code> is the id of this <code>Peer</code> object, either provided in the constructor, or generated automatically by the PeerServer.</p>
|
|
|
-
|
|
|
-<h3>Event: 'error'</h3>
|
|
|
-
|
|
|
-<p><code>function (error) { }</code></p>
|
|
|
-
|
|
|
-<p>Emitted when an unexpected event occurs. Errors on the Peer are <strong>always
|
|
|
-fatal</strong>. Errors from the underlying socket and PeerConnections are forwarded here.</p>
|
|
|
-
|
|
|
-<p>The <code>error</code> object also has a <code>type</code> parameter that may be helpful in responding to client errors properly:
|
|
|
-<em> <code>browser-incompatible</code>: The client's browser does not support some or all WebRTC features that you are trying to use.
|
|
|
-</em> <code>invalid-id</code>: The ID passed into the Peer constructor contains illegal characters.
|
|
|
-<em> <code>invalid-key</code>: The API key passed into the Peer constructor contains illegal characters or is not in the system (cloud server only).
|
|
|
-</em> <code>unavailable-id</code>: The ID passed into the Peer constructor is already taken.
|
|
|
-<em> <code>firefoxism</code>: The operation you're trying to perform is not supported in firefox.
|
|
|
-</em> <code>ssl-unavailable</code>: PeerJS is being used securely, but the cloud server does not support SSL. Use a custom PeerServer.
|
|
|
-<em> Errors types that shouldn't regularly appear:
|
|
|
- </em> <code>server-error</code>: Unable to reach the server.
|
|
|
- <em> <code>socket-error</code>: An error from the underlying socket.
|
|
|
- </em> <code>socket-closed</code>: The underlying socket closed unexpectedly.
|
|
|
-<em> (The Peer object is destroyed after one of the errors above are emitted.)
|
|
|
-</em> <code>server-disconnected</code>: A Peer that has been disconnected is being used to try to connect.</p>
|
|
|
-
|
|
|
-<h3>Event: 'close'</h3>
|
|
|
-
|
|
|
-<p><code>function () { }</code></p>
|
|
|
-
|
|
|
-<p>Emitted when the Peer object has closed its connection with PeerServer so no more remote peer connections can be made or received.</p>
|
|
|
-
|
|
|
-<p>To be extra certain that Peer objects clean up cleanly (and because it takes the WS server and DataChannel some time to realize that a Peer has disconnected), it is best to call <code>destroy()</code> on a Peer when it is no longer needed.</p>
|
|
|
-
|
|
|
-<h2>Class: peerjs.DataConnection</h2>
|
|
|
-
|
|
|
-<p>This class is the interface two communicate between two peers. It is an <code>EventEmitter</code>.</p>
|
|
|
-
|
|
|
-<p>There is no constructor. A <code>DataConnection</code> object must be obtained in the callback of <code>peer.connect(...)</code> when initiating a peer-to-peer connection or emitted in the <code>peer.on('connection', ...)</code> event when receiving a connection.</p>
|
|
|
-
|
|
|
-<h3>EXPERIMENTAL reliable and large file transfer:</h3>
|
|
|
-
|
|
|
-<p>(CHROME ONLY. Firefox has reliable transport built in and reliable transfer is the default option.) Simply pass in <code>reliable: true</code> when calling <code>.connect(...)</code>. This module is experimental, temporary, and exists here: https://github.com/michellebu/reliable</p>
|
|
|
-
|
|
|
-<p><em>Caveat:</em> With reliable enabled in Chrome, you can no longer customize the serialization format used for data transfer.</p>
|
|
|
-
|
|
|
-<h3>connection.peer</h3>
|
|
|
-
|
|
|
-<p>The id of the remote peer this connection is connected to.</p>
|
|
|
-
|
|
|
-<h3>connection.open</h3>
|
|
|
-
|
|
|
-<p>Whether the connection is open (ready for read and write).</p>
|
|
|
-
|
|
|
-<h3>connection.metadata</h3>
|
|
|
-
|
|
|
-<p>The metadata passed in when the connection was created with <code>peer.connect(...)</code>.</p>
|
|
|
-
|
|
|
-<h3>connection.label</h3>
|
|
|
-
|
|
|
-<p>The optional label passed in or assigned by PeerJS when the connection was created with <code>peer.connect(...)</code>.</p>
|
|
|
-
|
|
|
-<h3>connection.serialization</h3>
|
|
|
-
|
|
|
-<p>The serialization format of the connection. Can be <code>binary</code>, <code>binary-utf8</code>, <code>json</code>, or <code>none</code>
|
|
|
-for no serialization. Default serialization format is <code>binary</code>.</p>
|
|
|
-
|
|
|
-<p><strong>Note:</strong> <code>binary-utf8</code> will take a performance hit because of the way utf8 strings are packed into binary.</p>
|
|
|
-
|
|
|
-<h3>connection.send(data)</h3>
|
|
|
-
|
|
|
-<p>Accepts data of any JSON type or binary type.</p>
|
|
|
-
|
|
|
-<p>To configure which serialization format to use, specify <code>binary</code>, <code>binary-utf8</code>, <code>json</code>, or <code>none</code> as the <code>serialization</code> property of the <code>options</code> object in <code>peer.connect(...)</code>.</p>
|
|
|
-
|
|
|
-<p>Data is serialized using BinaryPack (<code>binary</code>) by default and then sent to the remote peer.</p>
|
|
|
-
|
|
|
-<h3>connection.close()</h3>
|
|
|
-
|
|
|
-<p>Gracefully closes the connection.</p>
|
|
|
-
|
|
|
-<h3>Event: 'data'</h3>
|
|
|
-
|
|
|
-<p><code>function (data) { }</code></p>
|
|
|
-
|
|
|
-<p>Emitted when data is received from the remote peer. </p>
|
|
|
-
|
|
|
-<p>The <code>data</code> parameter contains values exactly as put into the <code>connection.send(...)</code>. Binary types will have been deserialized to <code>ArrayBuffer</code>.</p>
|
|
|
-
|
|
|
-<h3>Event: 'open'</h3>
|
|
|
-
|
|
|
-<p><code>function () { }</code></p>
|
|
|
-
|
|
|
-<p>Emitted when the connection is established and ready for writing. <code>data</code> from the remote peer will also start to be emitted.</p>
|
|
|
-
|
|
|
-<h3>Event: 'error'</h3>
|
|
|
-
|
|
|
-<p><code>function (error) { }</code></p>
|
|
|
-
|
|
|
-<p>If the connection emits an error, this event is emitted (errors from the underlying <code>DataChannel</code> are forwarded here).</p>
|
|
|
-
|
|
|
-<p><code>error</code> is an <code>Error</code> object.</p>
|
|
|
-
|
|
|
-<h3>Event: 'close'</h3>
|
|
|
-
|
|
|
-<p><code>function () { }</code></p>
|
|
|
-
|
|
|
-<p>Is emitted when the connection is closed.</p>
|
|
|
+ <p>
|
|
|
+ A Peer can connect to other peers and listen for connections.
|
|
|
+ </p>
|
|
|
|
|
|
-<p>The <code>close</code> event is also emitted when the remote peer closes the connection.</p>
|
|
|
+ <!-- peer args -->
|
|
|
+ <div class="arguments">
|
|
|
+ <div class="argument">
|
|
|
+ <span class="name">
|
|
|
+ id
|
|
|
+ </span>
|
|
|
+ <span class="labels">
|
|
|
+ <span class="label type">string</span>
|
|
|
+ <span class="label arg">arg</span>
|
|
|
+ </span>
|
|
|
+
|
|
|
+ <p>
|
|
|
+ Other peers can connect to this peer using the provided ID. If no ID
|
|
|
+ is given, one will be generated by the brokering server.
|
|
|
+ </p>
|
|
|
+
|
|
|
+ <p>
|
|
|
+ It is not
|
|
|
+ recommended that you use this ID to identify peers, as it's meant to
|
|
|
+ be used for brokering connections only. You're recommended to set the
|
|
|
+ <span class="code">metadata</span> option to send other identifying
|
|
|
+ information.
|
|
|
+ </p>
|
|
|
+
|
|
|
+ </div>
|
|
|
+
|
|
|
+ <div class="argument">
|
|
|
+ <span class="name">
|
|
|
+ options
|
|
|
+ </span>
|
|
|
+ <span class="labels">
|
|
|
+ <span class="label type">object</span>
|
|
|
+ <span class="label arg">arg</span>
|
|
|
+ </span>
|
|
|
+
|
|
|
+ <div class="options">
|
|
|
+ <div class="option">
|
|
|
+ <span class="name">
|
|
|
+ key
|
|
|
+ </span>
|
|
|
+ <span class="labels">
|
|
|
+ <span class="label">option</span>
|
|
|
+ <span class="label type">string</span>
|
|
|
+ </span>
|
|
|
+
|
|
|
+ <p>
|
|
|
+ API key for the cloud PeerServer. This is not used for servers
|
|
|
+ other than <span class="code">0.peerjs.com</span>
|
|
|
+ </p>
|
|
|
+ </div>
|
|
|
+
|
|
|
+ <div class="option">
|
|
|
+ <span class="name">
|
|
|
+ host
|
|
|
+ </span>
|
|
|
+ <span class="labels">
|
|
|
+ <span class="label">option</span>
|
|
|
+ <span class="label type">string</span>
|
|
|
+ </span>
|
|
|
+
|
|
|
+ <p>
|
|
|
+ Server host. Defaults to <span class="code">0.peerjs.com</span>.
|
|
|
+ Also accepts <span class="code">'/'</span> to signify relative
|
|
|
+ hostname.
|
|
|
+ </p>
|
|
|
+ </div>
|
|
|
+
|
|
|
+ </div>
|
|
|
+
|
|
|
+ </div>
|
|
|
+ </div>
|
|
|
+ <!-- /peer args -->
|
|
|
+
|
|
|
+ <!-- peer methods -->
|
|
|
+ <div class="methods">
|
|
|
+
|
|
|
+ <!-- peer.connect -->
|
|
|
+ <div class="method">
|
|
|
+ <span class="name">
|
|
|
+ peer.connect(id, [options])
|
|
|
+ </span>
|
|
|
+ <span class="labels">
|
|
|
+ <span class="label">method</span>
|
|
|
+ </span>
|
|
|
+
|
|
|
+ <!-- peer.connect args -->
|
|
|
+ <div class="arguments">
|
|
|
+ <div class="argument">
|
|
|
+ <span class="name">
|
|
|
+ id
|
|
|
+ </span>
|
|
|
+ <span class="labels">
|
|
|
+ <span class="label type">string</span>
|
|
|
+ <span class="label required">required</span>
|
|
|
+ <span class="label arg">arg</span>
|
|
|
+ </span>
|
|
|
+
|
|
|
+ <p>
|
|
|
+ Blah blah something.
|
|
|
+ </p>
|
|
|
+
|
|
|
+ </div>
|
|
|
+
|
|
|
+ <div class="argument">
|
|
|
+ <span class="name">
|
|
|
+ options
|
|
|
+ </span>
|
|
|
+ <span class="labels">
|
|
|
+ <span class="label type">object</span>
|
|
|
+ <span class="label arg">arg</span>
|
|
|
+ </span>
|
|
|
+
|
|
|
+ <div class="options">
|
|
|
+ <div class="option">
|
|
|
+ <span class="name">
|
|
|
+ serialization
|
|
|
+ </span>
|
|
|
+ <span class="labels">
|
|
|
+ <span class="label">option</span>
|
|
|
+ <span class="label type">string</span>
|
|
|
+ </span>
|
|
|
+
|
|
|
+ <p>
|
|
|
+ Blah more blah.
|
|
|
+ </p>
|
|
|
+ </div>
|
|
|
+
|
|
|
+ </div>
|
|
|
+
|
|
|
+ </div>
|
|
|
+ </div>
|
|
|
+ <!-- /peer.connect args -->
|
|
|
+ </div>
|
|
|
+ <!-- /peer.connect -->
|
|
|
+
|
|
|
+ </div>
|
|
|
+ <!-- /peer methods -->
|
|
|
+
|
|
|
+ <!-- peer events -->
|
|
|
+ <div class="events">
|
|
|
+ </div>
|
|
|
+ <!-- /peer events -->
|
|
|
+ </div>
|
|
|
|
|
|
</section>
|
|
|
|
|
|
<section class="start">
|
|
|
- <h1>PeerJS docs</h1>
|
|
|
<h2>Get started with PeerJS</h2>
|
|
|
|
|
|
<div class="warning">Due to browsers' incomplete support of the WebRTC DataChannel specification, many features of PeerJS have caveats.<br><a href="/status">View the status page for full details</a>.</div>
|
Michelle Bu