117 lines
4.4 KiB
ReStructuredText
117 lines
4.4 KiB
ReStructuredText
Introduction
|
|
============
|
|
|
|
The class :class:`autobahn.websocket.WebSocketProtocol` implements the
|
|
WebSocket protocol.
|
|
|
|
Though you will use methods and override callbacks from this class, you must
|
|
implement your clients/servers by deriving from the classes
|
|
:class:`autobahn.websocket.WebSocketClientProtocol` and
|
|
:class:`autobahn.websocket.WebSocketServerProtocol`.
|
|
|
|
|
|
Class Diagrams
|
|
--------------
|
|
|
|
|
|
* :class:`autobahn.websocket.WebSocketProtocol`
|
|
* :class:`autobahn.websocket.WebSocketClientProtocol`
|
|
* :class:`autobahn.websocket.WebSocketServerProtocol`
|
|
* :class:`autobahn.wamp.WampClientProtocol`
|
|
* :class:`autobahn.wamp.WampServerProtocol`
|
|
|
|
.. image:: protocolclasses.png
|
|
|
|
|
|
* :class:`autobahn.websocket.WebSocketClientFactory`
|
|
* :class:`autobahn.websocket.WebSocketServerFactory`
|
|
* :class:`autobahn.wamp.WampClientFactory`
|
|
* :class:`autobahn.wamp.WampServerFactory`
|
|
|
|
.. image:: factoryclasses.png
|
|
|
|
|
|
Basic API
|
|
---------
|
|
|
|
Most of the time, the basic API offered by *AutobahnPython*
|
|
will be the one you want to use. It is easy to use and gets out of your way.
|
|
|
|
The basic API is the one to use, unless you have specific needs (frame-based
|
|
processing or streaming), in which case Autobahn provides an advanced
|
|
API (see below).
|
|
|
|
The basic API consists of the following methods and callbacks
|
|
|
|
* :func:`autobahn.websocket.WebSocketProtocol.onOpen`
|
|
* :func:`autobahn.websocket.WebSocketProtocol.onMessage`
|
|
* :func:`autobahn.websocket.WebSocketProtocol.onClose`
|
|
* :func:`autobahn.websocket.WebSocketProtocol.sendMessage`
|
|
* :func:`autobahn.websocket.WebSocketProtocol.sendClose`
|
|
|
|
|
|
Advanced API
|
|
------------
|
|
|
|
A WebSockets message consists of a potentially unlimited number of
|
|
fragments ("message frames"), each of which can have a payload between 0
|
|
and 2^63 octets.
|
|
|
|
The implementation of the basic API is message-based, and thus has to buffer
|
|
all data received for a message frame, and buffer all frames received for
|
|
a message, and only when the message finally ends, flattens all buffered
|
|
data and fires :func:`autobahn.websocket.WebSocketProtocol.onMessage`.
|
|
|
|
Usually, when you produce/consume messages of small to limited size (like
|
|
say <256k), this is absolutely sufficient and convenient.
|
|
|
|
However, when you want to process messages consisting of a large number
|
|
of message fragments, or you want to process messages that contain message
|
|
fragments of large size, this buffering will result in excessive memory
|
|
consumption.
|
|
|
|
In these cases, you might want to process message fragments on a per
|
|
frame basis, or you may even want to process data incoming, as it arrives.
|
|
|
|
The advanced API provides you all the necessary methods and callbacks to
|
|
do WebSockets using frame-based processing or even completely streaming
|
|
processing - both sending and receiving.
|
|
|
|
API for frame-based processing:
|
|
|
|
* :func:`autobahn.websocket.WebSocketProtocol.onMessageBegin`
|
|
* :func:`autobahn.websocket.WebSocketProtocol.onMessageFrame`
|
|
* :func:`autobahn.websocket.WebSocketProtocol.onMessageEnd`
|
|
* :func:`autobahn.websocket.WebSocketProtocol.beginMessage`
|
|
* :func:`autobahn.websocket.WebSocketProtocol.sendMessageFrame`
|
|
* :func:`autobahn.websocket.WebSocketProtocol.endMessage`
|
|
|
|
API for streaming processing:
|
|
|
|
* :func:`autobahn.websocket.WebSocketProtocol.onMessageBegin`
|
|
* :func:`autobahn.websocket.WebSocketProtocol.onMessageFrameBegin`
|
|
* :func:`autobahn.websocket.WebSocketProtocol.onMessageFrameData`
|
|
* :func:`autobahn.websocket.WebSocketProtocol.onMessageFrameEnd`
|
|
* :func:`autobahn.websocket.WebSocketProtocol.onMessageEnd`
|
|
* :func:`autobahn.websocket.WebSocketProtocol.beginMessage`
|
|
* :func:`autobahn.websocket.WebSocketProtocol.beginMessageFrame`
|
|
* :func:`autobahn.websocket.WebSocketProtocol.sendMessageFrameData`
|
|
* :func:`autobahn.websocket.WebSocketProtocol.endMessage`
|
|
|
|
The advanced API for frame-based/streaming processing of WebSockets
|
|
messages also provides access to extension points in the WebSockets
|
|
protocol (you also normally won't use) - namely "reserved bits" and
|
|
"reserved opcodes".
|
|
|
|
Additionally, the advanced API provides methods and callbacks to do
|
|
your own processing of WebSockets Pings and Pongs. Normally, it is
|
|
unnecessary to do that, Autobahn will do the right thing under the hood.
|
|
Anyway, if you want, you can do.
|
|
|
|
API for explicit Ping/Pong processing:
|
|
|
|
* :func:`autobahn.websocket.WebSocketProtocol.onPing`
|
|
* :func:`autobahn.websocket.WebSocketProtocol.onPong`
|
|
* :func:`autobahn.websocket.WebSocketProtocol.sendPing`
|
|
* :func:`autobahn.websocket.WebSocketProtocol.sendPong`
|