-
Notifications
You must be signed in to change notification settings - Fork 0
/
api_documentation.html
503 lines (495 loc) · 17.2 KB
/
api_documentation.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
<html>
<head>
<title>SockIt · API</title>
<link href="tutorial.css" rel="stylesheet" type="text/css">
</head>
<body>
<center>
<h1>SockIt · API</h1>
<h3><a href="downloads.html">Download</a></h3>
<br/>
<br/>
<a href="index.html">Home</a> · <a href="tutorial.html">Quick Tutorial</a> · <a href="full_tutorial.html">Full Tutorial</a> · <a href="demos.html">Demos</a> · <a href="api_documentation.html">API</a> · <a href="html/index.html">Source Documentation</a> · <a href="developers.html">Developers</a>
</center>
<h2>Top Level API</h2>
<br>
<table>
<tr><pre>createThread()</pre></tr>
<tr>
<td>
<p>Creates a new thread on which to create new clients and servers.</p>
<table>
<tr>
<td><code>returns</code></td>
<td>A new thread, on which we can create new clients and servers.</td>
</tr>
</table>
</td>
</tr>
</table>
<br><br>
<table>
<tr><pre>toBinary(data)</pre></tr>
<tr>
<td>
<p>Converts an array of bytes by encoding each byte into a UTF-16 character, and returns a UTF-16 string encoded from the given data.</p>
<table>
<tr>
<td><code>data</code></td>
<td>An array of 1-byte integers, which will be converted into a string.</td>
</tr>
<tr>
<td><code>returns</code></td>
<td>A UTF-16 string encoded from the given data.</td>
</tr>
</table>
</td>
</tr>
</table>
<br><br>
<table>
<tr><pre>fromBinary(data)</pre></tr>
<tr>
<td>
<p>Converts a UTF-16 string into an array of bytes.</p>
<table>
<tr>
<td><code>data</code></td>
<td>The UTF-16 string to convert to bytes.</td>
</tr>
<tr>
<td><code>returns</code></td>
<td>An array of bytes, the result of decoding <code>data</code> character by character.</td>
</tr>
</table>
</td>
</tr>
</table>
<br><br>
<table>
<tr><pre>createTcpServer(port [, options])</pre></tr>
<tr>
<td>
<p>Creates a TCP server, but does not start the server listening.</p>
<table>
<tr>
<td><code>port</code></td>
<td>An integer representing the port on which the server will listen.</td>
</tr>
<tr>
<td><code>options</code></td>
<td>An optional map of strings to strings, which enumerates further options for the TCP connections for this server, and controls the underlying TCP sockets. If this map is not provided, each property takes its default value.
</tr>
<tr>
<td></td><td>
<table>
<tr>
<td><code>doNotRoute</code></td>
<td>Specifies whether this server should disable routing on its TCP connections. If this field is set to <code>false</code> or is not provided, the server defaults to <code>false</code>, so that routing is enabled.</td>
</tr>
<tr>
<td><code>ipv6</code></td>
<td>Specifies whether this server should use IPv6 over IPv4. If this field is set to <code>false</code> or is not provided, the server defaults to IPv4.</td>
</tr>
<tr>
<td><code>keepAlive</code></td>
<td>If this field is set to true, then the underlying TCP connection will try to maintain a keep-alive connections with clients. By default, this field is <code>true</code>.</td>
</tr>
<tr>
<td><code>keepAliveTimeout</code></td>
<td>If this field is set, then the underlying TCP connection will maintain a keep-alive connections with this specified timeout, interpreted in milliseconds.</td>
</tr>
<tr>
<td><code>noDelay</code></td>
<td>Setting this field to <code>true</code> forces the underlying TCP connections to disable <a href="http://en.wikipedia.org/wiki/Nagle's_algorithm">Nagle's algorithm</a> for TCP. By default, this field is <code>false</code>.</td>
</tr>
</table>
</td>
</tr>
<tr>
<td><code>returns</code></td>
<td>A newly created TCP server, which is not yet listening.</td>
</tr>
</table>
</td>
</tr>
</table>
<br><br>
<table>
<tr><pre>createUdpServer(port [, options])</pre></tr>
<tr>
<td>
<p>Creates a UDP server, but does not start the server listening.</p>
<table>
<tr>
<td><code>port</code></td>
<td>An integer representing the port on which the server will listen.</td>
</tr>
<tr>
<td><code>options</code></td>
<td>An optional map of strings to strings, which enumerates further options for the UDP connections for this server, and controls the underlying UDP sockets. If this map is not provided, each property takes its default value.
</tr>
<tr>
<td></td><td>
<table>
<tr>
<td><code>ipv6</code></td>
<td>Specifies whether this server should use IPv6 over IPv4. If this field is set to <code>false</code> or is not provided, the server defaults to IPv4.</td>
</tr>
<tr>
<td><code>doNotRoute</code></td>
<td>Specifies whether this server should disable routing on its UDP connections. If this field is set to <code>false</code> or is not provided, the server defaults to <code>false</code>, so that routing is enabled.</td>
</tr>
<tr>
<td><code>multicast</code></td>
<td>Specifies whether this server should enable UDP multicast. If this field is not provided, it defaults to <code>false</code>, such that multicast is disabled for this server. If this is set to true, <code>MulticastGroup</code> must also be specified, and <code>ReuseAddress</code> will be set to true.</td>
</tr>
<tr>
<td><code>multicastGroup</code></td>
<td>The multicast group to which this UDP server has subscribed and from which it will receive messages. This field has no default value.</td>
</tr>
<tr>
<td><code>multicastTTL</code></td>
<td>The multicast TTL for this UDP server, or the number of router hops that a multicast message sent from this server will make. This field has no specified default value. Note that large values may be ignored by routers.</td>
</tr>
<tr>
<td><code>reuseAddress</code></td>
<td>Specifies whether this server should fail if the port on which it should listen already has another socket bound to it. By default, this parameter is <code>false</code>, so that the server will not try to reuse addresses and will fail if another socket is already bound to the port. This is automatically set to <code>true</code> if <code>Multicast</code> is enabled.</td>
</tr>
</table>
</td>
</tr>
<tr>
<td><code>returns</code></td>
<td>A newly created UDP server, which is not yet listening.</td>
</tr>
</table>
</td>
</tr>
</table>
<br><br>
<table>
<tr><pre>createTcpClient(hostname, port [, options])</pre></tr>
<tr>
<td>
<p>Creates a TCP client.</p>
<table>
<tr>
<td><code>hostname</code></td>
<td>A string, the hostname or IP address to which this client should connect.</td>
</tr>
<tr>
<td><code>port</code></td>
<td>An integer representing the port to which the client will connect.</td>
</tr>
<tr>
<td><code>options</code></td>
<td>An optional map of strings to strings, which enumerates further options for the TCP connections for this client, and controls the underlying TCP socket. If this map is not provided, each property takes its default value.
</tr>
<tr>
<td></td><td>
<table>
<tr>
<td><code>doNotRoute</code></td>
<td>Specifies whether this client should disable routing on its TCP connections. If this field is set to <code>false</code> or is not provided, the client defaults to <code>false</code>, so that routing is enabled.</td>
</tr>
<tr>
<td><code>ipv6</code></td>
<td>Specifies whether this client should use IPv6 over IPv4. If this field is set to <code>false</code> or is not provided, the client defaults to IPv4.</td>
</tr>
<tr>
<td><code>keepAlive</code></td>
<td>If this field is set to true, then the underlying TCP connection will try to maintain a keep-alive connections with servers. By default, this field is <code>false</code>.</td>
</tr>
<tr>
<td><code>keepAliveTimeout</code></td>
<td>If this field is set, then the underlying TCP connection will maintain a keep-alive connections with this specified timeout, interpreted in milliseconds.</td>
</tr>
<tr>
<td><code>noDelay</code></td>
<td>Setting this field to <code>true</code> forces the underlying TCP connections to disable <a href="http://en.wikipedia.org/wiki/Nagle's_algorithm">Nagle's algorithm</a> for TCP. By default, this field is <code>false</code>.</td>
</tr>
</table>
</td>
</tr>
<tr>
<td><code>returns</code></td>
<td>A newly created TCP client.</td>
</tr>
</table>
</td>
</tr>
</table>
<br><br>
<table>
<tr><pre>createUdpClient(hostname, port [, options])</pre></tr>
<tr>
<td>
<p>Creates a UDP client.</p>
<table >
<tr>
<td><code>hostname</code></td>
<td>A string, the hostname or IP address to which this client should connect.</td>
</tr>
<tr>
<td><code>port</code></td>
<td>An integer representing the port to which the client will connect.</td>
</tr>
<tr>
<td><code>options</code></td>
<td>An optional map of strings to strings, which enumerates further options for the UDP connections for this client, and controls the underlying UDP sockets. If this map is not provided, each property takes its default value.
</tr>
<tr>
<td></td><td>
<table>
<tr>
<td><code>doNotRoute</code></td>
<td>Specifies whether this client should disable routing on its UDP connections. If this field is set to <code>false</code> or is not provided, the client defaults to <code>false</code>, so that routing is enabled.</td>
</tr>
<tr>
<td><code>ipv6</code></td>
<td>Specifies whether this client should use IPv6 over IPv4. If this field is set to <code>false</code> or is not provided, the client defaults to IPv4.</td>
</tr>
<tr>
<td><code>multicast</code></td>
<td>Specifies whether this client should enable UDP multicast. If this field is not provided, it defaults to <code>false</code>, such that multicast is disabled for this client. If this is set to true, <code>MulticastGroup</code> must also be specified, and <code>ReuseAddress</code> will be set to true.</td>
</tr>
<tr>
<td><code>multicastTTL</code></td>
<td>The multicast TTL for this UDP client, or the number of router hops that a multicast message sent from this client will make. This field has no specified default value. Note that large values may be ignored by routers.</td>
</tr>
</table>
</td>
</tr>
<tr>
<td><code>returns</code></td>
<td>A newly created UDP client.</td>
</tr>
</table>
</td>
</tr>
</table>
<h2>Thread API</h2>
<div class='indented'>
Mirrors the top level API, except that it does not contain the <code>createThread</code> method.<p> </p>
</div>
<h2>Client API</h2>
<p class='indented'>The API exposed to both UDP and TCP clients contain these common functions.</p>
<table class='indented'>
<tr>
<td>
<pre>send(data)</pre>
</td>
<td>
<p>Asynchronously sends some data to the remote endpoint for this client.</p>
<table>
<tr>
<td><code>data</code></td>
<td>A string, the data the client should be sent to the remote endpoint.</td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<pre>sendBytes(data)</pre>
</td>
<td>
<p>Asynchronously sends some bytes of data across the connection.</p>
<table>
<tr>
<td><code>data</code></td>
<td>An array of bytes to send over the connection.</td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<pre>close()</pre>
</td>
<td>
<p>Gracefully shuts down the client, freeing all resources once pending sends have been completed.</p>
</td>
<tr>
<td>
<pre>getHost()</pre>
</td>
<td>
<p>Gets the hostname to which this client connects.</p>
</td>
</tr>
<tr>
<td>
<pre>getPort()</pre>
</td>
<td>
<p>Gets the port on which this client will connect to the remote host.</p>
</td>
</tr>
</tr>
</table>
<p> </p>
<h2>Server API</h2>
<p class='indented'>The API exposed to both UDP and TCP servers contain these common functions.</p>
<table class='indented'>
<tr>
<td>
<pre>listen()</pre>
</td>
<td>
<p>Starts up the server listening on the port given.</p>
</td>
</tr>
<tr>
<td>
<pre>close()</pre>
</td>
<td>
<p>Gracefully shuts down the server, freeing the port and resources once any pending sends have completed. The server will continue to listen for connections and incoming data until all pending sends have been sent.</p>
</td>
</tr>
<tr>
<td>
<pre>getPort()</pre>
</td>
<td>
<p>Returns the port on which this server listens.</p>
</td>
</tr>
</table>
<p> </p>
<h2>Event API</h2>
<p class='indented'>The API exposed to the event parameter of the <code>data</code> handler function, which allows reading and sending data.</p>
<table class='indented'>
<tr>
<td>
<pre>send(data)</pre>
</td>
<td>
<p>Asynchronously send back some data across the connection.</p>
<table>
<tr>
<td><code>data</code></td>
<td>A string, the data the client should be sent to the remote endpoint.</td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<pre>sendBytes(data)</pre>
</td>
<td>
<p>Asynchronously send back some byte data across the connection.</p>
<table>
<tr>
<td><code>data</code></td>
<td>An array of bytes, which will be sent to the remote endpoint as binary data.</td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<pre>read()</pre>
</td>
<td>
<p>Read the string data that triggered this event.</p>
<table>
<tr>
<td><code>returns</code></td>
<td>A string, the data received that triggered this event.</td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<pre>readBytes(data)</pre>
</td>
<td>
<p>Read the bytes of the data received that triggered this event.</p>
<table>
<tr>
<td><code>returns</code></td>
<td>An array of bytes, representing the data received that triggered this event.</td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<pre>getHost()</pre>
</td>
<td>
<p>Returns the hostname from which the data was received.</p>
</td>
</tr>
<tr>
<td>
<pre>getPort()</pre>
</td>
<td>
<p>Returns the port from which the data was received on the remote host.</p>
</td>
</tr>
</table>
<p> </p>
<h2>Events</h2>
<p class='indented'>The events for which we can attach Javascript event handlers to perform callbacks.</p>
<table class='indented'>
<tr>
<td>
<pre>data</pre>
</td>
<td>
<p>This event can occur on server or clients, and is fired whenever a connection receives some data.</p>
</td>
</tr>
<tr>
<td>
<pre>error</pre>
</td>
<td>
<p>This event can occur on clients or server objects, and is fired whenever an unrecoverable error occurs.</p>
</td>
</tr>
<tr>
<td>
<pre>close</pre>
</td>
<td>
<p>This event occurs whenever a client or server completely shuts down, after the <code>close</code> function</p>
</td>
</tr>
<tr>
<td>
<pre>open</pre>
</td>
<td>
<p>This event occurs once a server successfully opens a new socket and begins listening for incoming connnections</p>
</td>
</tr>
<tr>
<td>
<pre>resolve</pre>
</td>
<td>
<p>This event occurs once a client successfully resolves the hostname of its remote endpoint</p>
</td>
</tr>
<tr>
<td>
<pre>disconnect</pre>
</td>
<td>
<p>This event occurs for TCP clients and servers when an error occurs that severs the TCP connection.</p>
</td>
</tr>
</table>
<center>
<br><a href="index.html">Home</a> · <a href="tutorial.html">Quick Tutorial</a> · <a href="full_tutorial.html">Full Tutorial</a> · <a href="demos.html">Demos</a> · <a href="api_documentation.html">API</a> · <a href="html/index.html">Source Documentation</a> · <a href="developers.html">Developers</a>
</center>
</body>
</html>