Revision 24:6c1651fd26b9, committed 2018-01-11

Comitter:

Jan Jongboom

Date:

Thu Jan 11 13:57:53 2018 +0100

Parent:

23:15fa2726f793

Child:

25:47d5c90c9ceb

Child:

27:42b319540a74

Commit message:

Add chunked requests to readme

Changed in this revision

--- a/README.md	Thu Jan 11 13:49:06 2018 +0100
+++ b/README.md	Thu Jan 11 13:57:53 2018 +0100
@@ -52,7 +52,7 @@
 
 This means that you cannot use HTTPS on devices with less than 128K of memory, as you also need to reserve memory for the stack and network interface.
 
-### Dealing with large body
+### Dealing with large response body
 
 By default the library will store the full request body on the heap. This works well for small responses, but you'll run out of memory when receiving a large response body. To mitigate this you can pass in a callback as the last argument to the request constructor. This callback will be called whenever a chunk of the body is received. You can set the request chunk size in the `HTTP_RECEIVE_BUFFER_SIZE` macro (see `mbed_lib.json` for the definition) although it also depends on the buffer size of the underlying network connection.
 
@@ -65,6 +65,22 @@
 req->send(NULL, 0);
 ```
 
+### Dealing with a large request body
+
+If you cannot load the full request into memory, you can pass a callback into the `send` function. Through this callback you can feed in chunks of the request body. This is very useful if you want to send files from a file system.
+
+```cpp
+const void * get_chunk(size_t* out_size) {
+    // set the value of out_size (via *out_size = 10) to the size of the buffer
+    // return the buffer
+
+    // if you don't have any more data, set *out_size to 0
+}
+
+HttpRequest* req = new HttpRequest(network, HTTP_POST, "http://my_api.com/upload");
+req->send(callback(&get_chunk));
+```
+
 ## Socket re-use
 
 By default the library opens a new socket per request. This is wasteful, especially when dealing with TLS requests. You can re-use sockets like this:
@@ -103,3 +119,6 @@
 * K64F with Ethernet.
 * NUCLEO_F411RE with ESP8266.
 * ODIN-W2 with WiFi.
+* K64F with Atmel 6LoWPAN shield.
+
+But this should work with any Mbed OS 5 device that implements the `NetworkInterface` API.