From aaa4ccc28461cd69d0bfb5d0a4eed59c86b88ea1 Mon Sep 17 00:00:00 2001
From: Thomas Kriechbaumer <thomas@kriechbaumer.name>
Date: Sun, 13 Nov 2016 21:12:43 +0100
Subject: websocket: add event documentation

---
 docs/scripting/events.rst | 58 +++++++++++++++++++++++++++++++++++++----------
 1 file changed, 46 insertions(+), 12 deletions(-)

diff --git a/docs/scripting/events.rst b/docs/scripting/events.rst
index 69b829a3..a0fc1243 100644
--- a/docs/scripting/events.rst
+++ b/docs/scripting/events.rst
@@ -158,12 +158,15 @@ HTTP Events
 WebSocket Events
 -----------------
 
+These events are called only after a connection made an HTTP upgrade with
+"101 Switching Protocols". No further HTTP-related events after the handshake
+are issued, only new WebSocket messages are called.
+
 .. list-table::
     :widths: 40 60
     :header-rows: 0
 
     *   - .. py:function:: websocket_handshake(flow)
-
         - Called when a client wants to establish a WebSocket connection. The
           WebSocket-specific headers can be manipulated to manipulate the
           handshake. The ``flow`` object is guaranteed to have a non-None
@@ -173,6 +176,36 @@ WebSocket Events
             The flow containing the HTTP WebSocket handshake request. The
             object is guaranteed to have a non-None ``request`` attribute.
 
+    *   - .. py:function:: websocket_start(flow)
+        - Called when WebSocket connection is established after a successful
+          handshake.
+
+          *flow*
+            A ``models.WebSocketFlow`` object.
+
+    *   - .. py:function:: websocket_message(flow)
+
+        - Called when a WebSocket message is received from the client or server. The
+          sender and receiver are identifiable. The most recent message will be
+          ``flow.messages[-1]``. The message is user-modifiable. Currently there are
+          two types of messages, corresponding to the BINARY and TEXT frame types.
+
+          *flow*
+            A ``models.WebSocketFlow`` object.
+
+    *   - .. py:function:: websocket_end(flow)
+        - Called when WebSocket connection ends.
+
+          *flow*
+            A ``models.WebSocketFlow`` object.
+
+    *   - .. py:function:: websocket_error(flow)
+        - Called when a WebSocket error occurs - e.g. the connection closing
+          unexpectedly.
+
+          *flow*
+            A ``models.WebSocketFlow`` object.
+
 
 TCP Events
 ----------
@@ -185,30 +218,31 @@ connections.
     :widths: 40 60
     :header-rows: 0
 
-    *   - .. py:function:: tcp_end(flow)
-        - Called when TCP streaming ends.
-
-          *flow*
-            A ``models.TCPFlow`` object.
 
-    *   - .. py:function:: tcp_error(flow)
-        - Called when a TCP error occurs - e.g. the connection closing
-          unexpectedly.
+    *   - .. py:function:: tcp_start(flow)
+        - Called when TCP streaming starts.
 
           *flow*
             A ``models.TCPFlow`` object.
 
     *   - .. py:function:: tcp_message(flow)
 
-        - Called a TCP payload is received from the client or server. The
+        - Called when a TCP payload is received from the client or server. The
           sender and receiver are identifiable. The most recent message will be
           ``flow.messages[-1]``. The message is user-modifiable.
 
           *flow*
             A ``models.TCPFlow`` object.
 
-    *   - .. py:function:: tcp_start(flow)
-        - Called when TCP streaming starts.
+    *   - .. py:function:: tcp_end(flow)
+        - Called when TCP streaming ends.
+
+          *flow*
+            A ``models.TCPFlow`` object.
+
+    *   - .. py:function:: tcp_error(flow)
+        - Called when a TCP error occurs - e.g. the connection closing
+          unexpectedly.
 
           *flow*
             A ``models.TCPFlow`` object.
-- 
cgit v1.2.3