Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 188 lines (106 sloc) 8.876 kb
e2f9f15 @ericz docs first draft
ericz authored
1 # PeerJS API Reference
2
f393640 @ericz mo docs
ericz authored
3 **Due to browsers' incomplete support of the WebRTC DataChannel specification, many features of PeerJS have caveats.
4 [View the status page for full details](http://peerjs.com/status).**
5
e85dca5 @ericz update docs
ericz authored
6 ## Class: peerjs.Peer
e2f9f15 @ericz docs first draft
ericz authored
7
a60ddb8 @michelle more details on serialization format
michelle authored
8 This class is a Peer, which can connect to other peers and listen for connections. It is an `EventEmitter`.
e2f9f15 @ericz docs first draft
ericz authored
9
c768356 @michelle update docs more
michelle authored
10 ### new Peer([id], [options])
e2f9f15 @ericz docs first draft
ericz authored
11
f8ce0c1 @michelle advisory
michelle authored
12 * `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. **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 `metadata` option to send other identifying information.**
e2f9f15 @ericz docs first draft
ericz authored
13 * `options` Object
14 * `key` String. API key for cloud PeerServer. Is not used for servers other than `cloud.peerjs.com`
730339e @michelle / for relative hostname
michelle authored
15 * `host` String. Server host. Default `cloud.peerjs.com`. Also accepts `'/'` for relative hostname.
e2f9f15 @ericz docs first draft
ericz authored
16 * `port` Number. Server port. Default `80`
17 * `config` Object. Configuration hash passed to `RTCPeerConnection`. This hash contains the ICE servers. Default `{ 'iceServers': [{ 'url': 'stun:stun.l.google.com:19302' }] }`
18 * `debug` Boolean. Prints verbose log messages. Default `false`
19
20 Construct a new Peer object.
21
22 The Peer object is used to connect to other Peer clients and also to receive connections from other clients.
23
24 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.
25
a116ed5 @michelle api update for new error events
michelle authored
26 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.**
e2f9f15 @ericz docs first draft
ericz authored
27
28 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.
29
30 ### peer.id
31
32 The given id of this peer.
33
d2e05d5 @ericz docs update
ericz authored
34 If no id was specified in the constructor, this value will be `undefined` util the `open` event fires.
e2f9f15 @ericz docs first draft
ericz authored
35
36 ### peer.connections
37
d8d16e6 @michelle docs
michelle authored
38 A hash of all current connections with the current peer. Keys are ids and values are hashes of label => `DataConnection` pairs.
e2f9f15 @ericz docs first draft
ericz authored
39
c768356 @michelle update docs more
michelle authored
40 ### peer.connect(id, [options])
e2f9f15 @ericz docs first draft
ericz authored
41
c768356 @michelle update docs more
michelle authored
42 Connects to the remote peer specified by `id`.
e2f9f15 @ericz docs first draft
ericz authored
43
44 Returns a `DataConnection` object.
45
c768356 @michelle update docs more
michelle authored
46 * `id` String. The id of the remote peer to connect to.
47 * `options` Object.
d8d16e6 @michelle docs
michelle authored
48 * `label` 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.
34e704e @michelle unmerge firefox for now
michelle authored
49 * `metadata` Optional metadata to pass to the remote peer. Can be any serializable type.
50 * `serialization` String, which can be `binary`, `binary-utf8`, `json`, or `none`. This will be the serialization format of all data sent over the P2P DataConnection. Defaults to `binary`.
51 * `reliable` Boolean, which if `true` activates experimental reliable transfer (while waiting for actual reliable transfer to be implemented in Chrome). Defaults to `false` until Chrome implements reliable/large data transfer. This parameter is only available in the most recent build.
e2f9f15 @ericz docs first draft
ericz authored
52
53 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.
54
55 ### peer.destroy()
56
254e3be @michelle docs update
michelle authored
57 Close the connection to the server and terminate all connections.
58
59 **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.**
60
61 ### peer.disconnect()
62
63 Close the connection to the server, leaving all existing DataConnections intact.
64
65 **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.**
e2f9f15 @ericz docs first draft
ericz authored
66
67 ### Event: 'connection'
68
69 `function (connection, meta) { }`
70
71 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.
72
a116ed5 @michelle api update for new error events
michelle authored
73 **Note:** the `open` event must fire on the `DataConnection` before it is ready to read/write.
00512f0 @ericz update docs
ericz authored
74
d2e05d5 @ericz docs update
ericz authored
75 ### Event: 'open'
e2f9f15 @ericz docs first draft
ericz authored
76
77 `function(id) { }`
78
d2e05d5 @ericz docs update
ericz authored
79 Fired when the PeerServer connection is succesfully, fully, open.
80 This event does not need to fire before creating or receiving connections.
a116ed5 @michelle api update for new error events
michelle authored
81 **You should not wait for open before connecting to other peers or expecting to receive connections if connection speed is important.**
e2f9f15 @ericz docs first draft
ericz authored
82
d2e05d5 @ericz docs update
ericz authored
83 `id` is the id of this `Peer` object, either provided in the constructor, or generated automatically by the PeerServer.
e2f9f15 @ericz docs first draft
ericz authored
84
85 ### Event: 'error'
86
87 `function (error) { }`
88
34e704e @michelle unmerge firefox for now
michelle authored
89 Emitted when an unexpected event occurs. Errors on the Peer are **always
90 fatal**. Errors from the underlying socket and PeerConnections are forwarded here.
00512f0 @ericz update docs
ericz authored
91
a116ed5 @michelle api update for new error events
michelle authored
92 The `error` object also has a `type` parameter that may be helpful in responding to client errors properly:
a52201b @michelle fixes #27, at last. api updates as well.
michelle authored
93 * `browser-incompatible`: The client's browser does not support some or all WebRTC features that you are trying to use.
a116ed5 @michelle api update for new error events
michelle authored
94 * `invalid-id`: The ID passed into the Peer constructor contains illegal characters.
95 * `invalid-key`: The API key passed into the Peer constructor contains illegal characters or is not in the system (cloud server only).
96 * `unavailable-id`: The ID passed into the Peer constructor is already taken.
97 * Errors types that shouldn't regularly appear:
98 * `server-error`: Unable to reach the server.
99 * `socket-error`: An error from the underlying socket.
100 * `socket-closed`: The underlying socket closed unexpectedly.
10c61ae @michelle closes #14; 'error' event now comes with brand new shiny Error object an...
michelle authored
101 * (The Peer object is destroyed after one of the errors above are emitted.)
5fbdaf0 @michelle peer-disconnected could be confused for a peer disconnecting rather than...
michelle authored
102 * `server-disconnected`: A Peer that has been disconnected is being used to try to connect.
e2f9f15 @ericz docs first draft
ericz authored
103
104 ### Event: 'close'
105
00512f0 @ericz update docs
ericz authored
106 `function () { }`
e2f9f15 @ericz docs first draft
ericz authored
107
d62aed6 @michelle everything works
michelle authored
108 Emitted when the Peer object has closed its connection with PeerServer so no more remote peer connections can be made or received.
ba59b06 @michelle 0.1.6
michelle authored
109
110 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 `destroy()` on a Peer when it is no longer needed.
e2f9f15 @ericz docs first draft
ericz authored
111
112 ## Class: peerjs.DataConnection
113
114 This class is the interface two communicate between two peers. It is an `EventEmitter`.
115
116 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.
90e5fe5 @michelle docs
michelle authored
117
118 ### EXPERIMENTAL reliable and large file transfer:
119
120 Simply pass in `reliable: true` when calling `.connect(...)`. This module is experimental, temporary, and exists here: https://github.com/michellebu/reliable
e2f9f15 @ericz docs first draft
ericz authored
121
122 ### connection.id
123
124 The id of the local peer that this connection belongs to.
125
126 ### connection.peer
127
128 The id of the remote peer this connection is connected to.
129
130 ### connection.open
131
132 Whether the connection is open (ready for read and write).
133
134 ### connection.metadata
135
136 The metadata passed in when the connection was created with `peer.connect(...)`.
137
b6ec7a8 @michelle update api
michelle authored
138 ### connection.serialization
139
dc637f2 @michelle update api
michelle authored
140 The serialization format of the connection. Can be `binary`, `binary-utf8`, `json`, or `none`
b6ec7a8 @michelle update api
michelle authored
141 for no serialization. Default serialization format is `binary`.
142
a116ed5 @michelle api update for new error events
michelle authored
143 **Note:** `binary-utf8` will take a performance hit because of the way utf8 strings are packed into binary.
dc637f2 @michelle update api
michelle authored
144
e2f9f15 @ericz docs first draft
ericz authored
145 ### connection.send(data)
146
147 Accepts data of any JSON type or binary type.
148
dc637f2 @michelle update api
michelle authored
149 To configure which serialization format to use, specify `binary`, `binary-utf8`, `json`, or `none` as the `serialization` property of the `options` object in `peer.connect(...)`.
a60ddb8 @michelle more details on serialization format
michelle authored
150
151 Data is serialized using BinaryPack (`binary`) by default and then sent to the remote peer.
e2f9f15 @ericz docs first draft
ericz authored
152
153 ### connection.close()
154
155 Gracefully closes the connection.
156
157 ### Event: 'data'
158
159 `function (data) { }`
160
161 Emitted when data is received from the remote peer.
162
163 The `data` parameter contains values exactly as put into the `connection.send(...)`. Binary types will have been deserialized to `ArrayBuffer`.
164
165 ### Event: 'open'
166
167 `function () { }`
168
00512f0 @ericz update docs
ericz authored
169 Emitted when the connection is established and ready for writing. `data` from the remote peer will also start to be emitted.
e2f9f15 @ericz docs first draft
ericz authored
170
171 ### Event: 'error'
172
173 `function (error) { }`
174
d8d16e6 @michelle docs
michelle authored
175 If the connection emits an error, this event is emitted (errors from the underlying `DataChannel` are forwarded here).
e2f9f15 @ericz docs first draft
ericz authored
176
a116ed5 @michelle api update for new error events
michelle authored
177 `error` is an `Error` object.
178
e2f9f15 @ericz docs first draft
ericz authored
179 ### Event: 'close'
180
181 `function () { }`
182
183 Is emitted when the connection is closed.
184
185 The `close` event is also emitted when the remote peer closes the connection.
186
187
Something went wrong with that request. Please try again.