modules/websocket: Update README xml with section IDs

modules/websocket/README

@@ -1,11 +1,12 @@
+
 WebSocket Module
 
 Peter Dunkley
 
    Crocodile RCS Ltd
 
-   Copyright © 2012-2013 Crocodile RCS Ltd
-     __________________________________________________________________
+   Copyright © 2012-2013 Crocodile RCS Ltd
+     _________________________________________________________________
 
    Table of Contents
 
@@ -34,7 +35,7 @@ Peter Dunkley
 
         5. Functions
 
-              5.1. ws_handle_handshake()
+              5.1. ws_handle_handshake() 
 
         6. MI Commands
 
@@ -47,7 +48,7 @@ Peter Dunkley
 
         7. Event routes
 
-              7.1. websocket:closed
+              7.1. websocket:closed 
 
    List of Examples
 
@@ -60,6 +61,7 @@ Peter Dunkley
    1.7. Set ping_application_data parameter
    1.8. Set sub_protocols parameter
    1.9. ws_handle_handshake usage
+   1.10. event_route[websocket:closed] usage
 
 Chapter 1. Admin Guide
 
@@ -88,7 +90,7 @@ Chapter 1. Admin Guide
 
    5. Functions
 
-        5.1. ws_handle_handshake()
+        5.1. ws_handle_handshake() 
 
    6. MI Commands
 
@@ -101,14 +103,14 @@ Chapter 1. Admin Guide
 
    7. Event routes
 
-        7.1. websocket:closed
+        7.1. websocket:closed 
 
 1. Overview
 
