Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 177 lines (99 sloc) 7.862 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
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
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
38 A hash of all current connections with the current peer. Keys are ids and values are instances of `DataConnection`.
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.
48 * `metadata` Optional metadata to pass to the remote peer. Can be any serializable type.
dc637f2 @michelle update api
michelle authored
49 * `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`.
8772dbb @michelle docs
michelle authored
50 * `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
51
52 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.
53
54 ### peer.destroy()
55
56 Close the server and terminate all connections.
57
58 ### Event: 'connection'
59
60 `function (connection, meta) { }`
61
62 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.
63
a116ed5 @michelle api update for new error events
michelle authored
64 **Note:** the `open` event must fire on the `DataConnection` before it is ready to read/write.
00512f0 @ericz update docs
ericz authored
65
d2e05d5 @ericz docs update
ericz authored
66 ### Event: 'open'
e2f9f15 @ericz docs first draft
ericz authored
67
68 `function(id) { }`
69
d2e05d5 @ericz docs update
ericz authored
70 Fired when the PeerServer connection is succesfully, fully, open.
71 This event does not need to fire before creating or receiving connections.
a116ed5 @michelle api update for new error events
michelle authored
72 **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
73
d2e05d5 @ericz docs update
ericz authored
74 `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
75
76 ### Event: 'error'
77
78 `function (error) { }`
79
a116ed5 @michelle api update for new error events
michelle authored
80 Emitted when an unexpected event occurs. Errors on the Peer are **always fatal**. Errors from the underlying socket are forwarded here.
00512f0 @ericz update docs
ericz authored
81
a116ed5 @michelle api update for new error events
michelle authored
82 The `error` object also has a `type` parameter that may be helpful in responding to client errors properly:
83 * `invalid-id`: The ID passed into the Peer constructor contains illegal characters.
84 * `invalid-key`: The API key passed into the Peer constructor contains illegal characters or is not in the system (cloud server only).
85 * `unavailable-id`: The ID passed into the Peer constructor is already taken.
86 * Errors types that shouldn't regularly appear:
87 * `server-error`: Unable to reach the server.
88 * `socket-error`: An error from the underlying socket.
89 * `socket-closed`: The underlying socket closed unexpectedly.
10c61ae @michelle closes #14; 'error' event now comes with brand new shiny Error object an...
michelle authored
90 * (The Peer object is destroyed after one of the errors above are emitted.)
e0d9e22 @michelle destroyed check when connecting
michelle authored
91 * `peer-destroyed`: A Peer that has been destroyed is being used to try to connect.
e2f9f15 @ericz docs first draft
ericz authored
92
93 ### Event: 'close'
94
00512f0 @ericz update docs
ericz authored
95 `function () { }`
e2f9f15 @ericz docs first draft
ericz authored
96
ba59b06 @michelle 0.1.6
michelle authored
97 Emitted when the Peer object has closed it's connection with PeerServer so no more remote peer connections can be made or received.
98
99 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
100
101 ## Class: peerjs.DataConnection
102
103 This class is the interface two communicate between two peers. It is an `EventEmitter`.
104
105 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
106
107 ### EXPERIMENTAL reliable and large file transfer:
108
109 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
110
111 ### connection.id
112
113 The id of the local peer that this connection belongs to.
114
115 ### connection.peer
116
117 The id of the remote peer this connection is connected to.
118
119 ### connection.open
120
121 Whether the connection is open (ready for read and write).
122
123 ### connection.metadata
124
125 The metadata passed in when the connection was created with `peer.connect(...)`.
126
b6ec7a8 @michelle update api
michelle authored
127 ### connection.serialization
128
dc637f2 @michelle update api
michelle authored
129 The serialization format of the connection. Can be `binary`, `binary-utf8`, `json`, or `none`
b6ec7a8 @michelle update api
michelle authored
130 for no serialization. Default serialization format is `binary`.
131
a116ed5 @michelle api update for new error events
michelle authored
132 **Note:** `binary-utf8` will take a performance hit because of the way utf8 strings are packed into binary.
dc637f2 @michelle update api
michelle authored
133
e2f9f15 @ericz docs first draft
ericz authored
134 ### connection.send(data)
135
136 Accepts data of any JSON type or binary type.
137
dc637f2 @michelle update api
michelle authored
138 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
139
140 Data is serialized using BinaryPack (`binary`) by default and then sent to the remote peer.
e2f9f15 @ericz docs first draft
ericz authored
141
142 ### connection.close()
143
144 Gracefully closes the connection.
145
146 ### Event: 'data'
147
148 `function (data) { }`
149
150 Emitted when data is received from the remote peer.
151
152 The `data` parameter contains values exactly as put into the `connection.send(...)`. Binary types will have been deserialized to `ArrayBuffer`.
153
154 ### Event: 'open'
155
156 `function () { }`
157
00512f0 @ericz update docs
ericz authored
158 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
159
160 ### Event: 'error'
161
162 `function (error) { }`
163
164 If the client emits an error, this event is emitted (errors from the underlying `RTCPeerConnection` and `DataChannel` are forwarded here).
165
a116ed5 @michelle api update for new error events
michelle authored
166 `error` is an `Error` object.
167
e2f9f15 @ericz docs first draft
ericz authored
168 ### Event: 'close'
169
170 `function () { }`
171
172 Is emitted when the connection is closed.
173
174 The `close` event is also emitted when the remote peer closes the connection.
175
176
Something went wrong with that request. Please try again.