WebSocketSession Class Reference

#include <Pt/Http/WebSocketSession.h>

Server facade of one accepted WebSocket stream. More...

Inherits Connectable.

Public Member Functions
	WebSocketSession (WebSocketServlet &servlet, System::EventLoop &loop, Stream &stream)
	Binds stream on loop.
	~WebSocketSession ()
	Closes the stream.
WebSocketService &	service ()
	Returns the service that created this session.
const WebSocketService &	service () const
	Returns the service that created this session.
System::EventLoop &	loop ()
	Returns the loop that serializes this stream.
const System::EventLoop &	loop () const
	Returns the loop that serializes this stream.
WebSocketMessage &	incoming ()
	Returns the incoming message.
WebSocketMessage &	outgoing ()
	Returns the outgoing message.
void	beginSend ()
	Begins sending outgoing().
MessageProgress	endSend ()
	Completes the send started by beginSend().
void	beginReceive ()
	Begins receiving into incoming().
MessageProgress	endReceive ()
	Completes the receive started by beginReceive().
void	ping (const char *payload=0, std::size_t n=0)
	Enqueues a ping with an optional payload of at most 125 bytes.
void	close (unsigned code=1000, const std::string &reason=std::string())
	Enqueues a close frame and ends the stream after the close handshake.
unsigned	closeCode () const
	Returns the close status code of the handshake that ended the stream.
const std::string &	closeReason () const
	Returns the close reason of the handshake that ended the stream.

Protected Member Functions
virtual void	onInput ()=0
	Called when data bytes were received.
virtual void	onOutput ()=0
	Called when data bytes were sent.
virtual void	onClose ()=0
	Called when the stream has ended.

Detailed Description

WebSocketSession is the application object of one upgraded stream. Derive from it to keep the state that must survive from one message to the next: a subscription, a cursor, a user, or a reference into the application domain. The HTTP server already owns the connection and the stream. This session formats messages on that stream. It is not a stream-session bind the application performs, and it is not a request responder. The handshake responder has already been released when the session begins. A server does not mask the frames it writes.

The example starts a receive in the constructor and reads each payload from the input callback. Domain state belongs in the derived session.

class EchoSession : public Pt::Http::WebSocketSession
{
    public:
        EchoSession(Pt::Http::WebSocketServlet& servlet,
                    Pt::System::EventLoop& loop,
                    Pt::Http::Stream& stream)
        : Pt::Http::WebSocketSession(servlet, loop, stream)
        {
            beginReceive();
        }
 
    protected:
        virtual void onInput()
        {
            Pt::Http::MessageProgress progress = endReceive();
            if( ! progress.finished() )
            {
                incoming().discard();
                beginReceive();
                return;
            }
 
            incoming().clear();
            beginReceive();
        }
 
        virtual void onOutput()
        {
            endSend();
        }
 
        virtual void onClose()
        {}
};

The servlet constructs the session with itself, with the loop that serializes this stream, and with the stream of this upgrade. The loop must be the loop of the stream. The base constructor binds the stream, copies the service limits onto the connection, and stores the loop. The derived constructor runs after that. Its members are initialized, the stream is open, and loop() is the loop of this stream. Start the first beginReceive() or beginSend() there. There is no separate accept callback. By the time the derived constructor body runs, the base has already bound the stream.

incoming() and outgoing() are the two payloads. beginSend() writes outgoing(). beginReceive() reads into incoming(). onInput() runs when data bytes were received. Call endReceive(), read incoming() when progress reports body bytes, and start the next receive if the message is not finished. A ping or a pong does not run onInput(). onOutput() runs when data bytes were sent. Call endSend() and continue the send when progress is not finished. onClose() runs while this object is still alive, after the stream has ended. Do not call endReceive() or endSend() from onClose(). The servlet that holds this session releases it after onClose() returns.

service() reaches state shared by every connection of this endpoint. loop() is where a timer or posted work must run. Closing the session closes the stream. The session does not own the stream or the connection. The destructor closes the stream. A derived constructor that throws still runs this destructor, so a failed construction does not leave an accepted stream without an owner.

Ping and close stay control operations on this type.

ping();
close(1000, "done");

ping() enqueues a ping. close() enqueues a close frame. closeCode() and closeReason() report the handshake that ended the stream.

Constructor & Destructor Documentation

WebSocketSession()

WebSocketSession	(	WebSocketServlet &	servlet,
		System::EventLoop &	loop,
		Stream &	stream )

servlet holds this session. loop must be the loop of stream.

Exceptions

%std::logic_error

if loop is not the loop of stream.

Member Function Documentation

endSend()

MessageProgress endSend

(

)

Returns

Progress of this send step.

endReceive()

MessageProgress endReceive

(

)

Returns

Progress of this receive step.

onClose()

virtual void onClose ( )

protectedpure virtual

This object is still alive. The servlet releases it after this call returns. Do not call endReceive() or endSend().