-   This module implements a WebSocket (RFC 6455) server and provides
-   connection establishment (handshaking), management (including
-   connection keep-alive), and framing for the SIP and MSRP WebSocket
-   sub-protocols (draft-ietf-sipcore-sip-websocket and
+   This  module  implements  a  WebSocket  (RFC 6455) server and provides
+   connection    establishment   (handshaking),   management   (including
+   connection  keep-alive),  and  framing  for the SIP and MSRP WebSocket
+   sub-protocols           (draft-ietf-sipcore-sip-websocket          and
    draft-pd-msrp-websocket).
 
    The module supports WebSockets (ws) and secure WebSockets (wss)
@@ -122,15 +124,15 @@ Chapter 1. Admin Guide
 2.1. Initiating a connection
 
    A WebSocket connection is initiated with an HTTP GET. The xhttp module
-   is used to handle this GET and call the Section 5.1, “
-   ws_handle_handshake() � exported function.
+   is   used   to   handle   this   GET   and  call  the  Section 5.1,  "
+   ws_handle_handshake() " exported function.
 
-   event_route[xhttp:request] should perform some validation of the HTTP
-   headers before calling Section 5.1, “ ws_handle_handshake() �. The
+   event_route[xhttp:request]  should perform some validation of the HTTP
+   headers  before  calling  Section 5.1,  " ws_handle_handshake() ". The
    event_route can also be used to make sure the HTTP GET has the correct
-   URI, perform HTTP authentication on the WebSocket connection, and check
-   the Origin header (RFC 6454) to ensure a browser-based SIP UA or MSRP
-   client has been downloaded from the correct location.
+   URI,  perform  HTTP  authentication  on  the WebSocket connection, and
+   check the Origin header (RFC 6454) to ensure a browser-based SIP UA or
+   MSRP client has been downloaded from the correct location.
 
    Example 1.1. event_route[xhttp:request]
 ...
@@ -196,21 +198,22 @@ event_route[xhttp:request] {
 
 2.2. SIP message routing
 
-   SIP over WebSockets uses invalid URIs in routing headers (Contact:,
-   Record-Route:, and Via:) because a JavaScript stack running in a
-   browser has no way to determine the local address from which the
-   WebSocket connection is made. This means that the routing headers
+   SIP  over  WebSockets  uses invalid URIs in routing headers (Contact:,
+   Record-Route:,  and  Via:)  because  a  JavaScript  stack running in a
+   browser  has  no  way  to  determine  the local address from which the
+   WebSocket  connection  is  made.  This  means that the routing headers
    cannot be used for request or response routing in the normal manner.
 
    draft-ietf-sipcore-sip-websocket states that SIP WebSocket Clients and
-   the SIP registrar should implement Outbound (RFC 5626) and Path (RFC
-   3327) to enable requests and responses to be correctly routed. However,
-   Kamailio does not currently support Outbound and it may not be possible
-   to guarantee all SIP WebSocket clients will support Outbound and Path.
-
-   The nathelper module functions (nat_uac_test(), fix_nated_register(),
-   add_contact_alias(), and handle_ruri_alias()) and the Kamailio core
-   force_rport() can be used to ensure correct routing of SIP WebSocket
+   the  SIP  registrar should implement Outbound (RFC 5626) and Path (RFC
+   3327)  to  enable  requests  and  responses  to  be  correctly routed.
+   However,  Kamailio  does not currently support Outbound and it may not
+   be  possible  to  guarantee  all  SIP  WebSocket  clients will support
+   Outbound and Path.
+
+   The  nathelper module functions (nat_uac_test(), fix_nated_register(),
+   add_contact_alias(),  and  handle_ruri_alias())  and the Kamailio core
+   force_rport()  can  be used to ensure correct routing of SIP WebSocket
    requests without using Outbound and Path.
 
    Example 1.2. WebSocket SIP Routing
@@ -235,7 +238,8 @@ request_route {
                         fix_nated_register();
                 else {
                         if (!add_contact_alias()) {
-                                xlog("L_ERR", "Error aliasing contact <$ct>\n");
+                                xlog("L_ERR", "Error aliasing contact <$ct>\n")
+;
                                 sl_send_reply("400", "Bad Request");
                                 exit;
                         }
@@ -275,11 +279,11 @@ onreply_route[WS_REPLY] {
 
 2.3. MSRP message routing
 
-   MSRP over WebSocket clients create invalid local URIs for use in Path
-   headers (From-Path: and To-Path:) because a JavaScript stack running in
-   a browser has no way to determine the local address from which the
-   WebSocket connection is made. This is OK because MSRP over WebSocket
-   clients MUST use an MSRP relay and it is the MSRP relay's
+   MSRP  over WebSocket clients create invalid local URIs for use in Path
+   headers  (From-Path:  and To-Path:) because a JavaScript stack running
+   in  a browser has no way to determine the local address from which the
+   WebSocket  connection  is made. This is OK because MSRP over WebSocket
+   clients   MUST   use  an  MSRP  relay  and  it  is  the  MSRP  relay's
    responsibility to select the correct connection to the client based on
    the MSRP URIs that it has created (and maintains a mapping for).
 
@@ -298,7 +302,7 @@ onreply_route[WS_REPLY] {
      * tm.
      * xhttp.
 
-   The following module is required to use the secure WebSocket (wss)
+   The  following  module  is  required to use the secure WebSocket (wss)
    scheme:
      * tls.
 
@@ -327,10 +331,10 @@ onreply_route[WS_REPLY] {
 
 Note
 
-   If nathelper is only being used for WebSocket connections then
-   nathelper NAT pinging is not required. If nathelper is used for
-   WebSocket connections and TCP/TLS aliasing/NAT-traversal then WebSocket
-   keep-alives are not required.
+   If  nathelper  is  only  being  used  for  WebSocket  connections then
+   nathelper  NAT  pinging  is  not  required.  If  nathelper is used for
+   WebSocket   connections   and   TCP/TLS   aliasing/NAT-traversal  then
+   WebSocket keep-alives are not required.
 
      * 0 - no WebSocket keep-alives
      * 1 - Ping WebSocket keep-alives
@@ -345,7 +349,7 @@ modparam("websocket", "keepalive_mechanism", 0)
 
 4.2. keepalive_timeout (integer)
 
-   The time (in seconds) after which to send a keep-alive on idle
+   The  time  (in  seconds)  after  which  to  send  a keep-alive on idle
    WebSocket connections.
 
    Default value is 180.
@@ -357,7 +361,7 @@ modparam("websocket", "keepalive_timeout", 30)
 
 4.3. keepalive_processes (integer)
 
-   The number of processes to start to perform WebSocket connection
+   The  number  of  processes  to  start  to perform WebSocket connection
    keep-alives.
 
    Default value is 1.
@@ -397,7 +401,8 @@ modparam("websocket", "ping_application_data", "WebSockets rock")
      * 2 - msrp (draft-pd-msrp-websocket) - msrp.so must be loaded before
        websocket.so
 
-   Default value is 1 when msrp.so is not loaded 3 when msrp.so is loaded.
+   Default  value  is  1  when  msrp.so  is  not loaded 3 when msrp.so is
+   loaded.
 
    Example 1.8. Set sub_protocols parameter
 ...
@@ -406,20 +411,20 @@ modparam("websocket", "sub_protocols", 2)
 
 5. Functions
 
-   5.1. ws_handle_handshake()
+   5.1. ws_handle_handshake() 
 
 5.1.  ws_handle_handshake()
 
-   This function checks an HTTP GET request for the required headers and
-   values, and (if successful) upgrades the connection from HTTP to
+   This  function checks an HTTP GET request for the required headers and
+   values,  and  (if  successful)  upgrades  the  connection from HTTP to
    WebSocket.
 
-   This function can be used from ANY_ROUTE (but will only work in
+   This  function  can  be  used  from  ANY_ROUTE  (but will only work in
    event_route[xhttp:request]).
 
 Note
 
-   This function returns 0, stopping all further processing of the
+   This  function  returns  0,  stopping  all  further  processing of the
    request, when there is a problem.
 
    Example 1.9. ws_handle_handshake usage
@@ -443,7 +448,7 @@ ws_handle_handshake();
    Name: ws.dump
 
    Parameters:
-     * order (optional) - “id_hash�, “used_desc�, or “used_asc�.
+     * order (optional) - "id_hash", "used_desc", or "used_asc".
 
 Note
 
@@ -526,13 +531,15 @@ Note
 
 7. Event routes
 
-   7.1. websocket:closed
+   7.1. websocket:closed 
 
 7.1.  websocket:closed
 
-   When defined, the module calls event_route[websocket:closed] when a
-   connection closes. The connection may be identified using the the $si
+   When  defined,  the  module calls event_route[websocket:closed] when a
+   connection  closes. The connection may be identified using the the $si
    and $sp pseudo-variables.
+
+   Example 1.10. event_route[websocket:closed] usage
 ...
 event_route[websocket:closed] {
         xlog("L_INFO", "WebSocket connection from $si:$sp has closed\n");

modules/websocket/doc/websocket_admin.xml

@@ -30,11 +30,11 @@
 	<title>Initiating a connection</title>
 	<para>A WebSocket connection is initiated with an HTTP GET.  The
 	<emphasis>xhttp</emphasis> module is used to handle this GET and
-	call the <xref linkend="ws_handle_handshake"/> exported function.
+	call the <xref linkend="websocket.f.ws_handle_handshake"/> exported function.
 	</para>
 	<para><emphasis>event_route[xhttp:request]</emphasis> should perform
 	some validation of the HTTP headers before calling
-	<xref linkend="ws_handle_handshake"/>.  The event_route can also be
+	<xref linkend="websocket.f.ws_handle_handshake"/>.  The event_route can also be
 	used to make sure the HTTP GET has the correct URI, perform HTTP
 	authentication on the WebSocket connection, and check the
 	<emphasis>Origin</emphasis> header (RFC 6454) to ensure a
@@ -275,7 +275,7 @@ onreply_route[WS_REPLY] {
 
 	<section>
 	<title>Parameters</title>
-	<section>
+	<section id="websocket.p.keepalive_mechanism">
 		<title><varname>keepalive_mechanism</varname> (integer)</title>
 		<para>The keep-alive mechanism to use for WebSocket connections.
 		</para>
@@ -306,7 +306,7 @@ modparam("websocket", "keepalive_mechanism", 0)
 		</example>
 	</section>
 
-	<section>
+	<section id="websocket.p.keepalive_timeout">
 		<title><varname>keepalive_timeout</varname> (integer)</title>
 		<para>The time (in seconds) after which to send a keep-alive on
 		idle WebSocket connections.</para>
@@ -322,7 +322,7 @@ modparam("websocket", "keepalive_timeout", 30)
 		</example>
 	</section>
 
-	<section>
+	<section id="websocket.p.keepalive.processes">
 		<title><varname>keepalive_processes</varname> (integer)</title>
 		<para>The number of processes to start to perform WebSocket
 		connection keep-alives.</para>
@@ -338,7 +338,7 @@ modparam("websocket", "keepalive_processes", 2)
 		</example>
 	</section>
 
-	<section>
+	<section id="websocket.p.keepalive_interval">
 		<title><varname>keepalive_interval</varname> (integer)</title>
 		<para>The number of seconds between each keep-alice process run
 		</para>
@@ -354,7 +354,7 @@ modparam("websocket", "keepalive_interval", 2)
 		</example>
 	</section>
 
-	<section>
+	<section id="websocket.p.ping_application_data">
 		<title><varname>ping_application_data</varname> (string)</title>
 		<para>The application data to use in keep-alive Ping and Pong
 		frames.</para>
@@ -371,7 +371,7 @@ modparam("websocket", "ping_application_data", "WebSockets rock")
 		</example>
 	</section>
 
-	<section>
+	<section id="websocket.p.sub_protocols">
 		<title><varname>sub_protocols</varname> (integer)</title>
 		<para>A bitmap that allows you to control the sub-protocols
 		supported by the WebSocket server.</para>
@@ -401,7 +401,7 @@ modparam("websocket", "sub_protocols", 2)
 
 	<section>
 	<title>Functions</title>
-	<section id="ws_handle_handshake">
+	<section id="websocket.f.ws_handle_handshake">
 		<title>
 		<function moreinfo="none">ws_handle_handshake()</function>
 		</title>
@@ -425,7 +425,7 @@ ws_handle_handshake();
 
 	<section>
 	<title>MI Commands</title>
-	<section>
+	<section id="websocket.m.ws.dump">
 		<title><function moreinfo="none">ws.dump</function></title>
 		<para>Provides the details of the first 50 WebSocket
 		connections.</para>
@@ -449,7 +449,7 @@ ws_handle_handshake();
 </programlisting>
 	</section>
 
-	<section>
+	<section id="websocket.m.ws.close">
 		<title><function moreinfo="none">ws.close</function></title>
 		<para>Starts the close handshake for the specified
 		WebSocket connection.</para>
@@ -468,7 +468,7 @@ ws_handle_handshake();
 </programlisting>
 	</section>
 
-	<section>
+	<section id="websocket.m.ping">
 		<title><function moreinfo="none">ws.ping</function></title>
 		<para>Sends a Ping frame on the specified WebSocket
 		connection.</para>
@@ -487,7 +487,7 @@ ws_handle_handshake();
 </programlisting>
 	</section>
 
-	<section>
+	<section id="websocket.m.ws.pong">
 		<title><function moreinfo="none">ws.pong</function></title>
 		<para>Sends a Pong frame on the specified WebSocket
 		connection.</para>
@@ -506,7 +506,7 @@ ws_handle_handshake();
 </programlisting>
 	</section>
 
-	<section>
+	<section id="websocket.m.ws.disable">
 		<title><function moreinfo="none">ws.disable</function></title>
 		<para>Disables WebSockets preventing new connections from
 		being established.</para>
@@ -519,7 +519,7 @@ ws_handle_handshake();
 </programlisting>
 	</section>
 
-	<section>
+	<section id="websocket.m.ws.enable">
 		<title><function moreinfo="none">ws.enable</function></title>
 		<para>Enables WebSockets allowing new connections to be
 		established.</para>
@@ -537,7 +537,7 @@ ws_handle_handshake();
 
 	<section>
 	<title>Event routes</title>
-	<section>
+	<section id="websocket.e.closed">
 		<title>
 		<function moreinfo="none">websocket:closed</function>
 		</title>
@@ -547,13 +547,16 @@ ws_handle_handshake();
 			closes.  The connection may be identified using the
 			the $si and $sp pseudo-variables.
 		</para>
-		<programlisting format="linespecific">
+		<example>
+		<title><function moreinfo="none">event_route[websocket:closed]</function> usage</title>
+			<programlisting format="linespecific">
 ...
 event_route[websocket:closed] {
 	xlog("L_INFO", "WebSocket connection from $si:$sp has closed\n");
 }
 ...
-		</programlisting>
+			</programlisting>
+		</example>
 	</section>
 
 	</section>