|
|
|
@@ -1,55 +1,61 @@
|
|
|
|
|
How to use this library
|
|
|
|
|
|
|
|
|
|
WebSocket++ is a C++ websocket server library implimented using the Boost Asio networking stack. It is designed to provide a simple interface
|
|
|
|
|
WebSocket++ is a C++ websocket server library implemented using the Boost Asio networking stack. It is designed to provide a simple interface.
|
|
|
|
|
|
|
|
|
|
Built on Asio's proactor asyncronious event loop.
|
|
|
|
|
Built on Asio's proactor asynchronous event loop.
|
|
|
|
|
|
|
|
|
|
Building a program using WebSocket++ has two parts
|
|
|
|
|
1. Impliment a connection handler.
|
|
|
|
|
This is done by subclassing websocketpp::connection_handler. Each websocket connection is attached to a connection handler. The handler impliments the following methods:
|
|
|
|
|
1. Implement a connection handler.
|
|
|
|
|
This is done by subclassing websocketpp::connection_handler. Each websocket connection is attached to a connection handler.
|
|
|
|
|
The handler implements the following methods:
|
|
|
|
|
|
|
|
|
|
validate:
|
|
|
|
|
Called after the client handshake is recieved but before the connection is accepted. Allows cookie authentication, origin checking, subprotocol negotiation, etc
|
|
|
|
|
Called after the client handshake is received but before the connection is accepted. Allows cookie authentication, origin checking, subprotocol negotiation, etc.
|
|
|
|
|
|
|
|
|
|
connect:
|
|
|
|
|
Called when the connection has been established and writes are allowed.
|
|
|
|
|
|
|
|
|
|
disconnect:
|
|
|
|
|
Called when the connection has been disconnected
|
|
|
|
|
Called when the connection has been disconnected.
|
|
|
|
|
|
|
|
|
|
message: text and binary variants
|
|
|
|
|
Called when a new websocket message is recieved.
|
|
|
|
|
Called when a new websocket message is received.
|
|
|
|
|
|
|
|
|
|
The handler has access to the following websocket session api:
|
|
|
|
|
The handler has access to the following websocket session API:
|
|
|
|
|
get_header
|
|
|
|
|
returns the value of an HTTP header sent by the client during the handshake
|
|
|
|
|
returns the value of an HTTP header sent by the client during the handshake.
|
|
|
|
|
|
|
|
|
|
get_request
|
|
|
|
|
returns the resource requested by the client in the handshake
|
|
|
|
|
returns the resource requested by the client in the handshake.
|
|
|
|
|
|
|
|
|
|
set_handler:
|
|
|
|
|
pass responsibility for this connection to another connection handler
|
|
|
|
|
pass responsibility for this connection to another connection handler.
|
|
|
|
|
|
|
|
|
|
set_http_error:
|
|
|
|
|
reject the connection with a specific HTTP error
|
|
|
|
|
reject the connection with a specific HTTP error.
|
|
|
|
|
|
|
|
|
|
add_header
|
|
|
|
|
adds an HTTP header to the server handshake
|
|
|
|
|
adds an HTTP header to the server handshake.
|
|
|
|
|
|
|
|
|
|
set_subprotocol
|
|
|
|
|
selects a subprotocol for the connection
|
|
|
|
|
selects a subprotocol for the connection.
|
|
|
|
|
|
|
|
|
|
send: text and binary varients
|
|
|
|
|
send a websocket message
|
|
|
|
|
send: text and binary variants
|
|
|
|
|
send a websocket message.
|
|
|
|
|
|
|
|
|
|
ping:
|
|
|
|
|
send a ping
|
|
|
|
|
send a ping.
|
|
|
|
|
|
|
|
|
|
2. Start Asio's event loop with a TCP endpoint and your connection handler
|
|
|
|
|
|
|
|
|
|
There are two example programs in the examples directory that demonstrate this use pattern. One is a trivial stateless echo server, the other is a simple web based chat client. Both include example javascript clients. The echo server is suitable for use with automated testing suites such as the Autobahn test suite.
|
|
|
|
|
There are two example programs in the examples directory that demonstrate this use pattern.
|
|
|
|
|
One is a trivial stateless echo server, the other is a simple web based chat client.
|
|
|
|
|
Both include example javascript clients. The echo server is suitable for use with automated
|
|
|
|
|
testing suites such as the Autobahn test suite.
|
|
|
|
|
|
|
|
|
|
By default, a single connection handler object is used for all connections. If needs require, that default handler can either store per-connection state itself or create new handlers and pass off responsibility for the connection to them.
|
|
|
|
|
By default, a single connection handler object is used for all connections.
|
|
|
|
|
If needs require, that default handler can either store per-connection state itself
|
|
|
|
|
or create new handlers and pass off responsibility for the connection to them.
|
|
|
|
|
|
|
|
|
|
How to build this library
|
|
|
|
|
|
|
|
|
@@ -59,7 +65,7 @@ make
|
|
|
|
|
Build and install in system include directories
|
|
|
|
|
make install
|
|
|
|
|
|
|
|
|
|
Avaliable flags:
|
|
|
|
|
Available flags:
|
|
|
|
|
- SHARED=1: build a shared instead of static library.
|
|
|
|
|
- DEBUG=1: build library with no optimizations, suitable for debugging. Debug library
|
|
|
|
|
is called libwebsocketpp_dbg
|
|
|
|
@@ -89,9 +95,9 @@ To check
|
|
|
|
|
- double check bugs in autobahn (sending wrong localhost:9000 header) not
|
|
|
|
|
- checking masking in the 9.x tests
|
|
|
|
|
|
|
|
|
|
Unimplimented features
|
|
|
|
|
Unimplemented features
|
|
|
|
|
- SSL
|
|
|
|
|
- frame or streaming based api
|
|
|
|
|
- frame or streaming based API
|
|
|
|
|
- client features
|
|
|
|
|
- extension negotiation interface
|
|
|
|
|
|
|
|
|
@@ -117,19 +123,31 @@ websocketpp.hpp
|
|
|
|
|
create a websocketpp::server_ptr initialized to a new websocketpp::server object
|
|
|
|
|
|
|
|
|
|
the server constructor will need three things.
|
|
|
|
|
- A boost::asio::io_service object to use to manage its async operations
|
|
|
|
|
- A boost::asio::io_service object to manage its async operations
|
|
|
|
|
- A boost::asio::ip::tcp::endpoint to listen to for new connections
|
|
|
|
|
- An object that impliments the websocketpp::connection_handler interface to provide callback functions (See Handler API)
|
|
|
|
|
- An object that implements the websocketpp::connection_handler interface to provide callback functions (See Handler API)
|
|
|
|
|
|
|
|
|
|
After construction the server object will be in the initialization state. At this time you can set up server config options either via calling individual set option commands or by loading them in a batch from a config file.
|
|
|
|
|
After construction, the server object will be in the initialization state.
|
|
|
|
|
At this time you can set up server configuration options either via calling individual set option commands
|
|
|
|
|
or by loading them in a batch from a configuration file.
|
|
|
|
|
|
|
|
|
|
The only required option is that at least one host value must be set. Incoming websocket connections must specify a host value that they wish to connect to and if the server object does not have that host value in it's list of canonical hosts it will reject the connection.
|
|
|
|
|
The only required option is that at least one host value must be set.
|
|
|
|
|
Incoming websocket connections must specify a host value that they wish to connect to
|
|
|
|
|
and if the server object does not have that host value in it's list of canonical hosts it will reject the connection.
|
|
|
|
|
|
|
|
|
|
[note about settings that can be changed live?]
|
|
|
|
|
|
|
|
|
|
Once the server has been configured the way you want, call the start_accept() method. This will add the first async call to your io_service. If your io_service was already running, the server will start accepting connections immediately. If not you will need to call io_service.run() to start it.
|
|
|
|
|
Once the server has been configured the way you want, call the start_accept() method.
|
|
|
|
|
This will add the first async call to your io_service. If your io_service was already running,
|
|
|
|
|
the server will start accepting connections immediately. If not you will need to call io_service.run() to start it.
|
|
|
|
|
|
|
|
|
|
Once the server has started it will accept new connections. A new session object will be created for each connection accepted. The session will perform the websocket handshake and if it is successful begin reading frames. The session will continue reading frames until an error occurs or a connection close frame is seen. The session will notify the handler that it was initilized with (see Handler API) as necessary. The Session API defines how a handler (or other part of the end application) can interact with the session (to get information about the session, send messages back to the client, etc)
|
|
|
|
|
Once the server has started it will accept new connections.
|
|
|
|
|
A new session object will be created for each connection accepted.
|
|
|
|
|
The session will perform the websocket handshake and if it is successful begin reading frames.
|
|
|
|
|
The session will continue reading frames until an error occurs or a connection close frame is seen.
|
|
|
|
|
The session will notify the handler that it was initialized with (see Handler API) as necessary.
|
|
|
|
|
The Session API defines how a handler (or other part of the end application) can interact with the session
|
|
|
|
|
(to get information about the session, send messages back to the client, etc).
|
|
|
|
|
|
|
|
|
|
## Client API ##
|
|
|
|
|
include websocketpp.hpp
|
|
|
|
@@ -137,22 +155,30 @@ include websocketpp.hpp
|
|
|
|
|
create a websocketpp::client_ptr initialized to a new websocketpp::client object
|
|
|
|
|
|
|
|
|
|
the client constructor will need:
|
|
|
|
|
- A boost::asio::io_service object to use to manage its async operations
|
|
|
|
|
- An object that impliments the websocketpp::connection_handler interface to privde callback functions (See Handler API)
|
|
|
|
|
- A boost::asio::io_service object to manage its async operations
|
|
|
|
|
- An object that implements the websocketpp::connection_handler interface to provide callback functions (See Handler API)
|
|
|
|
|
|
|
|
|
|
After construction, the client object will be in the initialization state. At this time you can set up client config options either via calling individual set options commands or by loading them in a batch from a config file.
|
|
|
|
|
After construction, the client object will be in the initialization state.
|
|
|
|
|
At this time you can set up client configuration options either via calling individual set options commands
|
|
|
|
|
or by loading them in a batch from a configuration file.
|
|
|
|
|
|
|
|
|
|
Opening a new connection:
|
|
|
|
|
Per the websocket spec, a client can only have one connection in the connecting state at a time. Client method new_session() will create a new session and return a shared pointer to it. After this point new_session will throw an exception if you attempt to call it again before the most recently created session has either successfully connected or failed to connect. new_session()
|
|
|
|
|
Per the websocket spec, a client can only have one connection in the connecting state at a time.
|
|
|
|
|
Client method new_session() will create a new session and return a shared pointer to it.
|
|
|
|
|
After this point new_session will throw an exception if you attempt to call it again
|
|
|
|
|
before the most recently created session has either successfully connected or failed to connect.
|
|
|
|
|
new_session()
|
|
|
|
|
- call websocketpp::client::new_session(). This will return a session_ptr
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Handler API ##
|
|
|
|
|
The handler API defines the interface that a websocketpp session will use to communicate information about the session state and new messages to your application.
|
|
|
|
|
The handler API defines the interface that a websocketpp session will use to communicate information
|
|
|
|
|
about the session state and new messages to your application.
|
|
|
|
|
|
|
|
|
|
A client or server must be initialized with a default handler that will be used for all sessions. The default handler may pass a session off to another handler as necessary.
|
|
|
|
|
A client or server must be initialized with a default handler that will be used for all sessions.
|
|
|
|
|
The default handler may pass a session off to another handler as necessary.
|
|
|
|
|
|
|
|
|
|
A handler must impliment the following methods:
|
|
|
|
|
A handler must implement the following methods:
|
|
|
|
|
- validate(session_ptr)
|
|
|
|
|
- on_fail(session_ptr)
|
|
|
|
|
- on_open(session_ptr)
|
|
|
|
@@ -160,23 +186,43 @@ A handler must impliment the following methods:
|
|
|
|
|
- on_message(session_ptr,const std::vector<unsigned char> &)
|
|
|
|
|
- on_message(session_ptr,const std::string &)
|
|
|
|
|
|
|
|
|
|
validate will be called after a websocket handshake has been received and before it is accepted. It provides a handler the ability to refuse a connection based on application specific logic (ex: restrict domains or negotiate subprotocols). To reject the connection throw a handshake_error. Validate is never called for client sessions. To refuse a client session (ex: if you do not like the set of extensions/subprotocols the server chose) you can close the connection immediately in the on_open member function.
|
|
|
|
|
validate will be called after a websocket handshake has been received and before it is accepted.
|
|
|
|
|
It provides a handler with the ability to refuse a connection based on application specific logic
|
|
|
|
|
(ex: restrict domains or negotiate subprotocols). To reject the connection throw a handshake_error.
|
|
|
|
|
Validate is never called for client sessions.
|
|
|
|
|
To refuse a client session (ex: if you do not like the set of extensions/subprotocols the server chose)
|
|
|
|
|
you can close the connection immediately in the on_open member function.
|
|
|
|
|
|
|
|
|
|
on_fail is called whenever a session is terminated or failed before it was successfully established. This happens if there is an error during the handshake process or if the server refused the connection.
|
|
|
|
|
on_fail will be the last time a session calls its handler. If your application will need information from `session` after this function you should either save the session_ptr somewhere or copy the data out.
|
|
|
|
|
on_fail is called whenever a session is terminated or failed before it was successfully established.
|
|
|
|
|
This happens if there is an error during the handshake process or if the server refused the connection.
|
|
|
|
|
|
|
|
|
|
on_open is called after the websocket session has been successfully established and is in the OPEN state. The session is now avaliable to send messages and will begin reading frames and calling the on_message/on_close/on_error callbacks. A client may reject the connection by closing the session at this point.
|
|
|
|
|
on_fail will be the last time a session calls its handler.
|
|
|
|
|
If your application will need information from `session` after this function you should either
|
|
|
|
|
save the session_ptr somewhere or copy the data out.
|
|
|
|
|
|
|
|
|
|
on_close is called whenever an open session is closed for any reason. This can be due to either endpoint requesting a connection close or an error occuring. Information about why the session was closed can be extracted from the session itself.
|
|
|
|
|
on_close will be the last time a session calls its handler. If your application will need information from `session` after this function you should either save the session_ptr somewhere or copy the data out.
|
|
|
|
|
on_open is called after the websocket session has been successfully established and is in the OPEN state.
|
|
|
|
|
The session is now available to send messages and will begin reading frames
|
|
|
|
|
and calling the on_message/on_close/on_error callbacks.
|
|
|
|
|
A client may reject the connection by closing the session at this point.
|
|
|
|
|
|
|
|
|
|
on_message (binary version) will be called when a binary message is recieved. Message data is passed as a vector of bytes (unsigned char). data will not be avaliable after this callback ends so the handler must either completely process the message or copy it somewhere else for processing later.
|
|
|
|
|
on_close is called whenever an open session is closed for any reason.
|
|
|
|
|
This can be due to either endpoint requesting a connection close or an error occurring.
|
|
|
|
|
Information about why the session was closed can be extracted from the session itself.
|
|
|
|
|
on_close will be the last time a session calls its handler.
|
|
|
|
|
If your application will need information from `session` after this function you should either
|
|
|
|
|
save the session_ptr somewhere or copy the data out.
|
|
|
|
|
|
|
|
|
|
on_message (binary version) will be called when a binary message is received.
|
|
|
|
|
Message data is passed as a vector of bytes (unsigned char).
|
|
|
|
|
Data will not be available after this callback ends so the handler must either
|
|
|
|
|
completely process the message or copy it somewhere else for processing later.
|
|
|
|
|
|
|
|
|
|
TODO: Notes about thread safety
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Session API ##
|
|
|
|
|
The Session API allows a handler to look up information about a session as well as interact with that session (send messages, close the connection, etc)
|
|
|
|
|
The Session API allows a handler to look up information about a session
|
|
|
|
|
as well as interact with that session (send messages, close the connection, etc).
|
|
|
|
|
|
|
|
|
|
Session pointers are returned with every handler callback as well as every call to websocketpp::client::connect.
|
|
|
|
|
|
|
|
|
@@ -185,8 +231,11 @@ Handler Interface:
|
|
|
|
|
- set_handler(connection_handler_ptr)
|
|
|
|
|
|
|
|
|
|
Handshake Interface:
|
|
|
|
|
For the client these methods are valid after the server's handshake has been received. This is guaranteed to be the case by the time `on_open` is called.
|
|
|
|
|
For the server these methods are valid after the client's handshake has been received. This is guaranteed to be the case by the time `validate` is called.
|
|
|
|
|
For the client these methods are valid after the server's handshake has been received.
|
|
|
|
|
This is guaranteed to be the case by the time `on_open` is called.
|
|
|
|
|
|
|
|
|
|
For the server these methods are valid after the client's handshake has been received.
|
|
|
|
|
This is guaranteed to be the case by the time `validate` is called.
|
|
|
|
|
|
|
|
|
|
- const std::string& get_subprotocol() const;
|
|
|
|
|
- const std::string& get_resource() const;
|
|
|
|
@@ -204,7 +253,7 @@ Frame Interface
|
|
|
|
|
|
|
|
|
|
These methods are valid only for open connections. They will throw an exception if called from any other state.
|
|
|
|
|
|
|
|
|
|
WebSocket++ does not queue messages. As such only one send operation can be occuring at once.
|
|
|
|
|
WebSocket++ does not queue messages. As such only one send operation can be occurring at once.
|
|
|
|
|
TODO: failure behavior. OPTIONS:
|
|
|
|
|
- send will throw a `session_busy` exception if busy
|
|
|
|
|
- send will return true/false
|
|
|
|
|
Peter Thorson
Sven Almgren
muhler