HTTPClient.h

00001 /* HTTPClient.h */
00002 /* Copyright (C) 2012 mbed.org, MIT License
00003  *
00004  * Permission is hereby granted, free of charge, to any person obtaining a copy of this software
00005  * and associated documentation files (the "Software"), to deal in the Software without restriction,
00006  * including without limitation the rights to use, copy, modify, merge, publish, distribute,
00007  * sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
00008  * furnished to do so, subject to the following conditions:
00009  *
00010  * The above copyright notice and this permission notice shall be included in all copies or
00011  * substantial portions of the Software.
00012  *
00013  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
00014  * BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
00015  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
00016  * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
00017  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
00018  */
00019 
00020 /** \file
00021 HTTP Client header file
00022 */
00023 
00024 #ifndef HTTP_CLIENT_H
00025 #define HTTP_CLIENT_H
00026 
00027 #define HTTP_CLIENT_DEFAULT_TIMEOUT 15000
00028 
00029 class HTTPData;
00030 
00031 #include "IHTTPData.h"
00032 #include "mbed.h"
00033 #include "TCPSocketConnection.h"
00034 
00035 ///SSL peer verification setting    
00036 enum SSLMethod {
00037     VERIFY_NONE                 = 0, ///Don't check peer certificate
00038     VERIFY_PEER                 = 1, ///Client:Check peer certificate, Server:Check peer certificate and skip if no certificate received
00039     VERIFY_FAIL_IF_NO_PEER_CERT = 2, ///Client:Check peer certificate, Server:Check peer certificate and fail if none found
00040 };
00041 
00042 ///HTTP client results
00043 enum HTTPResult {
00044     HTTP_OK = 0, ///<Success
00045     HTTP_PROCESSING, ///<Processing
00046     HTTP_PARSE, ///<url Parse error
00047     HTTP_DNS, ///<Could not resolve name
00048     HTTP_PRTCL, ///<Protocol error
00049     HTTP_NOTFOUND, ///<HTTP 404 Error
00050     HTTP_REFUSED, ///<HTTP 403 Error
00051     HTTP_ERROR, ///<HTTP xxx error
00052     HTTP_TIMEOUT, ///<Connection timeout
00053     HTTP_CONN, ///<Connection error
00054     HTTP_CLOSED, ///<Connection was closed by remote host
00055     HTTP_REDIRECT, ///<HTTP 300 - 303
00056 };
00057 
00058 /**A simple HTTP Client
00059 The HTTPClient is composed of:
00060 - The actual client (HTTPClient)
00061 - 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)
00062 */
00063 class HTTPClient
00064 {
00065 public:
00066     ///Instantiate the HTTP client
00067     HTTPClient();
00068     ~HTTPClient();
00069 
00070     /**
00071     Provides a basic authentification feature (Base64 encoded username and password)
00072     Pass two NULL pointers to switch back to no authentication
00073     @param user username to use for authentication, must remain valid durlng the whole HTTP session
00074     @param user password to use for authentication, must remain valid durlng the whole HTTP session
00075     */
00076     HTTPResult basicAuth(const char* user, const char* password); //Basic Authentification
00077 
00078     //High Level setup functions
00079     /** Execute a GET request on the URL
00080     Blocks until completion
00081     @param url : url on which to execute the request. Format of: http[s]://<host>/[<path>][#fragment_id]
00082     @param pDataIn : pointer to an IHTTPDataIn instance that will collect the data returned by the request, can be NULL
00083     @param timeout waiting timeout in ms (osWaitForever for blocking function, not recommended)
00084     @return 0 on success, HTTP error (<0) on failure
00085     */
00086     HTTPResult get(const char* url, IHTTPDataIn* pDataIn, int timeout = HTTP_CLIENT_DEFAULT_TIMEOUT); //Blocking
00087 
00088     /** Execute a GET request on the URL
00089     Blocks until completion
00090     This is a helper to directly get a piece of text from a HTTP result
00091     @param url : url on which to execute the request. Format of: http[s]://<host>/[<path>][#fragment_id]
00092     @param result : pointer to a char array in which the result will be stored
00093     @param maxResultLen : length of the char array (including space for the NULL-terminating char)
00094     @param timeout waiting timeout in ms (osWaitForever for blocking function, not recommended)
00095     @return 0 on success, HTTP error (<0) on failure
00096     */
00097     HTTPResult get(const char* url, char* result, size_t maxResultLen, int timeout = HTTP_CLIENT_DEFAULT_TIMEOUT); //Blocking
00098 
00099     /** Execute a POST request on the URL
00100     Blocks until completion
00101     @param url : url on which to execute the request. Format of: http[s]://<host>/[<path>][#fragment_id]
00102     @param dataOut : a IHTTPDataOut instance that contains the data that will be posted
00103     @param pDataIn : pointer to an IHTTPDataIn instance that will collect the data returned by the request, can be NULL
00104     @param timeout waiting timeout in ms (osWaitForever for blocking function, not recommended)
00105     @return 0 on success, HTTP error (<0) on failure
00106     */
00107     HTTPResult post(const char* url, const IHTTPDataOut& dataOut, IHTTPDataIn* pDataIn, int timeout = HTTP_CLIENT_DEFAULT_TIMEOUT); //Blocking
00108 
00109     /** Execute a PUT request on the URL
00110     Blocks until completion
00111     @param url : url on which to execute the request. Format of: http[s]://<host>/[<path>][#fragment_id]
00112     @param dataOut : a IHTTPDataOut instance that contains the data that will be put
00113     @param pDataIn : pointer to an IHTTPDataIn instance that will collect the data returned by the request, can be NULL
00114     @param timeout waiting timeout in ms (osWaitForever for blocking function, not recommended)
00115     @return 0 on success, HTTP error (<0) on failure
00116     */
00117     HTTPResult put(const char* url, const IHTTPDataOut& dataOut, IHTTPDataIn* pDataIn, int timeout = HTTP_CLIENT_DEFAULT_TIMEOUT); //Blocking
00118 
00119     /** Execute a DELETE request on the URL
00120     Blocks until completion
00121     @param url : url on which to execute the request. Format of: http[s]://<host>/[<path>][#fragment_id]
00122     @param pDataIn : pointer to an IHTTPDataIn instance that will collect the data returned by the request, can be NULL
00123     @param timeout waiting timeout in ms (osWaitForever for blocking function, not recommended)
00124     @return 0 on success, HTTP error (<0) on failure
00125     */
00126     HTTPResult del(const char* url, IHTTPDataIn* pDataIn, int timeout = HTTP_CLIENT_DEFAULT_TIMEOUT); //Blocking
00127 
00128     /** Get last request's HTTP response code
00129     @return The HTTP response code of the last request
00130     */
00131     int getHTTPResponseCode();
00132     
00133     /** Set headers to be included in the following HTTP requests. Pass a NULL pointer to reset the headers stored. 
00134     * Make sure the headers are formatted with a "\r\n" after each header.
00135     * @param header pointer to array containing the headers to be added*/
00136     void setHeader(const char *header) ;
00137     
00138     /** Set SSL/TLS version. 
00139     * @param minorV integer witha a value between 0 and 3
00140     * 0: SSL3, 1: TLS1.0, 2: TLS1.1, 3: TLS1.2 
00141     * @returns HTTPResult based on success*/
00142     HTTPResult setSSLversion(int minorV) ; 
00143     
00144     /* set URL buffer for redirection */
00145     void setLocationBuf(char *url, int size) ; 
00146     
00147     /** Stores a root CA certificate for host authentication of a website.
00148     * Each new line should end with "\r\n" including the last line of each certificate.
00149     * Pass a pointer to the char array containing the certificate stored as a c-string.
00150     * Pass a NULL pointer to reset all certificates stored. 
00151     * (Can pass in multiple certificates with one function call if the array contains concatenated certificates) */
00152     HTTPResult addRootCACertificate(const char* cert) ;
00153     
00154     /** Sets the verification for peer authenticity when connecting with SSL
00155     * @param method specifies the method to use for peer verification
00156     * @VERIFY_NONE Sets the client to not verify the peer's certificates
00157     * @VERIFY_PEER Sets the client to verify the peer's certificates but skips if certificates unavailable
00158     * @VERIFY_FAIL_IF_NO_PEER_CERT Sets the client to verify the peer's certificates and throw an error if the 
00159     * certificates are unavailable.
00160     * */
00161     void setPeerVerification(SSLMethod method);
00162 
00163 private:
00164     enum HTTP_METH {
00165         HTTP_GET,
00166         HTTP_POST,
00167         HTTP_PUT,
00168         HTTP_DELETE,
00169         HTTP_HEAD
00170     };
00171 
00172     HTTPResult connect(const char* url, HTTP_METH method, IHTTPDataOut* pDataOut, IHTTPDataIn* pDataIn, int timeout); //Execute request
00173     HTTPResult recv(char* buf, size_t minLen, size_t maxLen, size_t* pReadLen); //0 on success, err code on failure
00174     HTTPResult send(char* buf, size_t len = 0); //0 on success, err code on failure
00175     HTTPResult flush(void); //0 on success, err code on failure
00176     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
00177     void cyassl_free(void) ;
00178     HTTPResult bAuth(void) ;
00179     HTTPResult readHeader(void) ;
00180     
00181     //Parameters
00182     TCPSocketConnection _m_sock;
00183 
00184     int m_timeout;
00185     
00186     const char* m_basicAuthUser;
00187     const char* m_basicAuthPassword;
00188     int m_httpResponseCode;
00189 
00190     const char * header ;
00191     char * redirect_url ;
00192     int    redirect_url_size ;
00193     int    redirect ;
00194     
00195     /* for CyaSSL */
00196     const char* certificates; //CA certificates
00197     SSLMethod peerMethod;
00198     int    SSLver ;
00199     uint16_t port;
00200     struct CYASSL_CTX* ctx ;
00201     struct CYASSL    * ssl ;
00202 };
00203 
00204 //Including data containers here for more convenience
00205 #include "data/HTTPJson.h"
00206 #include "data/HTTPMap.h"
00207 
00208 #endif