Add TOC
This commit is contained in:
@@ -8,7 +8,23 @@ Please turn to [doc](doc/) for more tutorials and guides. E.g., [Build Instructi
|
|||||||
|
|
||||||
Git repo: https://github.com/sprinfall/webcc. Please check this one instead of the forked for the latest features.
|
Git repo: https://github.com/sprinfall/webcc. Please check this one instead of the forked for the latest features.
|
||||||
|
|
||||||
**Features**
|
**Contents**
|
||||||
|
* [Overview](#overview)
|
||||||
|
* [Client API](#client-api)
|
||||||
|
* [A Complete Example](#a-complete-example)
|
||||||
|
* [Request Builder](#request-builder)
|
||||||
|
* [HTTPS](#request-builder)
|
||||||
|
* [Invoke GitHub REST API](#invoke-github-rest-api)
|
||||||
|
* [Authorization](#authorization)
|
||||||
|
* [Keep-Alive](#keep-alive)
|
||||||
|
* [POST Request](#post-request)
|
||||||
|
* [Download Files](#download-files)
|
||||||
|
* [Upload Files](#upload-files)
|
||||||
|
* [Server API](#server-api)
|
||||||
|
* [Hello World](#hello-world)
|
||||||
|
* [REST Book Server](#rest-book-server)
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
- Cross-platform: Windows, Linux and MacOS
|
- 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/)
|
||||||
@@ -26,6 +42,8 @@ Git repo: https://github.com/sprinfall/webcc. Please check this one instead of t
|
|||||||
|
|
||||||
## Client API
|
## Client API
|
||||||
|
|
||||||
|
### A Complete Example
|
||||||
|
|
||||||
Let's start from a complete client example:
|
Let's start from a complete client example:
|
||||||
|
|
||||||
```cpp
|
```cpp
|
||||||
@@ -60,6 +78,8 @@ int main() {
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
### Request Builder
|
||||||
|
|
||||||
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.
|
||||||
|
|
||||||
URL query parameters can be easily added through `Query()` method:
|
URL query parameters can be easily added through `Query()` method:
|
||||||
@@ -80,6 +100,8 @@ session.Send(webcc::RequestBuilder{}.
|
|||||||
());
|
());
|
||||||
```
|
```
|
||||||
|
|
||||||
|
### HTTPS
|
||||||
|
|
||||||
Accessing HTTPS has no difference from HTTP:
|
Accessing HTTPS has no difference from HTTP:
|
||||||
|
|
||||||
```cpp
|
```cpp
|
||||||
@@ -88,6 +110,8 @@ session.Send(webcc::RequestBuilder{}.Get("https://httpbin.org/get")());
|
|||||||
|
|
||||||
*NOTE: The HTTPS/SSL support requires the build option `WEBCC_ENABLE_SSL` to be enabled.*
|
*NOTE: The HTTPS/SSL support requires the build option `WEBCC_ENABLE_SSL` to be enabled.*
|
||||||
|
|
||||||
|
### Invoke GitHub REST API
|
||||||
|
|
||||||
Listing GitHub public events is not a big deal:
|
Listing GitHub public events is not a big deal:
|
||||||
|
|
||||||
```cpp
|
```cpp
|
||||||
@@ -100,6 +124,8 @@ You can then parse `r->data()` to JSON object with your favorite JSON library. M
|
|||||||
|
|
||||||
`RequestBuilder` 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.
|
||||||
|
|
||||||
|
### Authorization
|
||||||
|
|
||||||
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
|
||||||
@@ -118,6 +144,8 @@ session.Send(webcc::RequestBuilder{}.
|
|||||||
());
|
());
|
||||||
```
|
```
|
||||||
|
|
||||||
|
### Keep-Alive
|
||||||
|
|
||||||
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
|
||||||
@@ -129,6 +157,8 @@ auto r = session.Send(webcc::RequestBuilder{}.
|
|||||||
|
|
||||||
The API for other HTTP requests is no different from GET.
|
The API for other HTTP requests is no different from GET.
|
||||||
|
|
||||||
|
### POST Request
|
||||||
|
|
||||||
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
|
||||||
@@ -138,6 +168,8 @@ session.Send(webcc::RequestBuilder{}.
|
|||||||
());
|
());
|
||||||
```
|
```
|
||||||
|
|
||||||
|
### Download Files
|
||||||
|
|
||||||
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
|
||||||
@@ -149,6 +181,8 @@ auto r = session.Send(webcc::RequestBuilder{}.
|
|||||||
r->file_body()->Move("./wolf.jpeg");
|
r->file_body()->Move("./wolf.jpeg");
|
||||||
```
|
```
|
||||||
|
|
||||||
|
### Upload Files
|
||||||
|
|
||||||
Streaming is also available for uploading:
|
Streaming is also available for uploading:
|
||||||
|
|
||||||
```cpp
|
```cpp
|
||||||
@@ -162,11 +196,13 @@ The file will not be loaded into the memory all at once, instead, it will be rea
|
|||||||
|
|
||||||
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 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](examples/) for more information.
|
Please check the [examples](examples/) for more information.
|
||||||
|
|
||||||
## Server API
|
## Server API
|
||||||
|
|
||||||
### Hello, World!
|
### Hello World
|
||||||
|
|
||||||
|
Run the following example, open your browser with `localhost:8080`, you should see "Hello, World!".
|
||||||
|
|
||||||
```cpp
|
```cpp
|
||||||
class HelloView : public webcc::View {
|
class HelloView : public webcc::View {
|
||||||
@@ -196,7 +232,7 @@ int main() {
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### Book Server
|
### REST Book Server
|
||||||
|
|
||||||
Suppose you want to create a book server and provide the following operations with RESTful API:
|
Suppose you want to create a book server and provide the following operations with RESTful API:
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user