Kentaro Sekimoto / mbed-http

mbed-http

Fork of mbed-http by sandbox

README.md@0:910f5949759f, 2017-02-16 (annotated)

Committer:
Jan Jongboom
Date:
Thu Feb 16 11:35:56 2017 +0100
Revision:
0:910f5949759f
Child:
5:2456c90f02e9
Initial commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Jan Jongboom 0:910f5949759f 1 # HTTP and HTTPS library for mbed OS 5
Jan Jongboom 0:910f5949759f 2
Jan Jongboom 0:910f5949759f 3 This library is used to make HTTP and HTTPS calls from mbed OS 5 applications.
Jan Jongboom 0:910f5949759f 4
Jan Jongboom 0:910f5949759f 5 ## HTTP Request API
Jan Jongboom 0:910f5949759f 6
Jan Jongboom 0:910f5949759f 7 ```cpp
Jan Jongboom 0:910f5949759f 8 NetworkInterface* network = /* obtain a NetworkInterface object */
Jan Jongboom 0:910f5949759f 9
Jan Jongboom 0:910f5949759f 10 const char body[] = "{\"hello\":\"world\"}";
Jan Jongboom 0:910f5949759f 11
Jan Jongboom 0:910f5949759f 12 HttpRequest request(network, HTTP_POST, "http://httpbin.org/post");
Jan Jongboom 0:910f5949759f 13 request.set_header("Content-Type", "application/json);
Jan Jongboom 0:910f5949759f 14 HttpResponse* response = request.send(body, strlen(body));
Jan Jongboom 0:910f5949759f 15 // if response is NULL, check response->get_error()
Jan Jongboom 0:910f5949759f 16
Jan Jongboom 0:910f5949759f 17 printf("status is %d - %s\n", response->get_status_code(), response->get_status_message());
Jan Jongboom 0:910f5949759f 18 printf("body is:\n%s\n", response->get_body().c_str());
Jan Jongboom 0:910f5949759f 19 ```
Jan Jongboom 0:910f5949759f 20
Jan Jongboom 0:910f5949759f 21 ## HTTPS Request API
Jan Jongboom 0:910f5949759f 22
Jan Jongboom 0:910f5949759f 23 ```cpp
Jan Jongboom 0:910f5949759f 24 // pass in the root certificates that you trust, there is no central CA registry in mbed OS
Jan Jongboom 0:910f5949759f 25 const char SSL_CA_PEM[] = "-----BEGIN CERTIFICATE-----\n"
Jan Jongboom 0:910f5949759f 26 /* rest of the CA root certificates */;
Jan Jongboom 0:910f5949759f 27
Jan Jongboom 0:910f5949759f 28 NetworkInterface* network = /* obtain a NetworkInterface object */
Jan Jongboom 0:910f5949759f 29
Jan Jongboom 0:910f5949759f 30 const char body[] = "{\"hello\":\"world\"}";
Jan Jongboom 0:910f5949759f 31
Jan Jongboom 0:910f5949759f 32 HttpsRequest request(network, SSL_CA_PEM, HTTP_GET "https://httpbin.org/status/418");
Jan Jongboom 0:910f5949759f 33 HttpResponse* response = request.send();
Jan Jongboom 0:910f5949759f 34 // if response is NULL, check response->get_error()
Jan Jongboom 0:910f5949759f 35
Jan Jongboom 0:910f5949759f 36 printf("status is %d - %s\n", response->get_status_code(), response->get_status_message());
Jan Jongboom 0:910f5949759f 37 printf("body is:\n%s\n", response->get_body().c_str());
Jan Jongboom 0:910f5949759f 38 ```
Jan Jongboom 0:910f5949759f 39
Jan Jongboom 0:910f5949759f 40 ## Dealing with large body
Jan Jongboom 0:910f5949759f 41
Jan Jongboom 0:910f5949759f 42 By default the library will store the full request body on the stack. 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).
Jan Jongboom 0:910f5949759f 43
Jan Jongboom 0:910f5949759f 44 ```cpp
Jan Jongboom 0:910f5949759f 45 void body_callback(const char* data, size_t data_len) {
Jan Jongboom 0:910f5949759f 46 // do something with the data
Jan Jongboom 0:910f5949759f 47 }
Jan Jongboom 0:910f5949759f 48
Jan Jongboom 0:910f5949759f 49 HttpRequest req(network, HTTP_GET, "http://pathtolargefile.com");
Jan Jongboom 0:910f5949759f 50 ```
Jan Jongboom 0:910f5949759f 51
Jan Jongboom 0:910f5949759f 52 ## Tested on
Jan Jongboom 0:910f5949759f 53
Jan Jongboom 0:910f5949759f 54 * K64F with Ethernet.
Jan Jongboom 0:910f5949759f 55 * NUCLEO_F411RE with ESP8266.