You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: advanced-usage.md
+14-14Lines changed: 14 additions & 14 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -52,9 +52,9 @@ double elapsed; // The total time of the request in seconds
52
52
Cookies cookies; // A vector-like collection of cookies returned in the request
53
53
Error error; // An error object containing the error code and a message
54
54
std::string raw_header; // The raw header string
55
-
std::string status_line; // The status line of the respone
55
+
std::string status_line; // The status line of the response
56
56
std::string reason; // The reason for the status code
57
-
cpr_off_t uploaded_bytes; // How many bytes have been send to the server
57
+
cpr_off_t uploaded_bytes; // How many bytes have been sent to the server
58
58
cpr_off_t downloaded_bytes; // How many bytes have been received from the server
59
59
long redirect_count; // How many redirects occurred
60
60
@@ -222,9 +222,9 @@ cpr::Response r = session.Get();
222
222
```
223
223
{% endraw %}
224
224
225
-
This is important so it bears emphasizing: *for each configuration option (like `Url`, `Parameters`), there's a corresponding method `Set<ObjectName>` and a `SetOption(<Object>)`*. The second interface is to facilitate the template metaprogramming magic that lets the API expose order-less methods.
225
+
This is important, so it bears emphasizing: *for each configuration option (like `Url`, `Parameters`), there's a corresponding method `Set<ObjectName>` and a `SetOption(<Object>)`*. The second interface is to facilitate the template metaprogramming magic that lets the API expose order-less methods.
226
226
227
-
The key to all of this is actually the way [libcurl](http://curl.haxx.se/libcurl/) is designed. It uses a somewhat [policy-based design](https://en.wikipedia.org/wiki/Policy-based_design) that relies configuring a single library object (the `curl` handle). Each option configured into that object changes its behavior in mostly orthogonal ways.
227
+
The key to all of this is actually the way [libcurl](http://curl.haxx.se/libcurl/) is designed. It uses a somewhat [policy-based design](https://en.wikipedia.org/wiki/Policy-based_design) that relies on configuring a single library object (the `curl` handle). Each option configured into that object changes its behavior in mostly orthogonal ways.
228
228
229
229
`Session` leverages that and exposes a more modern interface that's free of the macro-heavy hulkiness of libcurl. Understanding the policy-based design of libcurl is important for understanding the way the `Session` object behaves.
Asynchronous requests can also be performed using a `cpr::Session` object. It is important to note that the asynchronous request is performed directly on the session object, modifying it in the process.
426
-
To ensure that the lifetime of the session is properly extended, the session object used **must be** managed by a `std::shared_ptr`. This restriction is necessary because the implementation uses `std::shared_from_this` to pass a pointer to the ansynchronous lambda function which would otherwise throw a `std::bad_weak_ptr` exception.
426
+
To ensure that the lifetime of the session is properly extended, the session object used **must be** managed by a `std::shared_ptr`. This restriction is necessary because the implementation uses `std::shared_from_this` to pass a pointer to the asynchronous lambda function which would otherwise throw a `std::bad_weak_ptr` exception.
427
427
Here is an example for an asynchronous get request which uses a session object:
An important note to make here is that arguments passed to an asynchronous call are copied. Under the hood, an asychronous call through the library's API is done with `std::async`. By default, for memory safety, all arguments are copied (or moved if temporary) because there's no syntax level guarantee that the arguments will live beyond the scope of the request.
440
+
An important note to make here is that arguments passed to an asynchronous call are copied. Under the hood, an asynchronous call through the library's API is done with `std::async`. By default, for memory safety, all arguments are copied (or moved if temporary) because there's no syntax level guarantee that the arguments will live beyond the scope of the request.
441
441
442
442
It's possible to force `std::async` out of this default so that the arguments are passed by reference as opposed to value. Currently, however, `cpr::<method>Async` has no support for forced pass by reference, though this is planned for a future release.
443
443
@@ -508,7 +508,7 @@ Setting the `Timeout` option sets the maximum allowed time the transfer operatio
508
508
509
509
## Setting Callbacks
510
510
511
-
You can optionally set callbacks for a request. Currently there is support for read, header, write, progress, and debug callbacks.
511
+
You can optionally set callbacks for a request. Currently, there is support for read, header, write, progress, and debug callbacks.
This is especially useful because `Cookies` often go from server to client and back to the server. Setting new `Cookies` should not look surprising at all:
696
+
This is especially useful because `Cookies` often go from server to client and back to the server. Setting new `Cookies` should not look surprising at all:
It should be noted that interceptors can make changes to the session object that is later passed to the proceed function and can thus fundamentally change the request. Of course, the returned response object can also be modified.
1291
1291
1292
-
In addition, interceptors can even change the http method of the request by passing the proceed method another parameter of the enum type `cpr::Interceptor::ProceedHttpMethod`. The parameter required for download requests is also simply passed to the proceed method. For example we can implement an interceptor which changes the request method to `HEAD`:
1292
+
In addition, interceptors can even change the http method of the request by passing the proceed method another parameter of the enum type `cpr::Interceptor::ProceedHttpMethod`. The parameter required for download requests is also simply passed to the proceed method. For example, we can implement an interceptor which changes the request method to `HEAD`:
It is also possible to use the ```setResolve``` and ```setResolves``` methods, however, it should be noted that each invocation clears any previous values set before. In other words, do not use multiple consecutive calls to ```setResolve``` to set multiple manual resolutions, instead create a vector of ```cpr::Resolve```-s and pass them to ```setResolves```.
1438
+
It is also possible to use the ```setResolve``` and ```setResolves``` methods, however, it should be noted that each invocation clears any previous values set before. In other words, do not use multiple consecutive calls to ```setResolve``` to set multiple manual resolutions, instead create a vector of ```cpr::Resolve```-s and pass them to ```setResolves```.
0 commit comments