Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 142 lines (74 sloc) 5.044 kb
e2f9f15 @ericz docs first draft
ericz authored
1 # PeerJS API Reference
2
e85dca5 @ericz update docs
ericz authored
3 ## Class: peerjs.Peer
e2f9f15 @ericz docs first draft
ericz authored
4
5 This class is a the BinaryJS websocket server. It is an `EventEmitter`.
6
e85dca5 @ericz update docs
ericz authored
7 ### new Peer([id], options)
e2f9f15 @ericz docs first draft
ericz authored
8
9 * `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
10 * `options` Object
11 * `key` String. API key for cloud PeerServer. Is not used for servers other than `cloud.peerjs.com`
12 * `host` String. Server host. Default `cloud.peerjs.com`
13 * `port` Number. Server port. Default `80`
14 * `config` Object. Configuration hash passed to `RTCPeerConnection`. This hash contains the ICE servers. Default `{ 'iceServers': [{ 'url': 'stun:stun.l.google.com:19302' }] }`
15 * `debug` Boolean. Prints verbose log messages. Default `false`
16
17 Construct a new Peer object.
18
19 The Peer object is used to connect to other Peer clients and also to receive connections from other clients.
20
21 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.
22
23 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.
24
25 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.
26
27 ### peer.id
28
29 The given id of this peer.
30
31 If no id was specified in the constructor, this value will be `undefined` util the `open` event fires.
32
33 ### peer.connections
34
35 A hash of all current connections with the current peer. Keys are ids and values are instances of `DataConnection`.
36
37 ### peer.connect(id, [meta])
38
39 Connects to the remote peer specified by `id`.
40
41 Returns a `DataConnection` object.
42
43 * `id` String. The id of the remote peer to connect to
44 * `meta` Optional metadata to pass to the remote peer. Can be any serializable type
45
46 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.
47
48 ### peer.destroy()
49
50 Close the server and terminate all connections.
51
52 ### Event: 'connection'
53
54 `function (connection, meta) { }`
55
56 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.
57
58 ### Event: 'open'
59
60 `function(id) { }`
61
62 Fired when the PeerServer connection is fully open.
63 This event does not need to fire before creating or receiving connections.
64
65 `id` is the id of this `Peer` object, either provided in the constructor, or generated automatically by the PeerServer.
66
67 ### Event: 'error'
68
69 `function (error) { }`
70
71 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.
72
73 Errors from the underlying socket are forwarded here.
74
75 ### Event: 'close'
76
77 `function (error) { }`
78
79 Emitted when the Peer object has closed it's connection with PeerServer so no more remote peer connections can be made or received..
80
81 ## Class: peerjs.DataConnection
82
83 This class is the interface two communicate between two peers. It is an `EventEmitter`.
84
85 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.
86
87 ### connection.id
88
89 The id of the local peer that this connection belongs to.
90
91 ### connection.peer
92
93 The id of the remote peer this connection is connected to.
94
95 ### connection.open
96
97 Whether the connection is open (ready for read and write).
98
99 ### connection.metadata
100
101 The metadata passed in when the connection was created with `peer.connect(...)`.
102
103 ### connection.send(data)
104
105 Accepts data of any JSON type or binary type.
106
107 Data is serialized using BinaryPack and then sent to the remote peer.
108
109 ### connection.close()
110
111 Gracefully closes the connection.
112
113 ### Event: 'data'
114
115 `function (data) { }`
116
117 Emitted when data is received from the remote peer.
118
119 The `data` parameter contains values exactly as put into the `connection.send(...)`. Binary types will have been deserialized to `ArrayBuffer`.
120
121 ### Event: 'open'
122
123 `function () { }`
124
125 Emitted when the connection is established.
126
127 ### Event: 'error'
128
129 `function (error) { }`
130
131 If the client emits an error, this event is emitted (errors from the underlying `RTCPeerConnection` and `DataChannel` are forwarded here).
132
133 ### Event: 'close'
134
135 `function () { }`
136
137 Is emitted when the connection is closed.
138
139 The `close` event is also emitted when the remote peer closes the connection.
140
141
Something went wrong with that request. Please try again.