Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 156 lines (83 sloc) 5.947 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
8 This class is a the BinaryJS websocket server. It is an `EventEmitter`.
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`
15 * `host` String. Server host. Default `cloud.peerjs.com`
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
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.
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.
49 * `serialization` String, which can be `binary`, `json`, or `none`. This will be the serialization format of all data sent over the P2P DataConnection. Defaults to `binary`.
e2f9f15 @ericz docs first draft
ericz authored
50
51 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.
52
53 ### peer.destroy()
54
55 Close the server and terminate all connections.
56
57 ### Event: 'connection'
58
59 `function (connection, meta) { }`
60
61 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.
62
00512f0 @ericz update docs
ericz authored
63 Note that the `open` event must fire on the `DataConnection` before it is ready to read/write.
64
d2e05d5 @ericz docs update
ericz authored
65 ### Event: 'open'
e2f9f15 @ericz docs first draft
ericz authored
66
67 `function(id) { }`
68
d2e05d5 @ericz docs update
ericz authored
69 Fired when the PeerServer connection is succesfully, fully, open.
70 This event does not need to fire before creating or receiving connections.
71 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
72
d2e05d5 @ericz docs update
ericz authored
73 `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
74
75 ### Event: 'error'
76
77 `function (error) { }`
78
00512f0 @ericz update docs
ericz authored
79 Emitted when an unexpected event occurs. May or may not be fatal. Errors from the underlying socket are forwarded here.
80
81 This is the event emitted if you attempt to connect with an ID that is already being used.
e2f9f15 @ericz docs first draft
ericz authored
82
83
84 ### Event: 'close'
85
00512f0 @ericz update docs
ericz authored
86 `function () { }`
e2f9f15 @ericz docs first draft
ericz authored
87
88 Emitted when the Peer object has closed it's connection with PeerServer so no more remote peer connections can be made or received..
89
90 ## Class: peerjs.DataConnection
91
92 This class is the interface two communicate between two peers. It is an `EventEmitter`.
93
94 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.
95
96 ### connection.id
97
98 The id of the local peer that this connection belongs to.
99
100 ### connection.peer
101
102 The id of the remote peer this connection is connected to.
103
104 ### connection.open
105
106 Whether the connection is open (ready for read and write).
107
108 ### connection.metadata
109
110 The metadata passed in when the connection was created with `peer.connect(...)`.
111
b6ec7a8 @michelle update api
michelle authored
112 ### connection.serialization
113
114 The serialization format of the connection. Can be `binary`, `json`, or `none`
115 for no serialization. Default serialization format is `binary`.
116
e2f9f15 @ericz docs first draft
ericz authored
117 ### connection.send(data)
118
119 Accepts data of any JSON type or binary type.
120
121 Data is serialized using BinaryPack and then sent to the remote peer.
122
123 ### connection.close()
124
125 Gracefully closes the connection.
126
127 ### Event: 'data'
128
129 `function (data) { }`
130
131 Emitted when data is received from the remote peer.
132
133 The `data` parameter contains values exactly as put into the `connection.send(...)`. Binary types will have been deserialized to `ArrayBuffer`.
134
135 ### Event: 'open'
136
137 `function () { }`
138
00512f0 @ericz update docs
ericz authored
139 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
140
141 ### Event: 'error'
142
143 `function (error) { }`
144
145 If the client emits an error, this event is emitted (errors from the underlying `RTCPeerConnection` and `DataChannel` are forwarded here).
146
147 ### Event: 'close'
148
149 `function () { }`
150
151 Is emitted when the connection is closed.
152
153 The `close` event is also emitted when the remote peer closes the connection.
154
155
Something went wrong with that request. Please try again.