From e434dc9fc8a4cffe987048fc39508993558c3d2b Mon Sep 17 00:00:00 2001 From: Chunting Gu Date: Tue, 16 Apr 2019 14:27:59 +0800 Subject: [PATCH] Add more examples; remove SOAP. --- README.md | 89 ++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 65 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index 06fae3a..4240a69 100644 --- a/README.md +++ b/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) -- [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 +## Client API Examples 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.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: + +```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") + ()); +``` + +Adding additional headers is also easy: ```cpp - auto r = session.Get("https://api.github.com/events"); +r = 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") + ()); +``` - // Parse r->content() to JSON object... +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.* -For more examples, see the Wiki tutorials. +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,36 @@ 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)") ``` 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 +132,9 @@ cmake -G"Unix Makefiles" \ -DCMAKE_INSTALL_PREFIX=~ \ -DWEBCC_ENABLE_LOG=1 \ -DWEBCC_LOG_LEVEL=2 \ - -DWEBCC_ENABLE_SOAP=ON \ - -DWEBCC_ENABLE_UNITTEST=OFF \ + -DWEBCC_ENABLE_SSL=ON \ + -DWEBCC_ENABLE_UNITTEST=ON \ + -DWEBCC_ENABLE_UNITTEST=ON \ -DWEBCC_ENABLE_EXAMPLES=ON \ .. ```