class Poco::Net::WebSocket

Overview

This class implements a WebSocket according to the WebSocket protocol specification in RFC 6455. More…

#include <WebSocket.h>

class WebSocket: public Poco::Net::StreamSocket
{
public:
    // enums

    enum ErrorCodes;
    enum FrameFlags;
    enum FrameOpcodes;
    enum Mode;
    enum SendFlags;
    enum StatusCodes;

    // fields

    static const std::string WEBSOCKET_VERSION;

    // construction

    WebSocket(
        HTTPServerRequest& request,
        HTTPServerResponse& response
        );

    WebSocket(
        HTTPClientSession& cs,
        HTTPRequest& request,
        HTTPResponse& response
        );

    WebSocket(
        HTTPClientSession& cs,
        HTTPRequest& request,
        HTTPResponse& response,
        HTTPCredentials& credentials
        );

    WebSocket(const Socket& socket);

    // methods

    WebSocket&
    operator=(const Socket& socket);

    void
    shutdown();

    void
    shutdown(
        Poco::UInt16 statusCode,
        const std::string& statusMessage = ""
        );

    int
    sendFrame(
        const void* buffer,
        int length,
        int flags = FRAME_TEXT
        );

    int
    receiveFrame(
        void* buffer,
        int length,
        int& flags
        );

    Mode
    mode() const;

protected:
    // methods

    static
    WebSocketImpl*
    accept(
        HTTPServerRequest& request,
        HTTPServerResponse& response
        );

    static
    WebSocketImpl*
    connect(
        HTTPClientSession& cs,
        HTTPRequest& request,
        HTTPResponse& response,
        HTTPCredentials& credentials
        );

    static
    WebSocketImpl*
    completeHandshake(
        HTTPClientSession& cs,
        HTTPResponse& response,
        const std::string& key
        );

    static
    std::string
    computeAccept(const std::string& key);

    static
    std::string
    createKey();
};

Inherited Members

public:
    // typedefs

    typedef std::vector<Socket> SocketList;

    // enums

    enum SelectMode;

    // methods

    Socket&
    operator=(const Socket& socket);

    bool
    operator==(const Socket& socket) const;

    bool
    operator!=(const Socket& socket) const;

    bool
    operator<(const Socket& socket) const;

    bool
    operator<=(const Socket& socket) const;

    bool
    operator>(const Socket& socket) const;

    bool
    operator>=(const Socket& socket) const;

    void
    close();

    bool
    poll(
        const Poco::Timespan& timeout,
        int mode
        ) const;

    int
    available() const;

    void
    setSendBufferSize(int size);

    int
    getSendBufferSize() const;

    void
    setReceiveBufferSize(int size);

    int
    getReceiveBufferSize() const;

    void
    setSendTimeout(const Poco::Timespan& timeout);

    Poco::Timespan
    getSendTimeout() const;

    void
    setReceiveTimeout(const Poco::Timespan& timeout);

    Poco::Timespan
    getReceiveTimeout() const;

    void
    setOption(
        int level,
        int option,
        int value
        );

    void
    setOption(
        int level,
        int option,
        unsigned value
        );

    void
    setOption(
        int level,
        int option,
        unsigned char value
        );

    void
    setOption(
        int level,
        int option,
        const Poco::Timespan& value
        );

    void
    setOption(
        int level,
        int option,
        const IPAddress& value
        );

    void
    getOption(
        int level,
        int option,
        int& value
        ) const;

    void
    getOption(
        int level,
        int option,
        unsigned& value
        ) const;

    void
    getOption(
        int level,
        int option,
        unsigned char& value
        ) const;

    void
    getOption(
        int level,
        int option,
        Poco::Timespan& value
        ) const;

    void
    getOption(
        int level,
        int option,
        IPAddress& value
        ) const;

    void
    setLinger(
        bool on,
        int seconds
        );

    void
    getLinger(
        bool& on,
        int& seconds
        ) const;

    void
    setNoDelay(bool flag);

    bool
    getNoDelay() const;

    void
    setKeepAlive(bool flag);

    bool
    getKeepAlive() const;

    void
    setReuseAddress(bool flag);

    bool
    getReuseAddress() const;

    void
    setReusePort(bool flag);

    bool
    getReusePort() const;

    void
    setOOBInline(bool flag);

    bool
    getOOBInline() const;

    void
    setBlocking(bool flag);

    bool
    getBlocking() const;

    SocketAddress
    address() const;

    SocketAddress
    peerAddress() const;

    SocketImpl*
    impl() const;

    bool
    secure() const;

    void
    init(int af);

    static
    int
    select(
        SocketList& readList,
        SocketList& writeList,
        SocketList& exceptList,
        const Poco::Timespan& timeout
        );

    static
    bool
    supportsIPv4();

    static
    bool
    supportsIPv6();

    StreamSocket&
    operator=(const Socket& socket);

    void
    connect(const SocketAddress& address);

    void
    connect(
        const SocketAddress& address,
        const Poco::Timespan& timeout
        );

    void
    connectNB(const SocketAddress& address);

    void
    shutdownReceive();

    void
    shutdownSend();

    void
    shutdown();

    int
    sendBytes(
        const void* buffer,
        int length,
        int flags = 0
        );

    int
    sendBytes(Poco::FIFOBuffer& buffer);

    int
    receiveBytes(
        void* buffer,
        int length,
        int flags = 0
        );

    int
    receiveBytes(Poco::FIFOBuffer& buffer);

    void
    sendUrgent(unsigned char data);

