Lightweight C++ HTTP client and server library based on [Boost Asio](https://www.boost.org/doc/libs/release/libs/asio/).
Lightweight C++ HTTP client and server library based on [Boost Asio](https://www.boost.org/doc/libs/release/libs/asio/).
Please turn to our [Wiki](https://github.com/sprinfall/webcc/wiki) (under construction) for more tutorials and guides.
Please turn to our [Wiki](https://github.com/sprinfall/webcc/wiki) for more tutorials and guides.
Wondering how to build Webcc? Check [Build Instructions](https://github.com/sprinfall/webcc/wiki/Build-Instructions).
Wondering how to build Webcc? Check [Build Instructions](https://github.com/sprinfall/webcc/wiki/Build-Instructions).
@ -12,7 +12,7 @@ Git repo: https://github.com/sprinfall/webcc. Please check this one instead of t
**Features**
**Features**
- Cross-platform: Linux, Windows and Mac
- Cross-platform: Windows, Linux and MacOS
- Easy-to-use client API inspired by Python [requests](https://2.python-requests.org//en/master/)
- Easy-to-use client API inspired by Python [requests](https://2.python-requests.org//en/master/)
- SSL/HTTPS support with OpenSSL (optional)
- SSL/HTTPS support with OpenSSL (optional)
- GZip compression support with Zlib (optional)
- GZip compression support with Zlib (optional)
@ -25,7 +25,6 @@ Git repo: https://github.com/sprinfall/webcc. Please check this one instead of t
- Source code follows [Google C++ Style](https://google.github.io/styleguide/cppguide.html)
- Source code follows [Google C++ Style](https://google.github.io/styleguide/cppguide.html)
- Automation tests and unit tests included
- Automation tests and unit tests included
- No memory leak detected by [VLD](https://kinddragon.github.io/vld/)
- No memory leak detected by [VLD](https://kinddragon.github.io/vld/)
- etc.
## Client API
## Client API
@ -48,7 +47,9 @@ int main() {
// Catch exceptions for error handling.
// Catch exceptions for error handling.
try {
try {
// Send a HTTP GET request.
// Send a HTTP GET request.
auto r = session.Get("http://httpbin.org/get");
auto r = session.Send(webcc::RequestBuilder{}.
Get("http://httpbin.org/get")
());
// Print the response data.
// Print the response data.
std::cout <<r->data() <<std::endl;
std::cout <<r->data() <<std::endl;
@ -61,46 +62,30 @@ int main() {
}
}
```
```
The `Get()` method is nothing but a shortcut of `Request()`. Using `Request()` directly is more complicated:
```cpp
auto r = session.Request(webcc::RequestBuilder{}.Get("http://httpbin.org/get")());
```
As you can see, a helper class named `RequestBuilder` is used to chain the parameters and finally build a request object. Please pay attention to the `()` operator.
As you can see, a helper class named `RequestBuilder` is used to chain the parameters and finally build a request object. Please pay attention to the `()` operator.
Both the shortcut and `Request()` accept URL query parameters:
URL query parameters can be easily added through `Query()` method:
```cpp
```cpp
// Query parameters are passed using a std::vector.
auto r = session.Get("https://api.github.com/events");
auto r = session.Send(webcc::RequestBuilder{}.
Get("https://api.github.com/events")
());
```
```
You can then parse `r->data()` to JSON object with your favorite JSON library. My choice for the examples is [jsoncpp](https://github.com/open-source-parsers/jsoncpp). But Webcc itself doesn't understand JSON nor require one. It's up to you to choose the most appropriate JSON library.
You can then parse `r->data()` to JSON object with your favorite JSON library. My choice for the examples is [jsoncpp](https://github.com/open-source-parsers/jsoncpp). But Webcc itself doesn't understand JSON nor require one. It's up to you to choose the most appropriate JSON library.
The shortcuts (`Get()`, `Post()`, etc.) are easier to use but `RequestBuilder` is more powerful. It provides a lot of functions for you to customize the request. Let's see more examples.
`RequestBuilder` provides a lot of functions for you to customize the request. Let's see more examples.
In order to list the followers of an authorized GitHub user, you need either **Basic Authorization**:
In order to list the followers of an authorized GitHub user, you need either **Basic Authorization**:
```cpp
```cpp
session.Request(webcc::RequestBuilder{}.
session.Send(webcc::RequestBuilder{}.
Get("https://api.github.com/user/followers").
Get("https://api.github.com/user/followers").
AuthBasic(login, password) // Should be replaced by real login and password
AuthBasic(login, password) // Should be replaced by valid login and passwords
());
());
```
```
Or **Token Authorization**:
Or **Token Authorization**:
```cpp
```cpp
session.Request(webcc::RequestBuilder{}.
session.Send(webcc::RequestBuilder{}.
Get("https://api.github.com/user/followers").
Get("https://api.github.com/user/followers").
AuthToken(token) // Should be replaced by a valid token
AuthToken(token) // Should be replaced by a valid token
());
());
```
```
Though **Keep-Alive** (i.e., persistent connection) is a good feature and enabled by default, you can turn it off:
Though **Keep-Alive** (i.e., persistent connection) is a good feature and enabled by default, you can turn it off:
```cpp
```cpp
auto r = session.Request(webcc::RequestBuilder{}.
auto r = session.Send(webcc::RequestBuilder{}.
Get("http://httpbin.org/get").
Get("http://httpbin.org/get").
KeepAlive(false) // No Keep-Alive
KeepAlive(false) // No Keep-Alive
());
());
```
```
The API for other HTTP requests is no different from GET.
The API for other HTTP requests is no different from GET.
@ -147,24 +134,36 @@ The API for other HTTP requests is no different from GET.
POST request needs a body which is normally a JSON string for REST API. Let's post a small UTF-8 encoded JSON string:
POST request needs a body which is normally a JSON string for REST API. Let's post a small UTF-8 encoded JSON string:
```cpp
```cpp
session.Request(webcc::RequestBuilder{}.
session.Send(webcc::RequestBuilder{}.
Post("http://httpbin.org/post").
Post("http://httpbin.org/post").
Body("{'name'='Adam', 'age'=20}").
Body("{'name'='Adam', 'age'=20}").Json().Utf8()
Json().Utf8()
());
());
```
```
Webcc has the ability to stream large response data to a file. This is especially useful when downloading files.
Webcc has the ability to stream large response data to a file. This is especially useful when downloading files.
```cpp
```cpp
auto r = session.Request(webcc::RequestBuilder{}.
auto r = session.Send(webcc::RequestBuilder{}.
Get("http://httpbin.org/image/jpeg")(),
Get("http://httpbin.org/image/jpeg")
true); // !!!
(), true); // stream = true
// Move the streamed file to your destination.
// Move the streamed file to your destination.
r->file_body()->Move("./wolf.jpeg");
r->file_body()->Move("./wolf.jpeg");
```
```
Streaming is also available for uploading:
```cpp
auto r = session.Send(webcc::RequestBuilder{}.
Post("http://httpbin.org/post").
File(path) // Should be replaced by a valid file path
());
```
The file will not be loaded into the memory all at once, instead, it will be read and sent piece by piece.
Please note that `Content-Length` header will still be set to the true size of the file, this is different from the handling of chunked data (`Transfer-Encoding: chunked`).
Please check the [examples](https://github.com/sprinfall/webcc/tree/master/examples/) for more information.
Please check the [examples](https://github.com/sprinfall/webcc/tree/master/examples/) for more information.
Chunting Gu
6 years ago