Browse code

modules/websocket: Update README xml with section IDs

Hugh Waite authored on 05/04/2013 13:12:22
Showing 2 changed files
... ...
@@ -1,11 +1,12 @@
1
+
1 2
 WebSocket Module
2 3
 
3 4
 Peter Dunkley
4 5
 
5 6
    Crocodile RCS Ltd
6 7
 
7
-   Copyright © 2012-2013 Crocodile RCS Ltd
8
-     __________________________________________________________________
8
+   Copyright � 2012-2013 Crocodile RCS Ltd
9
+     _________________________________________________________________
9 10
 
10 11
    Table of Contents
11 12
 
... ...
@@ -34,7 +35,7 @@ Peter Dunkley
34 35
 
35 36
         5. Functions
36 37
 
37
-              5.1. ws_handle_handshake()
38
+              5.1. ws_handle_handshake() 
38 39
 
39 40
         6. MI Commands
40 41
 
... ...
@@ -47,7 +48,7 @@ Peter Dunkley
47 48
 
48 49
         7. Event routes
49 50
 
50
-              7.1. websocket:closed
51
+              7.1. websocket:closed 
51 52
 
52 53
    List of Examples
53 54
 
... ...
@@ -60,6 +61,7 @@ Peter Dunkley
60 61
    1.7. Set ping_application_data parameter
61 62
    1.8. Set sub_protocols parameter
62 63
    1.9. ws_handle_handshake usage
64
+   1.10. event_route[websocket:closed] usage
63 65
 
64 66
 Chapter 1. Admin Guide
65 67
 
... ...
@@ -88,7 +90,7 @@ Chapter 1. Admin Guide
88 90
 
89 91
    5. Functions
90 92
 
91
-        5.1. ws_handle_handshake()
93
+        5.1. ws_handle_handshake() 
92 94
 
93 95
    6. MI Commands
94 96
 
... ...
@@ -101,14 +103,14 @@ Chapter 1. Admin Guide
101 103
 
102 104
    7. Event routes
103 105
 
104
-        7.1. websocket:closed
106
+        7.1. websocket:closed 
105 107
 
106 108
 1. Overview
107 109
 
