Begin update to migrate manual content into the git repository
The goal here is to get all the documentation in one place including the class reference, text based manual, tutorials, etc.
This commit is contained in:
Peter Thorson committed
1 parent
1e12e7aff8
commit
935c8a3264
6 files changed
+1755
-1019
No files matched your search
@@ -0,0 +1,22 @@
|
||||
/** \page faq FAQ
|
||||
|
||||
## Dependency Management
|
||||
|
||||
### Can WebSocket++ be used without Boost?
|
||||
Yes. WebSocket++ only uses Boost features as polyfills for C++11 language features and libraries. If you have a C++11 compiler and standard library you can use WebSocket++ without Boost. In most cases setting your build environment to use the C++11 (or later) language dialect is sufficient to enable this mode of use.
|
||||
|
||||
With less common compilers (and sometimes very recently release compilers) there may be specific issues with certain libraries that aren't automatically detected by the library. For these situations there are additional defines available to fine tune which C++11 libraries and features are used. TODO: more details about them.
|
||||
|
||||
For the iostream/raw transport the C++11 standard library is sufficient. For the Asio based transports, there is no C++11 library that provides the networking capabilaties that Asio does. As such even with a C++11 build system, you will need a standalone copy of Asio to use if Boost Asio is not available.
|
||||
|
||||
### Can WebSocket++ be used with standalone Asio
|
||||
Yes. The process is the same as used with standalone Asio itself. Define `ASIO_STANDALONE` before including Asio or WebSocket++ headers. You will need to download a copy of the Asio headers separately (http://www.think-async.com) and make sure they are in your build system's include path.
|
||||
|
||||
### Can WebSocket++ be used without TLS or OpenSSL?
|
||||
Yes. When using the iostream/raw transport, there are no TLS features and OpenSSL is not required. When using the Asio transport TLS features are optional. You only need OpenSSL if you want to use TLS. You can only make or recieve encrypted connections (https/wss) if you have enabled TLS features.
|
||||
|
||||
Whether an Asio endpoint uses TLS or not is determined by its config template parameter. The default bundled `websocketpp::config::asio` and `websocketpp::config::asio_client` configs do not support TLS, the `websocketpp::config::asio_tls` and `websocketpp::config::asio_tls_client` do.
|
||||
|
||||
The `<websocketpp/config/asio.hpp>` and `<websocketpp/config/asio_client.hpp>` headers will include both the TLS and non-TLS varients of their respective configs and require the presence of OpenSSL. The `<websocketpp/config/asio_no_tls.hpp>` and `<websocketpp/config/asio_no_tls_client.hpp>` headers will include only the non-TLS configs and do not require OpenSSL.
|
||||
|
||||
*/
|
||||
@@ -0,0 +1,27 @@
|
||||
/** \page getting_started Getting Started
|
||||
|
||||
WebSocket++ code is available on github at https://github.com/zaphoyd/websocketpp
|
||||
The official project homepage lives at http://www.zaphoyd.com/websocketpp
|
||||
|
||||
The git repository is organized into several directories:
|
||||
|
||||
- **docs**: This documentation
|
||||
- **examples**: Example programs that demonstrate how to build basic versions of some commonly used patterns for WebSocket clients and servers.
|
||||
- **test**: Unit tests that confirm that the code you have works properly and help detect platform specific issues.
|
||||
- **tutorials**: Detailed walkthroughs of a select set of the example programs.
|
||||
- **websocketpp**: All of the library code and default configuration files.
|
||||
|
||||
WebSocket++ is a header only library. You can start using it by including the websocketpp source directory in your project's include path and including the appropriate WebSocket++ headers in your program. You may also need to include and/or link to appropriate Boost/system libraries. TODO: More information: Building a program with WebSocket++, Walkthroughs of the example programs
|
||||
|
||||
WebSocket++ includes cmake and scons scripts for building the examples and unit tests. Neither system is needed unless you want to build tests or examples in an automated fashion.
|
||||
|
||||
__Usage questions__ should be posted to the project mailing list at http://groups.google.com/group/websocketpp/ or the IRC channel (\#websocketpp on freenode).
|
||||
|
||||
__Bugs and issues__ should be posted to the project GitHub issues queue: https://github.com/zaphoyd/websocketpp/issues.
|
||||
|
||||
__Pull requests__ on GitHub are welcome. Please make them against the `develop` branch.
|
||||
|
||||
WebSocket++ is written and maintained by Peter Thorson. You can contact me via GitHub messaging, IRC, or via email at websocket@zaphoyd.com.
|
||||
|
||||
*/
|
||||
|
||||
@@ -0,0 +1,165 @@
|
||||
/** \page reference.handlers Handler Reference
|
||||
|
||||
Handlers allow WebSocket++ programs to receive notifications about events
|
||||
that happen in relation to their connections. Some handlers also behave as
|
||||
hooks that give the program a chance to modify state or adjust settings before
|
||||
the connection continues.
|
||||
|
||||
Handlers are registered by calling the appropriate `set_*_handler` method on either an
|
||||
endpoint or connection. The * refers to the name of the handler (as
|
||||
specified in the signature field below). For example, to set the open handler,
|
||||
call `set_open_handler(...)`.
|
||||
|
||||
Setting handlers on an endpoint will result in them being copied as the default
|
||||
handler to all new connections created by that endpoint. Changing an endpoint's
|
||||
handlers will not affect connections that are already in progress. This includes
|
||||
connections that are in the listening state. As such, it is important to set any
|
||||
endpoint handlers before you call `endpoint::start_accept` or else the handlers
|
||||
will not be attached to your first connection.
|
||||
|
||||
Setting handlers on a connection will result in the handler being changed for
|
||||
that connection only, starting at the next time that handler is called. This can
|
||||
be used to change the handler during a connection.
|
||||
|
||||
Connection Handlers
|
||||
-------------------
|
||||
|
||||
These handlers will be called at most once per connection in the order specified below.
|
||||
|
||||
### Socket Init Handler
|
||||
|
||||
| Event | Signature | Availability |
|
||||
| --------------------- | ----------------------------------------------------- | -------------------- |
|
||||
| Socket initialization | `socket_init(connection_hdl, asio::ip::tcp::socket&)` | 0.3.0 Asio Transport |
|
||||
|
||||
This hook is triggered after the socket has been initialized but before a connection is established.
|
||||
It allows setting arbitrary socket options before connections are sent/recieved.
|
||||
|
||||
### TCP Pre-init Handler
|
||||
|
||||
| Event | Signature | Availability |
|
||||
| ----------------------------- | ------------------------------ | -------------------- |
|
||||
| TCP established, no data sent | `tcp_pre_init(connection_hdl)` | 0.3.0 Asio Transport |
|
||||
|
||||
This hook is triggered after the TCP connection is established, but before any pre-WebSocket-handshake
|
||||
operations have been run. Common pre-handshake operations include TLS handshakes and proxy connections.
|
||||
|
||||
### TCP Post-init Handler
|
||||
|
||||
| Event | Signature | Availability |
|
||||
| ----------------------- | ------------------------------------------ | ----------------------------- |
|
||||
| Request for TLS context | `tls_context_ptr tls_init(connection_hdl)` | 0.3.0 Asio Transport with TLS |
|
||||
|
||||
This hook is triggered before the TLS handshake to request the TLS context to use. You must
|
||||
return a pointer to a configured TLS conext to continue. This provides the opportuinity to
|
||||
set up the TLS settings, certificates, etc.
|
||||
|
||||
### Validate Handler
|
||||
|
||||
| Event | Signature | Availability |
|
||||
| ------------------------------------- | ------------------------------- | ---------------------------- |
|
||||
| Hook to accept or reject a connection | `bool validate(connection_hdl)` | 0.3.0 Core, Server role only |
|
||||
|
||||
This hook is triggered for servers during the opening handshake after the request has been
|
||||
processed but before the response has been sent. It gives a program the opportunity to inspect
|
||||
headers and other connection details and either accept or reject the connection. Validate happens
|
||||
before the open or fail handler.
|
||||
|
||||
Return true to accept the connection, false to reject. If no validate handler is registered,
|
||||
all connections will be accepted.
|
||||
|
||||
### Open Connection Handler
|
||||
|
||||
| Event | Signature | Availability |
|
||||
| ------------------------- | ---------------------- | ------------ |
|
||||
| Successful new connection | `open(connection_hdl)` | 0.3.0 Core |
|
||||
|
||||
Either open or fail will be called for each connection. Never both. All
|
||||
connections that begin with an open handler call will also have a matching
|
||||
close handler call when the connection ends.
|
||||
|
||||
### Fail Connection Handler
|
||||
|
||||
| Event | Signature | Availability |
|
||||
| ----------------------------------- | ---------------------- | ------------ |
|
||||
| Connection failed (before opening) | `fail(connection_hdl)` | 0.3.0 Core |
|
||||
|
||||
Either open or fail will be called for each connection. Never both. Connections
|
||||
that fail will never have a close handler called.
|
||||
|
||||
### Close Connection Handler
|
||||
|
||||
| Event | Signature | Availability |
|
||||
| --------------------------------- | ----------------------- | ------------ |
|
||||
| Connection closed (after opening) | `close(connection_hdl)` | 0.3.0 Core |
|
||||
|
||||
Close will be called exactly once for every connection that open was called for.
|
||||
Close is not called for failed connections.
|
||||
|
||||
Message Handlers
|
||||
----------------
|
||||
|
||||
These handers are called in response to incoming messages or message like events. They only will be called while the connection is in the open state.
|
||||
|
||||
### Message Handler
|
||||
|
||||
| Event | Signature | Availability |
|
||||
| --------------------- | -------------------------------------- | ------------ |
|
||||
| Data message recieved | `message(connection_hdl, message_ptr)` | 0.3.0 Core |
|
||||
|
||||
Applies to all non-control messages, including both text and binary opcodes. The
|
||||
`message_ptr` type and its API depends on your endpoint type and its config.
|
||||
|
||||
### Ping Handler
|
||||
|
||||
| Event | Signature | Availability |
|
||||
| ------------- | ---------------------------------------- | ------------ |
|
||||
| Ping recieved | `bool ping(connection_hdl, std::string)` | 0.3.0 Core |
|
||||
|
||||
Second (string) argument is the binary ping payload. Handler return value
|
||||
indicates whether or not to respond to the ping with a pong. If no ping handler
|
||||
is set, WebSocket++ will respond with a pong containing the same binary data as
|
||||
the ping (Per requirements in RFC6455).
|
||||
|
||||
### Pong Handler
|
||||
|
||||
| Event | Signature | Availability |
|
||||
| ------------- | ----------------------------------- | ------------ |
|
||||
| Pong recieved | `pong(connection_hdl, std::string)` | 0.3.0 Core |
|
||||
|
||||
Second (string) argument is the binary pong payload.
|
||||
|
||||
### Pong Timeout Handler
|
||||
|
||||
| Event | Signature | Availability |
|
||||
| ---------------------------------- | ------------------------------------------- | ---------------------------------------- |
|
||||
| Timed out while waiting for a pong | `pong_timeout(connection_hdl, std::string)` | 0.3.0 Core, transport with timer support |
|
||||
|
||||
Triggered if there is no response to a ping after the configured duration. The second
|
||||
(string) argument is the binary payload of the unanswered ping.
|
||||
|
||||
### HTTP Handler
|
||||
|
||||
| Event | Signature | Availability |
|
||||
| --------------------- | --------------------- | ---------------------------- |
|
||||
| HTTP request recieved | `http(connection_hdl` | 0.3.0 Core, Server role only |
|
||||
|
||||
Called when HTTP requests that are not WebSocket handshake upgrade requests are
|
||||
recieved. Allows responding to regular HTTP requests. If no handler is registered
|
||||
a 426/Upgrade Required error is returned.
|
||||
|
||||
### Interrupt Handler
|
||||
|
||||
| Event | Signature | Availability |
|
||||
| ----------------------------------- | --------------------------- | ------------ |
|
||||
| Connection was manually interrupted | `interrupt(connection_hdl)` | 0.3.0 Core |
|
||||
|
||||
Interrupt events can be triggered by calling `endpoint::interrupt` or `connection::interrupt`.
|
||||
Interrupt is similar to a timer event with duration zero but with lower overhead. It is useful
|
||||
for single threaded programs to allow breaking up a very long handler into multiple parts and
|
||||
for multi threaded programs as a way for worker threads to signale to the main/network thread
|
||||
that an event is ready.
|
||||
|
||||
todo: write low and high watermark handlers
|
||||
|
||||
*/
|
||||
@@ -0,0 +1,22 @@
|
||||
.tabs, .tabs2, .tabs3, .navpath ul {
|
||||
background-image: none;
|
||||
background-color: #333;
|
||||
border: none;
|
||||
border-bottom: 1px solid #575757;
|
||||
}
|
||||
|
||||
.tablist li, .navpath li {
|
||||
background-image: none;
|
||||
background-color: #333;
|
||||
}
|
||||
|
||||
.tablist a, .navpath li.navelem a {
|
||||
color: #ccc;
|
||||
text-shadow: 0px 1px 1px black;
|
||||
}
|
||||
|
||||
.tablist a:hover, .navpath li.navelem a:hover {
|
||||
background-image: none;
|
||||
background-color: #444;
|
||||
color: #ccc;
|
||||
}
|
||||
@@ -0,0 +1,18 @@
|
||||
/** \mainpage
|
||||
|
||||
WebSocket++ is a C++ library that can be used to implement WebSocket functionality. The goals of the project are to provide a WebSocket implementation that is portable, flexible, lightweight, low level, and high performance.
|
||||
|
||||
WebSocket++ does not intend to be used alone as a web application framework or full featured web services platform. As such the components, examples, and performance tuning are geared towards operation as a WebSocket client or server. There are some minimal convenience features that stray from this (for example the ability to respond to HTTP requests other than WebSocket Upgrades) but these are not the focus of the project. In particular WebSocket++ does not intend to implement any non-WebSocket related fallback options (ajax / long polling / comet / etc).
|
||||
|
||||
In order to remain compact and improve portability, the WebSocket++ project strives to reduce or eliminate external dependencies where possible and appropriate. WebSocket++ core has no dependencies other than the C++11 STL. For non-C++11 compilers the Boost libraries provide drop in polyfills for the C++11 functionality used.
|
||||
|
||||
WebSocket++ implements a pluggable data transport component. The default component allows reduced functionality by using STL iostream or raw byte shuffling via reading and writing char buffers. This component has no non-STL dependencies and can be used in a C++11 environment without Boost. Also included is an Asio based transport component that provides full featured network client/server functionality. This component requires either Boost Asio or a C++11 compiler and standalone Asio. As an advanced option, WebSocket++ supports custom transport layers if you want to provide your own using another library.
|
||||
|
||||
In order to accommodate the wide variety of use cases WebSocket++ has collected, the library is built in a way that most of the major components are loosely coupled and can be swapped out and replaced. WebSocket++ will attempt to track the future development of the WebSocket protocol and any extensions as they are developed.
|
||||
|
||||
- \subpage getting_started "Getting Started"
|
||||
- \subpage faq "FAQ"
|
||||
- \subpage reference.handlers "Handler Reference"
|
||||
|
||||
*/
|
||||
|
||||
Reference in new issue
Block a user