forked from zaphoyd/websocketpp
-
Notifications
You must be signed in to change notification settings - Fork 0
/
readme.txt
107 lines (78 loc) · 3.47 KB
/
readme.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
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
Built on Asio's proactor asyncronious 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:
validate:
Called after the client handshake is recieved 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
message: text and binary variants
Called when a new websocket message is recieved.
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
get_request
returns the resource requested by the client in the handshake
set_handler:
pass responsibility for this connection to another connection handler
set_http_error:
reject the connection with a specific HTTP error
add_header
adds an HTTP header to the server handshake
set_subprotocol
selects a subprotocol for the connection
send: text and binary varients
send a websocket message
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.
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
Build static library
make
Build and install in system include directories
make install
Avaliable 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
- CXX=*: uses * as the c++ compiler instead of system default
Build tested on
- Mac OS X 10.7 with apple gcc 4.2, macports gcc 4.6, apple llvm/clang, boost 1.47
- Fedora 15, gcc 4.6, boost 1.46
- Ubunutu server, gcc, boost 1.42
Outstanding issues
- Acknowledgement details
- Subprotocol negotiation interface
- check draft 14 issues
- session.cpp - add_header. Decide what should happen with multiple calls to
add header with the same key
- multiple headers of the same value
- Better exception model
- closing handshake reason/ error codes?
- tests for opening/closing handshake
- tests for utf8
- utf8 streaming validation
- more easily configurable frame size limit
- Better system of handling server wide defaults (like hosts, frame limits, etc)
To check
- double check bugs in autobahn (sending wrong localhost:9000 header) not
- checking masking in the 9.x tests
Unimplimented features
- SSL
- frame or streaming based api
- client features
- extension negotiation interface
Acknowledgements
- Boost Asio and other libraries
- base64 library
- sha1 library
- htonll discussion
- build/makefile from libjson
- Autobahn test suite
- testing by Keith Brisson