108
-   This module implements a WebSocket (RFC 6455) server and provides
109
-   connection establishment (handshaking), management (including
110
-   connection keep-alive), and framing for the SIP and MSRP WebSocket
111
-   sub-protocols (draft-ietf-sipcore-sip-websocket and
110
+   This  module  implements  a  WebSocket  (RFC 6455) server and provides
111
+   connection    establishment   (handshaking),   management   (including
112
+   connection  keep-alive),  and  framing  for the SIP and MSRP WebSocket
113
+   sub-protocols           (draft-ietf-sipcore-sip-websocket          and
112 114
    draft-pd-msrp-websocket).
113 115
 
114 116
    The module supports WebSockets (ws) and secure WebSockets (wss)
... ...
@@ -122,15 +124,15 @@ Chapter 1. Admin Guide
122 124
 2.1. Initiating a connection
123 125
 
124 126
    A WebSocket connection is initiated with an HTTP GET. The xhttp module
125
-   is used to handle this GET and call the Section 5.1, “
126
-   ws_handle_handshake() ” exported function.
127
+   is   used   to   handle   this   GET   and  call  the  Section 5.1,  "
128
+   ws_handle_handshake() " exported function.
127 129
 
128
-   event_route[xhttp:request] should perform some validation of the HTTP
129
-   headers before calling Section 5.1, “ ws_handle_handshake() ”. The
130
+   event_route[xhttp:request]  should perform some validation of the HTTP
131
+   headers  before  calling  Section 5.1,  " ws_handle_handshake() ". The
130 132
    event_route can also be used to make sure the HTTP GET has the correct
131
-   URI, perform HTTP authentication on the WebSocket connection, and check
132
-   the Origin header (RFC 6454) to ensure a browser-based SIP UA or MSRP
133
-   client has been downloaded from the correct location.
133
+   URI,  perform  HTTP  authentication  on  the WebSocket connection, and
134
+   check the Origin header (RFC 6454) to ensure a browser-based SIP UA or
135
+   MSRP client has been downloaded from the correct location.
134 136
 
135 137
    Example 1.1. event_route[xhttp:request]
136 138
 ...
... ...
@@ -196,21 +198,22 @@ event_route[xhttp:request] {
196 198
 
197 199
 2.2. SIP message routing
198 200
 
199
-   SIP over WebSockets uses invalid URIs in routing headers (Contact:,
200
-   Record-Route:, and Via:) because a JavaScript stack running in a
201
-   browser has no way to determine the local address from which the
202
-   WebSocket connection is made. This means that the routing headers
201
+   SIP  over  WebSockets  uses invalid URIs in routing headers (Contact:,
202
+   Record-Route:,  and  Via:)  because  a  JavaScript  stack running in a
203
+   browser  has  no  way  to  determine  the local address from which the
204
+   WebSocket  connection  is  made.  This  means that the routing headers
203 205
    cannot be used for request or response routing in the normal manner.
204 206
 
205 207
    draft-ietf-sipcore-sip-websocket states that SIP WebSocket Clients and
206
-   the SIP registrar should implement Outbound (RFC 5626) and Path (RFC
207
-   3327) to enable requests and responses to be correctly routed. However,
208
-   Kamailio does not currently support Outbound and it may not be possible
209
-   to guarantee all SIP WebSocket clients will support Outbound and Path.
210
-
211
-   The nathelper module functions (nat_uac_test(), fix_nated_register(),
212
-   add_contact_alias(), and handle_ruri_alias()) and the Kamailio core
213
-   force_rport() can be used to ensure correct routing of SIP WebSocket
208
+   the  SIP  registrar should implement Outbound (RFC 5626) and Path (RFC
209
+   3327)  to  enable  requests  and  responses  to  be  correctly routed.
210
+   However,  Kamailio  does not currently support Outbound and it may not
211
+   be  possible  to  guarantee  all  SIP  WebSocket  clients will support
212
+   Outbound and Path.
213
+
214
+   The  nathelper module functions (nat_uac_test(), fix_nated_register(),
215
+   add_contact_alias(),  and  handle_ruri_alias())  and the Kamailio core
216
+   force_rport()  can  be used to ensure correct routing of SIP WebSocket
214 217
    requests without using Outbound and Path.
215 218
 
216 219
    Example 1.2. WebSocket SIP Routing
... ...
@@ -235,7 +238,8 @@ request_route {
235 238
                         fix_nated_register();
236 239
                 else {
237 240
                         if (!add_contact_alias()) {
238
-                                xlog("L_ERR", "Error aliasing contact <$ct>\n");
241
+                                xlog("L_ERR", "Error aliasing contact <$ct>\n")
242
+;
239 243
                                 sl_send_reply("400", "Bad Request");
240 244
                                 exit;
241 245
                         }
... ...
@@ -275,11 +279,11 @@ onreply_route[WS_REPLY] {
275 279
 
276 280
 2.3. MSRP message routing
277 281
 
278
-   MSRP over WebSocket clients create invalid local URIs for use in Path
279
-   headers (From-Path: and To-Path:) because a JavaScript stack running in
280
-   a browser has no way to determine the local address from which the
281
-   WebSocket connection is made. This is OK because MSRP over WebSocket
282
-   clients MUST use an MSRP relay and it is the MSRP relay's
282
+   MSRP  over WebSocket clients create invalid local URIs for use in Path
283
+   headers  (From-Path:  and To-Path:) because a JavaScript stack running
284
+   in  a browser has no way to determine the local address from which the
285
+   WebSocket  connection  is made. This is OK because MSRP over WebSocket
286
+   clients   MUST   use  an  MSRP  relay  and  it  is  the  MSRP  relay's
283 287
    responsibility to select the correct connection to the client based on
284 288
    the MSRP URIs that it has created (and maintains a mapping for).
285 289
 
... ...
@@ -298,7 +302,7 @@ onreply_route[WS_REPLY] {
298 302
      * tm.
299 303
      * xhttp.
300 304
 
301
-   The following module is required to use the secure WebSocket (wss)
305
+   The  following  module  is  required to use the secure WebSocket (wss)
302 306
    scheme:
303 307
      * tls.
304 308
 
... ...
@@ -327,10 +331,10 @@ onreply_route[WS_REPLY] {
327 331
 
328 332
 Note
329 333
 
330
-   If nathelper is only being used for WebSocket connections then
331
-   nathelper NAT pinging is not required. If nathelper is used for
332
-   WebSocket connections and TCP/TLS aliasing/NAT-traversal then WebSocket
333
-   keep-alives are not required.
334
+   If  nathelper  is  only  being  used  for  WebSocket  connections then
335
+   nathelper  NAT  pinging  is  not  required.  If  nathelper is used for
336
+   WebSocket   connections   and   TCP/TLS   aliasing/NAT-traversal  then
337
+   WebSocket keep-alives are not required.
334 338
 
335 339
      * 0 - no WebSocket keep-alives
336 340
      * 1 - Ping WebSocket keep-alives
... ...
@@ -345,7 +349,7 @@ modparam("websocket", "keepalive_mechanism", 0)
345 349
 
346 350
 4.2. keepalive_timeout (integer)
347 351
 
348
-   The time (in seconds) after which to send a keep-alive on idle
352
+   The  time  (in  seconds)  after  which  to  send  a keep-alive on idle
349 353
    WebSocket connections.
350 354
 
351 355
    Default value is 180.
... ...
@@ -357,7 +361,7 @@ modparam("websocket", "keepalive_timeout", 30)
357 361
 
358 362
 4.3. keepalive_processes (integer)
359 363
 
360
-   The number of processes to start to perform WebSocket connection
364
+   The  number  of  processes  to  start  to perform WebSocket connection
361 365
    keep-alives.
362 366
 
363 367
    Default value is 1.
... ...
@@ -397,7 +401,8 @@ modparam("websocket", "ping_application_data", "WebSockets rock")
397 401
      * 2 - msrp (draft-pd-msrp-websocket) - msrp.so must be loaded before
398 402
        websocket.so
399 403
 
400
-   Default value is 1 when msrp.so is not loaded 3 when msrp.so is loaded.
404
+   Default  value  is  1  when  msrp.so  is  not loaded 3 when msrp.so is
405
+   loaded.
401 406
 
402 407
    Example 1.8. Set sub_protocols parameter
403 408
 ...
... ...
@@ -406,20 +411,20 @@ modparam("websocket", "sub_protocols", 2)
406 411
 
407 412
 5. Functions
408 413
 
409
-   5.1. ws_handle_handshake()
414
+   5.1. ws_handle_handshake() 
410 415
 
411 416
 5.1.  ws_handle_handshake()
412 417
 
413
-   This function checks an HTTP GET request for the required headers and
414
-   values, and (if successful) upgrades the connection from HTTP to
418
+   This  function checks an HTTP GET request for the required headers and
419
+   values,  and  (if  successful)  upgrades  the  connection from HTTP to
415 420
    WebSocket.
416 421
 
417
-   This function can be used from ANY_ROUTE (but will only work in
422
+   This  function  can  be  used  from  ANY_ROUTE  (but will only work in
418 423
    event_route[xhttp:request]).
419 424
 
420 425
 Note
421 426
 
422
-   This function returns 0, stopping all further processing of the
427
+   This  function  returns  0,  stopping  all  further  processing of the
423 428
    request, when there is a problem.
424 429
 
425 430
    Example 1.9. ws_handle_handshake usage
... ...
@@ -443,7 +448,7 @@ ws_handle_handshake();
443 448
    Name: ws.dump
444 449
 
445 450
    Parameters:
446
-     * order (optional) - “id_hash”, “used_desc”, or “used_asc”.
451
+     * order (optional) - "id_hash", "used_desc", or "used_asc".
447 452
 
448 453
 Note
449 454
 
... ...
@@ -526,13 +531,15 @@ Note
526 531
 
527 532
 7. Event routes
528 533
 
529
-   7.1. websocket:closed
534
+   7.1. websocket:closed 
530 535
 
531 536
 7.1.  websocket:closed
532 537
 
533
-   When defined, the module calls event_route[websocket:closed] when a
534
-   connection closes. The connection may be identified using the the $si
538
+   When  defined,  the  module calls event_route[websocket:closed] when a
539
+   connection  closes. The connection may be identified using the the $si
535 540
    and $sp pseudo-variables.
541
+
542
+   Example 1.10. event_route[websocket:closed] usage
536 543
 ...
537 544
 event_route[websocket:closed] {
538 545
         xlog("L_INFO", "WebSocket connection from $si:$sp has closed\n");
... ...
@@ -30,11 +30,11 @@
30 30
 	<title>Initiating a connection</title>
31 31
 	<para>A WebSocket connection is initiated with an HTTP GET.  The
32 32
 	<emphasis>xhttp</emphasis> module is used to handle this GET and
33
-	call the <xref linkend="ws_handle_handshake"/> exported function.
33
+	call the <xref linkend="websocket.f.ws_handle_handshake"/> exported function.
34 34
 	</para>
35 35
 	<para><emphasis>event_route[xhttp:request]</emphasis> should perform
36 36
 	some validation of the HTTP headers before calling
37
-	<xref linkend="ws_handle_handshake"/>.  The event_route can also be
37
+	<xref linkend="websocket.f.ws_handle_handshake"/>.  The event_route can also be
38 38
 	used to make sure the HTTP GET has the correct URI, perform HTTP
39 39
 	authentication on the WebSocket connection, and check the
40 40
 	<emphasis>Origin</emphasis> header (RFC 6454) to ensure a
... ...
@@ -275,7 +275,7 @@ onreply_route[WS_REPLY] {
275 275
 
276 276
 	<section>
277 277
 	<title>Parameters</title>
278
-	<section>
278
+	<section id="websocket.p.keepalive_mechanism">
279 279
 		<title><varname>keepalive_mechanism</varname> (integer)</title>
280 280
 		<para>The keep-alive mechanism to use for WebSocket connections.
281 281
 		</para>
... ...
@@ -306,7 +306,7 @@ modparam("websocket", "keepalive_mechanism", 0)
306 306
 		</example>
307 307
 	</section>
308 308
 
309
-	<section>
309
+	<section id="websocket.p.keepalive_timeout">
310 310
 		<title><varname>keepalive_timeout</varname> (integer)</title>
311 311
 		<para>The time (in seconds) after which to send a keep-alive on
312 312
 		idle WebSocket connections.</para>
... ...
@@ -322,7 +322,7 @@ modparam("websocket", "keepalive_timeout", 30)
322 322
 		</example>
323 323
 	</section>
324 324
 
325
-	<section>
325
+	<section id="websocket.p.keepalive.processes">
326 326
 		<title><varname>keepalive_processes</varname> (integer)</title>
327 327
 		<para>The number of processes to start to perform WebSocket
328 328
 		connection keep-alives.</para>
... ...
@@ -338,7 +338,7 @@ modparam("websocket", "keepalive_processes", 2)
338 338
 		</example>
339 339
 	</section>
340 340
 
341
-	<section>
341
+	<section id="websocket.p.keepalive_interval">
342 342
 		<title><varname>keepalive_interval</varname> (integer)</title>
343 343
 		<para>The number of seconds between each keep-alice process run
344 344
 		</para>
... ...
@@ -354,7 +354,7 @@ modparam("websocket", "keepalive_interval", 2)
354 354
 		</example>
355 355
 	</section>
356 356
 
357
-	<section>
357
+	<section id="websocket.p.ping_application_data">
358 358
 		<title><varname>ping_application_data</varname> (string)</title>
359 359
 		<para>The application data to use in keep-alive Ping and Pong
360 360
 		frames.</para>
... ...
@@ -371,7 +371,7 @@ modparam("websocket", "ping_application_data", "WebSockets rock")
371 371
 		</example>
372 372
 	</section>
373 373
 
374
-	<section>
374
+	<section id="websocket.p.sub_protocols">
375 375
 		<title><varname>sub_protocols</varname> (integer)</title>
376 376
 		<para>A bitmap that allows you to control the sub-protocols
377 377
 		supported by the WebSocket server.</para>
... ...
@@ -401,7 +401,7 @@ modparam("websocket", "sub_protocols", 2)
401 401
 
402 402
 	<section>
403 403
 	<title>Functions</title>
404
-	<section id="ws_handle_handshake">
404
+	<section id="websocket.f.ws_handle_handshake">
405 405
 		<title>
406 406
 		<function moreinfo="none">ws_handle_handshake()</function>
407 407
 		</title>
... ...
@@ -425,7 +425,7 @@ ws_handle_handshake();
425 425
 
426 426
 	<section>
427 427
 	<title>MI Commands</title>
428
-	<section>
428
+	<section id="websocket.m.ws.dump">
429 429
 		<title><function moreinfo="none">ws.dump</function></title>
430 430
 		<para>Provides the details of the first 50 WebSocket
431 431
 		connections.</para>
... ...
@@ -449,7 +449,7 @@ ws_handle_handshake();
449 449
 </programlisting>
450 450
 	</section>
451 451
 
452
-	<section>
452
+	<section id="websocket.m.ws.close">
453 453
 		<title><function moreinfo="none">ws.close</function></title>
454 454
 		<para>Starts the close handshake for the specified
455 455
 		WebSocket connection.</para>
... ...
@@ -468,7 +468,7 @@ ws_handle_handshake();
468 468
 </programlisting>
469 469
 	</section>
470 470
 
471
-	<section>
471
+	<section id="websocket.m.ping">
472 472
 		<title><function moreinfo="none">ws.ping</function></title>
473 473
 		<para>Sends a Ping frame on the specified WebSocket
474 474
 		connection.</para>
... ...
@@ -487,7 +487,7 @@ ws_handle_handshake();
487 487
 </programlisting>
488 488
 	</section>
489 489
 
490
-	<section>
490
+	<section id="websocket.m.ws.pong">
491 491
 		<title><function moreinfo="none">ws.pong</function></title>
492 492
 		<para>Sends a Pong frame on the specified WebSocket
493 493
 		connection.</para>
... ...
@@ -506,7 +506,7 @@ ws_handle_handshake();
506 506
 </programlisting>
507 507
 	</section>
508 508
 
509
-	<section>
509
+	<section id="websocket.m.ws.disable">
510 510
 		<title><function moreinfo="none">ws.disable</function></title>
511 511
 		<para>Disables WebSockets preventing new connections from
512 512
 		being established.</para>
... ...
@@ -519,7 +519,7 @@ ws_handle_handshake();
519 519
 </programlisting>
520 520
 	</section>
521 521
 
522
-	<section>
522
+	<section id="websocket.m.ws.enable">
523 523
 		<title><function moreinfo="none">ws.enable</function></title>
524 524
 		<para>Enables WebSockets allowing new connections to be
525 525
 		established.</para>
... ...
@@ -537,7 +537,7 @@ ws_handle_handshake();
537 537
 
538 538
 	<section>
539 539
 	<title>Event routes</title>
540
-	<section>
540
+	<section id="websocket.e.closed">
541 541
 		<title>
542 542
 		<function moreinfo="none">websocket:closed</function>
543 543
 		</title>
... ...
@@ -547,13 +547,16 @@ ws_handle_handshake();
547 547
 			closes.  The connection may be identified using the
548 548
 			the $si and $sp pseudo-variables.
549 549
 		</para>
550
-		<programlisting format="linespecific">
550
+		<example>
551
+		<title><function moreinfo="none">event_route[websocket:closed]</function> usage</title>
552
+			<programlisting format="linespecific">
551 553
 ...
552 554
 event_route[websocket:closed] {
553 555
 	xlog("L_INFO", "WebSocket connection from $si:$sp has closed\n");
554 556
 }
555 557
 ...
556
-		</programlisting>
558
+			</programlisting>
559
+		</example>
557 560
 	</section>
558 561
 
559 562
 	</section>