Alcatel-Lucent IoT Development / HTTPClient

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 HTTPClient by David Smart

HTTPClient.h@24:eee214e3e806, 2014-03-15 (annotated)

Committer:
WiredHome
Date:
Sat Mar 15 22:18:30 2014 +0000
Revision:
24:eee214e3e806
Parent:
23:517fec8b8b99
Child:
30:1df62fedb13b
Reformatted to match standard style.; Added support for automatically following redirection, and for getting the redirect location.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
donatien 0:2ccb9960a044 1 /* HTTPClient.h */
donatien 10:e1351de84c16 2 /* Copyright (C) 2012 mbed.org, MIT License
donatien 10:e1351de84c16 3 *
donatien 10:e1351de84c16 4 * Permission is hereby granted, free of charge, to any person obtaining a copy of this software
donatien 10:e1351de84c16 5 * and associated documentation files (the "Software"), to deal in the Software without restriction,
donatien 10:e1351de84c16 6 * including without limitation the rights to use, copy, modify, merge, publish, distribute,
donatien 10:e1351de84c16 7 * sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
donatien 10:e1351de84c16 8 * furnished to do so, subject to the following conditions:
donatien 10:e1351de84c16 9 *
donatien 10:e1351de84c16 10 * The above copyright notice and this permission notice shall be included in all copies or
donatien 10:e1351de84c16 11 * substantial portions of the Software.
donatien 10:e1351de84c16 12 *
donatien 10:e1351de84c16 13 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
donatien 10:e1351de84c16 14 * BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
donatien 10:e1351de84c16 15 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
donatien 10:e1351de84c16 16 * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
donatien 10:e1351de84c16 17 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
donatien 10:e1351de84c16 18 */
donatien 0:2ccb9960a044 19
donatien 0:2ccb9960a044 20 /** \file
donatien 0:2ccb9960a044 21 HTTP Client header file
donatien 0:2ccb9960a044 22 */
donatien 0:2ccb9960a044 23
donatien 0:2ccb9960a044 24 #ifndef HTTP_CLIENT_H
donatien 0:2ccb9960a044 25 #define HTTP_CLIENT_H
donatien 0:2ccb9960a044 26
donatien 11:390362de8c3f 27 #include "TCPSocketConnection.h"
donatien 0:2ccb9960a044 28
donatien 12:89d09a6db00a 29 #define HTTP_CLIENT_DEFAULT_TIMEOUT 15000
donatien 0:2ccb9960a044 30
donatien 0:2ccb9960a044 31 class HTTPData;
donatien 0:2ccb9960a044 32
donatien 0:2ccb9960a044 33 #include "IHTTPData.h"
donatien 0:2ccb9960a044 34 #include "mbed.h"
donatien 0:2ccb9960a044 35
donatien 0:2ccb9960a044 36 ///HTTP client results
WiredHome 20:4ea5255c1b04 37 enum HTTPResult {
WiredHome 20:4ea5255c1b04 38 HTTP_PROCESSING, ///<Processing
WiredHome 20:4ea5255c1b04 39 HTTP_PARSE, ///<url Parse error
WiredHome 20:4ea5255c1b04 40 HTTP_DNS, ///<Could not resolve name
WiredHome 20:4ea5255c1b04 41 HTTP_PRTCL, ///<Protocol error
WiredHome 20:4ea5255c1b04 42 HTTP_NOTFOUND, ///<HTTP 404 Error
WiredHome 20:4ea5255c1b04 43 HTTP_REFUSED, ///<HTTP 403 Error
WiredHome 20:4ea5255c1b04 44 HTTP_ERROR, ///<HTTP xxx error
WiredHome 20:4ea5255c1b04 45 HTTP_TIMEOUT, ///<Connection timeout
WiredHome 20:4ea5255c1b04 46 HTTP_CONN, ///<Connection error
WiredHome 20:4ea5255c1b04 47 HTTP_CLOSED, ///<Connection was closed by remote host
WiredHome 20:4ea5255c1b04 48 HTTP_OK = 0, ///<Success
donatien 0:2ccb9960a044 49 };
donatien 0:2ccb9960a044 50
donatien 0:2ccb9960a044 51 /**A simple HTTP Client
donatien 0:2ccb9960a044 52 The HTTPClient is composed of:
donatien 0:2ccb9960a044 53 - The actual client (HTTPClient)
donatien 0:2ccb9960a044 54 - Classes that act as a data repository, each of which deriving from the HTTPData class (HTTPText for short text content, HTTPFile for file I/O, HTTPMap for key/value pairs, and HTTPStream for streaming purposes)
donatien 0:2ccb9960a044 55 */
donatien 0:2ccb9960a044 56 class HTTPClient
donatien 0:2ccb9960a044 57 {
donatien 0:2ccb9960a044 58 public:
WiredHome 20:4ea5255c1b04 59 ///Instantiate the HTTP client
WiredHome 20:4ea5255c1b04 60 HTTPClient();
WiredHome 20:4ea5255c1b04 61 ~HTTPClient();
WiredHome 20:4ea5255c1b04 62
WiredHome 20:4ea5255c1b04 63 /**
WiredHome 20:4ea5255c1b04 64 Provides a basic authentification feature (Base64 encoded username and password)
WiredHome 20:4ea5255c1b04 65 Pass two NULL pointers to switch back to no authentication
WiredHome 20:4ea5255c1b04 66 @param user username to use for authentication, must remain valid durlng the whole HTTP session
WiredHome 20:4ea5255c1b04 67 @param user password to use for authentication, must remain valid durlng the whole HTTP session
WiredHome 20:4ea5255c1b04 68 */
WiredHome 20:4ea5255c1b04 69 void basicAuth(const char* user, const char* password); //Basic Authentification
WiredHome 20:4ea5255c1b04 70
WiredHome 20:4ea5255c1b04 71 /**
WiredHome 20:4ea5255c1b04 72 Set custom headers for request.
WiredHome 20:4ea5255c1b04 73
WiredHome 20:4ea5255c1b04 74 Pass NULL, 0 to turn off custom headers.
WiredHome 20:4ea5255c1b04 75
WiredHome 20:4ea5255c1b04 76 @code
WiredHome 20:4ea5255c1b04 77 const char * hdrs[] =
WiredHome 20:4ea5255c1b04 78 {
WiredHome 20:4ea5255c1b04 79 "Connection", "keep-alive",
WiredHome 20:4ea5255c1b04 80 "Accept", "text/html",
WiredHome 20:4ea5255c1b04 81 "User-Agent", "Mozilla/5.0 (Windows NT 6.1; WOW64)",
WiredHome 20:4ea5255c1b04 82 "Accept-Encoding", "gzip,deflate,sdch",
WiredHome 20:4ea5255c1b04 83 "Accept-Language", "en-US,en;q=0.8",
WiredHome 20:4ea5255c1b04 84 };
WiredHome 20:4ea5255c1b04 85
WiredHome 20:4ea5255c1b04 86 http.basicAuth("username", "password");
WiredHome 20:4ea5255c1b04 87 http.customHeaders(hdrs, 5);
WiredHome 20:4ea5255c1b04 88 @endcode
WiredHome 20:4ea5255c1b04 89
WiredHome 20:4ea5255c1b04 90 @param headers an array (size multiple of two) key-value pairs, must remain valid during the whole HTTP session
WiredHome 20:4ea5255c1b04 91 @param pairs number of key-value pairs
WiredHome 20:4ea5255c1b04 92 */
WiredHome 20:4ea5255c1b04 93 void customHeaders(const char** headers, size_t pairs);
WiredHome 20:4ea5255c1b04 94
WiredHome 20:4ea5255c1b04 95 //High Level setup functions
WiredHome 20:4ea5255c1b04 96 /** Execute a GET request on the URL
WiredHome 20:4ea5255c1b04 97 Blocks until completion
WiredHome 20:4ea5255c1b04 98 @param url : url on which to execute the request
WiredHome 20:4ea5255c1b04 99 @param pDataIn : pointer to an IHTTPDataIn instance that will collect the data returned by the request, can be NULL
WiredHome 20:4ea5255c1b04 100 @param timeout waiting timeout in ms (osWaitForever for blocking function, not recommended)
WiredHome 20:4ea5255c1b04 101 @return 0 on success, HTTP error (<0) on failure
WiredHome 20:4ea5255c1b04 102 */
WiredHome 20:4ea5255c1b04 103 HTTPResult get(const char* url, IHTTPDataIn* pDataIn, int timeout = HTTP_CLIENT_DEFAULT_TIMEOUT); //Blocking
WiredHome 20:4ea5255c1b04 104
WiredHome 20:4ea5255c1b04 105 /** Execute a GET request on the URL
WiredHome 20:4ea5255c1b04 106 Blocks until completion
WiredHome 20:4ea5255c1b04 107 This is a helper to directly get a piece of text from a HTTP result
WiredHome 20:4ea5255c1b04 108 @param url : url on which to execute the request
WiredHome 20:4ea5255c1b04 109 @param result : pointer to a char array in which the result will be stored
WiredHome 20:4ea5255c1b04 110 @param maxResultLen : length of the char array (including space for the NULL-terminating char)
WiredHome 20:4ea5255c1b04 111 @param timeout waiting timeout in ms (osWaitForever for blocking function, not recommended)
WiredHome 20:4ea5255c1b04 112 @return 0 on success, HTTP error (<0) on failure
WiredHome 20:4ea5255c1b04 113 */
WiredHome 20:4ea5255c1b04 114 HTTPResult get(const char* url, char* result, size_t maxResultLen, int timeout = HTTP_CLIENT_DEFAULT_TIMEOUT); //Blocking
donatien 0:2ccb9960a044 115
WiredHome 20:4ea5255c1b04 116 /** Execute a POST request on the URL
WiredHome 20:4ea5255c1b04 117 Blocks until completion
WiredHome 20:4ea5255c1b04 118 @param url : url on which to execute the request
WiredHome 20:4ea5255c1b04 119 @param dataOut : a IHTTPDataOut instance that contains the data that will be posted
WiredHome 20:4ea5255c1b04 120 @param pDataIn : pointer to an IHTTPDataIn instance that will collect the data returned by the request, can be NULL
WiredHome 20:4ea5255c1b04 121 @param timeout waiting timeout in ms (osWaitForever for blocking function, not recommended)
WiredHome 20:4ea5255c1b04 122 @return 0 on success, HTTP error (<0) on failure
WiredHome 20:4ea5255c1b04 123 */
WiredHome 20:4ea5255c1b04 124 HTTPResult post(const char* url, const IHTTPDataOut& dataOut, IHTTPDataIn* pDataIn, int timeout = HTTP_CLIENT_DEFAULT_TIMEOUT); //Blocking
WiredHome 20:4ea5255c1b04 125
WiredHome 20:4ea5255c1b04 126 /** Execute a PUT request on the URL
WiredHome 20:4ea5255c1b04 127 Blocks until completion
WiredHome 20:4ea5255c1b04 128 @param url : url on which to execute the request
WiredHome 20:4ea5255c1b04 129 @param dataOut : a IHTTPDataOut instance that contains the data that will be put
WiredHome 20:4ea5255c1b04 130 @param pDataIn : pointer to an IHTTPDataIn instance that will collect the data returned by the request, can be NULL
WiredHome 20:4ea5255c1b04 131 @param timeout waiting timeout in ms (osWaitForever for blocking function, not recommended)
WiredHome 20:4ea5255c1b04 132 @return 0 on success, HTTP error (<0) on failure
WiredHome 20:4ea5255c1b04 133 */
WiredHome 20:4ea5255c1b04 134 HTTPResult put(const char* url, const IHTTPDataOut& dataOut, IHTTPDataIn* pDataIn, int timeout = HTTP_CLIENT_DEFAULT_TIMEOUT); //Blocking
WiredHome 20:4ea5255c1b04 135
WiredHome 20:4ea5255c1b04 136 /** Execute a DELETE request on the URL
WiredHome 20:4ea5255c1b04 137 Blocks until completion
WiredHome 20:4ea5255c1b04 138 @param url : url on which to execute the request
WiredHome 20:4ea5255c1b04 139 @param pDataIn : pointer to an IHTTPDataIn instance that will collect the data returned by the request, can be NULL
WiredHome 20:4ea5255c1b04 140 @param timeout waiting timeout in ms (osWaitForever for blocking function, not recommended)
WiredHome 20:4ea5255c1b04 141 @return 0 on success, HTTP error (<0) on failure
WiredHome 20:4ea5255c1b04 142 */
WiredHome 20:4ea5255c1b04 143 HTTPResult del(const char* url, IHTTPDataIn* pDataIn, int timeout = HTTP_CLIENT_DEFAULT_TIMEOUT); //Blocking
WiredHome 20:4ea5255c1b04 144
WiredHome 20:4ea5255c1b04 145 /** Get last request's HTTP response code
WiredHome 20:4ea5255c1b04 146 @return The HTTP response code of the last request
WiredHome 20:4ea5255c1b04 147 */
WiredHome 20:4ea5255c1b04 148 int getHTTPResponseCode();
WiredHome 20:4ea5255c1b04 149
WiredHome 24:eee214e3e806 150 /** Set the maximum number of automated redirections
WiredHome 24:eee214e3e806 151 @param i is the number of redirections. Values < 1 are
WiredHome 24:eee214e3e806 152 set to 1.
WiredHome 24:eee214e3e806 153 */
WiredHome 24:eee214e3e806 154 void setMaxRedirections(int i = 1);
WiredHome 24:eee214e3e806 155
WiredHome 24:eee214e3e806 156 /** get the redirect location url
WiredHome 24:eee214e3e806 157 @returns const char pointer to the url.
WiredHome 24:eee214e3e806 158 */
WiredHome 24:eee214e3e806 159 const char * getLocation() {
WiredHome 24:eee214e3e806 160 return m_location;
WiredHome 24:eee214e3e806 161 }
WiredHome 24:eee214e3e806 162
donatien 0:2ccb9960a044 163 private:
WiredHome 20:4ea5255c1b04 164 enum HTTP_METH {
WiredHome 20:4ea5255c1b04 165 HTTP_GET,
WiredHome 20:4ea5255c1b04 166 HTTP_POST,
WiredHome 20:4ea5255c1b04 167 HTTP_PUT,
WiredHome 20:4ea5255c1b04 168 HTTP_DELETE,
WiredHome 20:4ea5255c1b04 169 HTTP_HEAD
WiredHome 20:4ea5255c1b04 170 };
donatien 0:2ccb9960a044 171
WiredHome 20:4ea5255c1b04 172 HTTPResult connect(const char* url, HTTP_METH method, IHTTPDataOut* pDataOut, IHTTPDataIn* pDataIn, int timeout); //Execute request
WiredHome 20:4ea5255c1b04 173 HTTPResult recv(char* buf, size_t minLen, size_t maxLen, size_t* pReadLen); //0 on success, err code on failure
WiredHome 20:4ea5255c1b04 174 HTTPResult send(char* buf, size_t len = 0); //0 on success, err code on failure
WiredHome 20:4ea5255c1b04 175 HTTPResult parseURL(const char* url, char* scheme, size_t maxSchemeLen, char* host, size_t maxHostLen, uint16_t* port, char* path, size_t maxPathLen); //Parse URL
WiredHome 20:4ea5255c1b04 176 void createauth (const char *user, const char *pwd, char *buf, int len);
WiredHome 20:4ea5255c1b04 177 int base64enc(const char *input, unsigned int length, char *output, int len);
donatien 0:2ccb9960a044 178
WiredHome 20:4ea5255c1b04 179 //Parameters
WiredHome 20:4ea5255c1b04 180 TCPSocketConnection m_sock;
WiredHome 20:4ea5255c1b04 181
WiredHome 20:4ea5255c1b04 182 int m_timeout;
donatien 0:2ccb9960a044 183
WiredHome 21:d33f7e1ce811 184 char* m_basicAuthUser;
WiredHome 21:d33f7e1ce811 185 char* m_basicAuthPassword;
WiredHome 20:4ea5255c1b04 186 const char** m_customHeaders;
WiredHome 20:4ea5255c1b04 187 size_t m_nCustomHeaders;
WiredHome 20:4ea5255c1b04 188 int m_httpResponseCode;
WiredHome 24:eee214e3e806 189 int m_maxredirections;
WiredHome 24:eee214e3e806 190 char * m_location;
donatien 0:2ccb9960a044 191
donatien 0:2ccb9960a044 192 };
donatien 0:2ccb9960a044 193
donatien 0:2ccb9960a044 194 //Including data containers here for more convenience
donatien 0:2ccb9960a044 195 #include "data/HTTPText.h"
donatien 0:2ccb9960a044 196 #include "data/HTTPMap.h"
WiredHome 23:517fec8b8b99 197 #include "data/HTTPFile.h"
donatien 0:2ccb9960a044 198
donatien 0:2ccb9960a044 199 #endif