Inheritance diagram for tornado.websocket.WebSocketHandler:

Public Member Functions
def	__init__
def	check_origin
def	close
def	get
def	on_close
def	on_connection_close
def	on_message
def	on_pong
def	open
def	ping
def	select_subprotocol
def	set_nodelay
def	write_message
Public Attributes
	close_code
	close_reason
	open_args
	open_kwargs
	stream
	ws_connection

Detailed Description

Subclass this class to create a basic WebSocket handler.

Override `on_message` to handle incoming messages, and use
`write_message` to send messages to the client. You can also
override `open` and `on_close` to handle opened and closed
connections.

See http://dev.w3.org/html5/websockets/ for details on the
JavaScript interface.  The protocol is specified at
http://tools.ietf.org/html/rfc6455.

Here is an example WebSocket handler that echos back all received messages
back to the client::

  class EchoWebSocket(websocket.WebSocketHandler):
      def open(self):
          print "WebSocket opened"

      def on_message(self, message):
          self.write_message(u"You said: " + message)

      def on_close(self):
          print "WebSocket closed"

WebSockets are not standard HTTP connections. The "handshake" is
HTTP, but after the handshake, the protocol is
message-based. Consequently, most of the Tornado HTTP facilities
are not available in handlers of this type. The only communication
methods available to you are `write_message()`, `ping()`, and
`close()`. Likewise, your request handler class should implement
`open()` method rather than ``get()`` or ``post()``.

If you map the handler above to ``/websocket`` in your application, you can
invoke it in JavaScript with::

  var ws = new WebSocket("ws://localhost:8888/websocket");
  ws.onopen = function() {
     ws.send("Hello, world");
  };
  ws.onmessage = function (evt) {
     alert(evt.data);
  };

This script pops up an alert box that says "You said: Hello, world".

