Merge branch 'master' of https://github.com/sprinfall/webcc

README.md

@@ -1,16 +1,10 @@
 # webcc
 
-C++ client and server library for HTTP, REST and SOAP based on *Boost.Asio*.
+C++ client and server library for HTTP and REST based on *Boost Asio*.
 
-Please turn to our [Wiki](https://github.com/sprinfall/webcc/wiki) for more tutorials and guides, or just follow the links below:
+Please turn to our [Wiki](https://github.com/sprinfall/webcc/wiki) (under construction) for more tutorials and guides.
 
-- [Integrate Into Your Project](https://github.com/sprinfall/webcc/wiki/Integrate-Into-Your-Project)
+## Client API Examples
-- [Logging](https://github.com/sprinfall/webcc/wiki/Logging)
-- [SOAP Client Tutorial](https://github.com/sprinfall/webcc/wiki/SOAP-Client-Tutorial)
-- [SOAP Server Tutorial](https://github.com/sprinfall/webcc/wiki/SOAP-Server-Tutorial)
-- [REST Server Tutorial](https://github.com/sprinfall/webcc/wiki/REST-Server-Tutorial)
-
-## Quickstart
 
 A complete client example: 
 ```cpp
@@ -20,13 +14,19 @@ A complete client example:
 #include "webcc/logger.h"
 
 int main() {
+  // Configure logger.
   WEBCC_LOG_INIT("", webcc::LOG_CONSOLE);
+  
+  // Session provides convenient request APIs, stores request configurations
+  // and manages persistent connenction.
+  webcc::HttpClientSession session;
 
+  // Catch exceptions for error handling.
   try {
-    webcc::HttpClientSession session;
+    // Send a HTTP GET request.
-
     auto r = session.Get("http://httpbin.org/get");
 
+    // Print the response content data.
     std::cout << r->content() << std::endl;
 
   } catch (const webcc::Exception& e) {
@@ -37,14 +37,52 @@ int main() {
 }
 ```
 
-List GitHub public events:
+The `Get()` method is nothing but a shortcut of `Request()`. Using `Request()` directly is more complicated:
 ```cpp
-  auto r = session.Get("https://api.github.com/events");
+auto r = session.Request(webcc::HttpRequestBuilder{}.Get().
+                         Url("http://httpbin.org/get")
+                         ());
+```
+As you can see, a helper class named `HttpRequestBuilder` is used to chain the parameters and finally build (don't miss the `()` operator) a request object.
+
+Both the shortcut and `Request()` accept URL query parameters:
 
-  // Parse r->content() to JSON object...
+```cpp
+// Query parameters are passed using a std::vector. 
+session.Get("http://httpbin.org/get", { "key1", "value1", "key2", "value2" });
+
+session.Request(webcc::HttpRequestBuilder{}.Get().
+                Url("http://httpbin.org/get").
+                Query("key1", "value1").
+                Query("key2", "value2")
+                ());
 ```
 
-For more examples, see the Wiki tutorials.
+Adding additional headers is also easy:
+```cpp
+session.Get("http://httpbin.org/get",
+            {"key1", "value1", "key2", "value2"},
+            {"Accept", "application/json"});  // Also a std::vector
+                
+session.Request(webcc::HttpRequestBuilder{}.Get().
+                Url("http://httpbin.org/get").
+                Query("key1", "value1").
+                Query("key2", "value2").
+                Header("Accept", "application/json")
+                ());
+```
+
+Accessing HTTPS has no difference from HTTP:
+```cpp
+session.Get("https://httpbin.org/get");
+```
+*NOTE: The HTTPS/SSL support requires the build option `WEBCC_ENABLE_SSL` to be enabled.*
+
+Listing GitHub public events is not a big deal:
+```cpp
+auto r = session.Get("https://api.github.com/events");
+```
+You can then parse `r->content()` to JSON object with your favorite JSON library. My choice for the examples is [jsoncpp](https://github.com/open-source-parsers/jsoncpp). But the library itself doesn't understand JSON nor require one. It's up to you to choose the most appropriate JSON library.
 
 ## Build Instructions
 
@@ -52,34 +90,38 @@ For more examples, see the Wiki tutorials.
 
 A lot of C++11 features are used, e.g., `std::move`.
 
-VS2015 and above is required for building `webcc` on Windows. No support for VS2013 any more!
+VS2013 and above is required for building `webcc` on Windows.
 
 [CMake 3.1.0+](https://cmake.org/) is used as the build system. But if you don't use CMake, you can just copy the `src/webcc` folder to your own project then manage it by yourself, though some changes are needed to make it work. See [Wiki/Integrate Into Your Project]( https://github.com/sprinfall/webcc/wiki/Integrate-Into-Your-Project) for more details.
 
 [C++ Boost](https://www.boost.org/) should be 1.66+ because Asio made some broken changes to the API since 1.66.
 
-OpenSSL is required for HTTPS support. Already included in the `third_party` folder for Windows.
+OpenSSL is required for HTTPS support. See `WEBCC_ENABLE_SSL` option.
 
-Zlib is required for compressing and decompressing HTTP requests and responses.
+Zlib is required for compressing and decompressing HTTP requests and responses. Already included in the `third_party` folder for Windows.
 
 ### Build Options
 
 The following CMake options determine how you build the projects. They are quite self-explanatory.
 
 ```cmake
-option(WEBCC_ENABLE_SOAP "Enable SOAP support (need pugixml)?" ON)
+option(WEBCC_ENABLE_TEST "Build test?" ON)
 option(WEBCC_ENABLE_UNITTEST "Build unit test?" ON)
 option(WEBCC_ENABLE_EXAMPLES "Build examples?" ON)
 
-set(WEBCC_ENABLE_LOG 1 CACHE STRING "Enable logging? (0:OFF, 1:ON)")
+set(WEBCC_ENABLE_LOG 1 CACHE STRING "Enable logging? (1:Yes, 0:No)")
 set(WEBCC_LOG_LEVEL 2 CACHE STRING "Log level (0:VERB, 1:INFO, 2:WARN, 3:ERRO or 4:FATA)")
+
+set(WEBCC_ENABLE_SSL 0 CACHE STRING "Enable SSL/HTTPS (need OpenSSL)? (1:Yes, 0:No)")
 ```
 
+Option `WEBCC_ENABLE_TEST` enables/disables the automation test based on real servers (mostly [httpbin.org](http://httpbin.org/)).
+
 Options `WEBCC_ENABLE_LOG` and `WEBCC_LOG_LEVEL` together define how logging behaves. See [Wiki/Logging](https://github.com/sprinfall/webcc/wiki/Logging) for more details.
 
-If `WEBCC_ENABLE_SOAP` is `1`, **pugixml** (already included) is used to parse and compose XML strings.
+You should install OpenSSL development files before try to enable `WEBCC_ENABLE_SSL`.
 
-### Build On Linux
+### Build on Linux
 
 Create a build folder under the root (or any other) directory, and `cd` to it:
 ```bash
@@ -92,8 +134,9 @@ cmake -G"Unix Makefiles" \
     -DCMAKE_INSTALL_PREFIX=~ \
     -DWEBCC_ENABLE_LOG=1 \
     -DWEBCC_LOG_LEVEL=2 \
-    -DWEBCC_ENABLE_SOAP=ON \
+    -DWEBCC_ENABLE_SSL=ON \
-    -DWEBCC_ENABLE_UNITTEST=OFF \
+    -DWEBCC_ENABLE_TEST=ON \
+    -DWEBCC_ENABLE_UNITTEST=ON \
     -DWEBCC_ENABLE_EXAMPLES=ON \
     ..
 ```