diff --git a/README.md b/README.md index acc006a..1bfcb8d 100644 --- a/README.md +++ b/README.md @@ -1,98 +1,90 @@ easywsclient ============ -Easywsclient is a single-file, header-only WebSocket -client for C++. It depends only on the standard libraries. -Can make optional use of C++11 features (i.e. std::function and -[lambda](http://en.wikipedia.org/wiki/Anonymous_function#C.2B.2B)). -Supported is [RFC 6455](http://tools.ietf.org/html/rfc6455) Version -13 WebSocket. +Easywsclient is an easy and powerful WebSocket client to C++ get +your code connected to a web stack right away. It depends only on +the standard libraries. It makes use of C++11 std::function and +[lambda](http://en.wikipedia.org/wiki/Anonymous_function#C.2B.2B), +if they're available (it's not required though). [RFC +6455](http://tools.ietf.org/html/rfc6455) Version 13 WebSocket is +supported this version is compatible with all major, modern WebSocket +implementations, including Node.js. Rationale: This library is intended to help a C++ project start using -WebSocket rapidly. It does not require your project to derive from any -spooky/mystical interfaces (at most, it may need a functor, but that's -pretty conventional). It does not require you to be using this-or-that -particular asynchronous library. It only requires your OS to support -sockets! +WebSocket rapidly. This small library can easily be thrown into an +existing project. For complicated builds that you can't figure out right +away, you can even cheat by piggy-backing the .cpp file into one of the +project's existing files. Yes, WebSocket is awesome enough to warrant +getting it integrated into your project! This project imposes no special +interface requirements, and can work happily with new C++11 features or +with older C++ projects. -More rationale: So, you were handed a project that needs a WebSocket. -You must do a demo right away. You don't have time to figure out how the -project's magic asynchronous event processing works (or worse, it doesn't -have any consistency). So what do you do? Panic? No. Use this library. - -However! This is probably not the end-point for your project, -as this library puts a lot of crap into the header file -(easier to use, but reduces the benefits of [separate -compilation](http://en.wikipedia.org/wiki/Single_Compilation_Unit)). -Also, this library does not work in cooperation with any asynchronous -event processing scheduler. The good news is that the code here is -straightforward and can serve as a reference to build something tailored -for your needs, in the spirt of copy-and-paste (and you are very welcome -to do so). - -Happy hacking! Drop me a line if you do anything cool with this :) -...complaints welcome too. +As an additional benefit, easywsclient is very simple, with just a single +implementation file and can serve as a cruft-free concise reference. You +are most welcome to use this code as a reference for creating alternative +implementations that may better suit your needs. Usage ===== -The interface looks somewhat like this: +The WebSocket class interface looks like this: - // Factory method to create a WebSocket: - static pointer from_url(std::string url); - // Factory method to create a dummy WebSocket (all operations are noop): - static pointer create_dummy(); +```c++ +// Factory method to create a WebSocket: +static pointer from_url(std::string url); +// Factory method to create a dummy WebSocket (all operations are noop): +static pointer create_dummy(); - // Function to perform actual network send()/recv() I/O: - void poll(); +// Function to perform actual network send()/recv() I/O: +void poll(); - // Receive a message, and pass it to callable(). Really, this just looks at - // a buffer (filled up by poll()) and decodes any messages in the buffer. - // Callable must have signature: void(const std::string & message). - // Should work with C functions, C++ functors, and C++11 std::function and - // lambda: - template - void dispatch(Callable callable); +// Receive a message, and pass it to callable(). Really, this just looks at +// a buffer (filled up by poll()) and decodes any messages in the buffer. +// Callable must have signature: void(const std::string & message). +// Should work with C functions, C++ functors, and C++11 std::function and +// lambda: +template +void dispatch(Callable callable); - // Sends a TEXT type message (gets put into a buffer for poll() to send - // later): - void send(std::string message); +// Sends a TEXT type message (gets put into a buffer for poll() to send +// later): +void send(std::string message); +``` -Put altogether, this will look something like this: +Put together, the usage looks like this: - // This #define must occur in _exactly one_ of your .cpp files, before - // #including the header. (This will put private implementation details in - // just that one file.): - #define EASYWSCLIENT_COMPILATION_UNIT // <-- must be put in exactly one .cpp file - #include "easywsclient.hpp" +```c++ +#include "easywsclient.hpp" +#include "easywsclient.cpp" // <-- include only if you don't want compile separately - int - main() - { - ... - using easywsclient::WebSocket; - WebSocket::pointer ws = WebSocket::from_url("ws://localhost:8126/foo"); - assert(ws); - while (true) { - ws->poll(); - ws->send("hello"); - ws->dispatch(handle_message); - // ...do more stuff... - } - ... +int +main() +{ + ... + using easywsclient::WebSocket; + WebSocket::pointer ws = WebSocket::from_url("ws://localhost:8126/foo"); + assert(ws); + while (true) { + ws->poll(); + ws->send("hello"); + ws->dispatch(handle_message); + // ...do more stuff... } + ... +} +``` Example ======= - # Launch the server + # Launch a test server: node example-server.js - # Build and launch the client + # Build and launch the client: g++ example-client.cpp -o example-client ./example-client - # Optional: build and launch a C++11 client + # ...or build and launch a C++11 client: g++ -std=gnu++0x example-client-cpp11.cpp -o example-client-cpp11 ./example-client-cpp11