protected:
    // methods

    poco_socket_t
    sockfd() const;

Detailed Documentation

This class implements a WebSocket according to the WebSocket protocol specification in RFC 6455.

Both client-side and server-side WebSockets are supported.

Server-side WebSockets are usually created from within a HTTPRequestHandler.

Client-side WebSockets are created using a HTTPClientSession.

Note that special frames like PING must be handled at application level. In the case of a PING, a PONG message must be returned.

Fields

static const std::string WEBSOCKET_VERSION

The WebSocket protocol version supported (13).

Construction

WebSocket(
    HTTPServerRequest& request,
    HTTPServerResponse& response
    )

Creates a server-side WebSocket from within a HTTPRequestHandler.

First verifies that the request is a valid WebSocket upgrade request. If so, completes the handshake by sending a proper 101 response.

Throws an exception if the request is not a proper WebSocket upgrade request.

WebSocket(
    HTTPClientSession& cs,
    HTTPRequest& request,
    HTTPResponse& response
    )

Creates a client-side WebSocket, using the given HTTPClientSession and HTTPRequest for the initial handshake (HTTP Upgrade request).

Additional HTTP headers for the initial handshake request (such as Origin or Sec-WebSocket-Protocol) can be given in the request object.

The result of the handshake can be obtained from the response object.

WebSocket(
    HTTPClientSession& cs,
    HTTPRequest& request,
    HTTPResponse& response,
    HTTPCredentials& credentials
    )

Creates a client-side WebSocket, using the given HTTPClientSession and HTTPRequest for the initial handshake (HTTP Upgrade request).

The given credentials are used for authentication if requested by the server.

Additional HTTP headers for the initial handshake request (such as Origin or Sec-WebSocket-Protocol) can be given in the request object.

The result of the handshake can be obtained from the response object.

WebSocket(const Socket& socket)

Creates a WebSocket from another Socket, which must be a WebSocket, otherwise a Poco::InvalidArgumentException will be thrown.

Methods

WebSocket&
operator=(const Socket& socket)

Assignment operator.

The other socket must be a WebSocket, otherwise a Poco::InvalidArgumentException will be thrown.

void
shutdown()

Sends a Close control frame to the server end of the connection to initiate an orderly shutdown of the connection.

void
shutdown(
    Poco::UInt16 statusCode,
    const std::string& statusMessage = ""
    )

Sends a Close control frame to the server end of the connection to initiate an orderly shutdown of the connection.

int
sendFrame(
    const void* buffer,
    int length,
    int flags = FRAME_TEXT
    )

Sends the contents of the given buffer through the socket as a single frame.

Values from the FrameFlags, FrameOpcodes and SendFlags enumerations can be specified in flags.

Returns the number of bytes sent, which may be less than the number of bytes specified.

Certain socket implementations may also return a negative value denoting a certain condition.

int
receiveFrame(
    void* buffer,
    int length,
    int& flags
    )

Receives a frame from the socket and stores it in buffer.

Up to length bytes are received. If the frame’s payload is larger, a WebSocketException is thrown and the WebSocket connection must be terminated.

Returns the number of bytes received. A return value of 0 means that the peer has shut down or closed the connection.

Throws a TimeoutException if a receive timeout has been set and nothing is received within that interval. Throws a NetException (or a subclass) in case of other errors.

The frame flags and opcode (FrameFlags and FrameOpcodes) is stored in flags.

Mode
mode() const

Returns WS_SERVER if the WebSocket is a server-side WebSocket, or WS_CLIENT otherwise.