Nigel Rantor / mbed-http

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Fork of mbed-http by sandbox

README.md@5:2456c90f02e9, 2017-02-23 (annotated)

Committer:
Jan Jongboom
Date:
Thu Feb 23 13:56:17 2017 +0100
Revision:
5:2456c90f02e9
Parent:
0:910f5949759f
Child:
12:530c2ebee349
Update README

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 5:2456c90f02e9 12 HttpRequest* request = new HttpRequest(network, HTTP_POST, "http://httpbin.org/post");
Jan Jongboom 5:2456c90f02e9 13 request->set_header("Content-Type", "application/json");
Jan Jongboom 5:2456c90f02e9 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 5:2456c90f02e9 18 printf("body is:\n%s\n", response->get_body_as_string().c_str());
Jan Jongboom 5:2456c90f02e9 19
Jan Jongboom 5:2456c90f02e9 20 delete request; // also clears out the response
Jan Jongboom 0:910f5949759f 21 ```
Jan Jongboom 0:910f5949759f 22
Jan Jongboom 0:910f5949759f 23 ## HTTPS Request API
Jan Jongboom 0:910f5949759f 24
Jan Jongboom 0:910f5949759f 25 ```cpp
Jan Jongboom 0:910f5949759f 26 // pass in the root certificates that you trust, there is no central CA registry in mbed OS
Jan Jongboom 0:910f5949759f 27 const char SSL_CA_PEM[] = "-----BEGIN CERTIFICATE-----\n"
Jan Jongboom 0:910f5949759f 28 /* rest of the CA root certificates */;
Jan Jongboom 0:910f5949759f 29
Jan Jongboom 0:910f5949759f 30 NetworkInterface* network = /* obtain a NetworkInterface object */
Jan Jongboom 0:910f5949759f 31
Jan Jongboom 0:910f5949759f 32 const char body[] = "{\"hello\":\"world\"}";
Jan Jongboom 0:910f5949759f 33
Jan Jongboom 5:2456c90f02e9 34 HttpsRequest* request = new HttpsRequest(network, SSL_CA_PEM, HTTP_GET "https://httpbin.org/status/418");
Jan Jongboom 5:2456c90f02e9 35 HttpResponse* response = request->send();
Jan Jongboom 0:910f5949759f 36 // if response is NULL, check response->get_error()
Jan Jongboom 0:910f5949759f 37
Jan Jongboom 0:910f5949759f 38 printf("status is %d - %s\n", response->get_status_code(), response->get_status_message());
Jan Jongboom 0:910f5949759f 39 printf("body is:\n%s\n", response->get_body().c_str());
Jan Jongboom 5:2456c90f02e9 40
Jan Jongboom 5:2456c90f02e9 41 delete request;
Jan Jongboom 0:910f5949759f 42 ```
Jan Jongboom 0:910f5949759f 43
Jan Jongboom 0:910f5949759f 44 ## Dealing with large body
Jan Jongboom 0:910f5949759f 45
Jan Jongboom 5:2456c90f02e9 46 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.
Jan Jongboom 0:910f5949759f 47
Jan Jongboom 0:910f5949759f 48 ```cpp
Jan Jongboom 0:910f5949759f 49 void body_callback(const char* data, size_t data_len) {
Jan Jongboom 0:910f5949759f 50 // do something with the data
Jan Jongboom 0:910f5949759f 51 }
Jan Jongboom 0:910f5949759f 52
Jan Jongboom 5:2456c90f02e9 53 HttpRequest* req = new HttpRequest(network, HTTP_GET, "http://pathtolargefile.com");
Jan Jongboom 5:2456c90f02e9 54 req->send(NULL, 0, body_callback);
Jan Jongboom 0:910f5949759f 55 ```
Jan Jongboom 0:910f5949759f 56
Jan Jongboom 0:910f5949759f 57 ## Tested on
Jan Jongboom 0:910f5949759f 58
Jan Jongboom 0:910f5949759f 59 * K64F with Ethernet.
Jan Jongboom 0:910f5949759f 60 * NUCLEO_F411RE with ESP8266.