Web browsers allow any site to open a websocket connection to any other,
instead of using the same-origin policy that governs other network
access from javascript.  This can be surprising and is a potential
security hole, so since Tornado 4.0 `WebSocketHandler` requires
applications that wish to receive cross-origin websockets to opt in
by overriding the `~WebSocketHandler.check_origin` method (see that
method's docs for details).  Failure to do so is the most likely
cause of 403 errors when making a websocket connection.

When using a secure websocket connection (``wss://``) with a self-signed
certificate, the connection from a browser may fail because it wants
to show the "accept this certificate" dialog but has nowhere to show it.
You must first visit a regular HTML page using the same certificate
to accept it before the websocket connection will succeed.

Definition at line 63 of file websocket.py.

Constructor & Destructor Documentation

def tornado.websocket.WebSocketHandler.__init__	(	self,
		application,
		request,
		kwargs
	)

Reimplemented from tornado.web.RequestHandler.

Definition at line 124 of file websocket.py.

Member Function Documentation

def tornado.websocket.WebSocketHandler.check_origin	(	self,
		origin
	)

Override to enable support for allowing alternate origins.

The ``origin`` argument is the value of the ``Origin`` HTTP
header, the url responsible for initiating this request.  This
method is not called for clients that do not send this header;
such requests are always allowed (because all browsers that
implement WebSockets support this header, and non-browser
clients do not have the same cross-site security concerns).

Should return True to accept the request or False to reject it.
By default, rejects all requests with an origin on a host other
than this one.

This is a security protection against cross site scripting attacks on
browsers, since WebSockets are allowed to bypass the usual same-origin
policies and don't use CORS headers.

To accept all cross-origin traffic (which was the default prior to
Tornado 4.0), simply override this method to always return true::

    def check_origin(self, origin):
return True

To allow connections from any subdomain of your site, you might
do something like::

    def check_origin(self, origin):
parsed_origin = urllib.parse.urlparse(origin)
return parsed_origin.netloc.endswith(".mydomain.com")

.. versionadded:: 4.0

Reimplemented in rosbridge_server.websocket_handler.RosbridgeWebSocket.

Definition at line 275 of file websocket.py.

def tornado.websocket.WebSocketHandler.close	(	self,
		code = `None`,
		reason = `None`
	)

Closes this Web Socket.

Once the close handshake is successful the socket will be closed.

``code`` may be a numeric status code, taken from the values
defined in `RFC 6455 section 7.4.1
<https://tools.ietf.org/html/rfc6455#section-7.4.1>`_.
``reason`` may be a textual message about why the connection is
closing.  These values are made available to the client, but are
not otherwise interpreted by the websocket protocol.

.. versionchanged:: 4.0

   Added the ``code`` and ``reason`` arguments.

Definition at line 255 of file websocket.py.

def tornado.websocket.WebSocketHandler.get	(	self,
		args,
		kwargs
	)

Reimplemented from tornado.web.RequestHandler.

Definition at line 133 of file websocket.py.

def tornado.websocket.WebSocketHandler.on_close ( self )

Invoked when the WebSocket is closed.

If the connection was closed cleanly and a status code or reason
phrase was supplied, these values will be available as the attributes
``self.close_code`` and ``self.close_reason``.

.. versionchanged:: 4.0

   Added ``close_code`` and ``close_reason`` attributes.

Reimplemented in rosbridge_server.websocket_handler.RosbridgeWebSocket, and tornado.test.websocket_test.TestWebSocketHandler.

Definition at line 242 of file websocket.py.

def tornado.websocket.WebSocketHandler.on_connection_close ( self )

Called in async handlers if the client closed the connection.

Override this to clean up resources associated with
long-lived connections.  Note that this method is called only if
the connection was closed during asynchronous processing; if you
need to do cleanup after every request override `on_finish`
instead.

Proxies may keep a connection open for a time (perhaps
indefinitely) after the client has gone away, so this method
may not be called promptly after the end user closes their
connection.

Reimplemented from tornado.web.RequestHandler.

Definition at line 333 of file websocket.py.

def tornado.websocket.WebSocketHandler.on_message	(	self,
		message
	)

Handle incoming messages on the WebSocket

This method must be overridden.

Reimplemented in rosbridge_server.websocket_handler.RosbridgeWebSocket, tornado.test.websocket_test.ErrorInOnMessageHandler, and tornado.test.websocket_test.EchoHandler.

Definition at line 225 of file websocket.py.

def tornado.websocket.WebSocketHandler.on_pong	(	self,
		data
	)

Invoked when the response to a ping frame is received.

Definition at line 238 of file websocket.py.

def tornado.websocket.WebSocketHandler.open ( self )

Invoked when a new WebSocket is opened.

The arguments to `open` are extracted from the `tornado.web.URLSpec`
regular expression, just like the arguments to
`tornado.web.RequestHandler.get`.

Reimplemented in tornado.test.websocket_test.CloseReasonHandler, tornado.test.websocket_test.HeaderHandler, and rosbridge_server.websocket_handler.RosbridgeWebSocket.

Definition at line 216 of file websocket.py.

def tornado.websocket.WebSocketHandler.ping	(	self,
		data
	)

Send ping frame to the remote end.

Definition at line 232 of file websocket.py.

def tornado.websocket.WebSocketHandler.select_subprotocol	(	self,
		subprotocols
	)

Invoked when a new WebSocket requests specific subprotocols.

``subprotocols`` is a list of strings identifying the
subprotocols proposed by the client.  This method may be
overridden to return one of those strings to select it, or
``None`` to not select a subprotocol.  Failure to select a
subprotocol does not automatically abort the connection,
although clients may close the connection if none of their
proposed subprotocols was selected.

Definition at line 203 of file websocket.py.

def tornado.websocket.WebSocketHandler.set_nodelay	(	self,
		value
	)

Set the no-delay flag for this stream.

By default, small messages may be delayed and/or combined to minimize
the number of packets sent.  This can sometimes cause 200-500ms delays
due to the interaction between Nagle's algorithm and TCP delayed
ACKs.  To reduce this delay (at the expense of possibly increasing
bandwidth usage), call ``self.set_nodelay(True)`` once the websocket
connection is established.

See `.BaseIOStream.set_nodelay` for additional details.

.. versionadded:: 3.1

Definition at line 317 of file websocket.py.

def tornado.websocket.WebSocketHandler.write_message	(	self,
		message,
		binary = `False`
	)

Sends the given message to the client of this Web Socket.

The message may be either a string or a dict (which will be
encoded as json).  If the ``binary`` argument is false, the
message will be sent as utf8; in binary mode any byte string
is allowed.

If the connection is already closed, raises `WebSocketClosedError`.

.. versionchanged:: 3.2
   `WebSocketClosedError` was added (previously a closed connection
   would raise an `AttributeError`)

Definition at line 183 of file websocket.py.