Kentaro Sekimoto / mbed-http

mbed-http

Fork of mbed-http by sandbox

README.md@12:530c2ebee349, 2017-03-28 (annotated)

Committer:
Jan Jongboom
Date:
Tue Mar 28 14:47:51 2017 +0200
Revision:
12:530c2ebee349
Parent:
5:2456c90f02e9
Child:
19:a5371b71de6f
Update README for socket reuse

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 12:530c2ebee349 57 ## Socket re-use
Jan Jongboom 12:530c2ebee349 58
Jan Jongboom 12:530c2ebee349 59 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:
Jan Jongboom 12:530c2ebee349 60
Jan Jongboom 12:530c2ebee349 61 ### HTTP
Jan Jongboom 12:530c2ebee349 62
Jan Jongboom 12:530c2ebee349 63 ```cpp
Jan Jongboom 12:530c2ebee349 64 TCPSocket* socket = new TCPSocket();
Jan Jongboom 12:530c2ebee349 65
Jan Jongboom 12:530c2ebee349 66 nsapi_error_t open_result = socket->open(network);
Jan Jongboom 12:530c2ebee349 67 // check open_result
Jan Jongboom 12:530c2ebee349 68
Jan Jongboom 12:530c2ebee349 69 nsapi_error_t connect_result = socket->connect("httpbin.org", 80);
Jan Jongboom 12:530c2ebee349 70 // check connect_result
Jan Jongboom 12:530c2ebee349 71
Jan Jongboom 12:530c2ebee349 72 // Pass in `socket`, instead of `network` as first argument
Jan Jongboom 12:530c2ebee349 73 HttpRequest* req = new HttpRequest(socket, HTTP_GET, "http://httpbin.org/status/418");
Jan Jongboom 12:530c2ebee349 74 ```
Jan Jongboom 12:530c2ebee349 75
Jan Jongboom 12:530c2ebee349 76 ### HTTPS
Jan Jongboom 12:530c2ebee349 77
Jan Jongboom 12:530c2ebee349 78 ```cpp
Jan Jongboom 12:530c2ebee349 79 TLSSocket* socket = new TLSSocket(network, "httpbin.org", 443, SSL_CA_PEM);
Jan Jongboom 12:530c2ebee349 80 socket->set_debug(true);
Jan Jongboom 12:530c2ebee349 81 if (socket->connect() != 0) {
Jan Jongboom 12:530c2ebee349 82 printf("TLS Connect failed %d\n", socket->error());
Jan Jongboom 12:530c2ebee349 83 return 1;
Jan Jongboom 12:530c2ebee349 84 }
Jan Jongboom 12:530c2ebee349 85
Jan Jongboom 12:530c2ebee349 86 // Pass in `socket`, instead of `network` as first argument, and omit the `SSL_CA_PEM` argument
Jan Jongboom 12:530c2ebee349 87 HttpsRequest* get_req = new HttpsRequest(socket, HTTP_GET, "https://httpbin.org/status/418");
Jan Jongboom 12:530c2ebee349 88 ```
Jan Jongboom 12:530c2ebee349 89
Jan Jongboom 0:910f5949759f 90 ## Tested on
Jan Jongboom 0:910f5949759f 91
Jan Jongboom 0:910f5949759f 92 * K64F with Ethernet.
Jan Jongboom 0:910f5949759f 93 * NUCLEO_F411RE with ESP8266.