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