HTTPClient.h

00001 /* HTTPClient.h */
00002 /*
00003 Copyright (C) 2012 ARM Limited.
00004 
00005 Permission is hereby granted, free of charge, to any person obtaining a copy of
00006 this software and associated documentation files (the "Software"), to deal in
00007 the Software without restriction, including without limitation the rights to
00008 use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
00009 of the Software, and to permit persons to whom the Software is furnished to do
00010 so, subject to the following conditions:
00011 
00012 The above copyright notice and this permission notice shall be included in all
00013 copies or substantial portions of the Software.
00014 
00015 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
00016 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
00017 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
00018 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
00019 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
00020 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
00021 SOFTWARE.
00022 */
00023 
00024 /** \file
00025 HTTP Client header file
00026 */
00027 
00028 #ifndef HTTP_CLIENT_H
00029 #define HTTP_CLIENT_H
00030 
00031 #include "api/socket.h"
00032 
00033 #define HTTP_CLIENT_DEFAULT_TIMEOUT 4000
00034 
00035 class HTTPData;
00036 
00037 #include "IHTTPData.h"
00038 #include "mbed.h"
00039 
00040 ///HTTP client results
00041 enum HTTPResult
00042 {
00043   HTTP_OK, ///<Success
00044   HTTP_PROCESSING, ///<Processing
00045   HTTP_PARSE, ///<url Parse error
00046   HTTP_DNS, ///<Could not resolve name
00047   HTTP_PRTCL, ///<Protocol error
00048   HTTP_NOTFOUND, ///<HTTP 404 Error
00049   HTTP_REFUSED, ///<HTTP 403 Error
00050   HTTP_ERROR, ///<HTTP xxx error
00051   HTTP_TIMEOUT, ///<Connection timeout
00052   HTTP_CONN ///<Connection error
00053 };
00054 
00055 /**A simple HTTP Client
00056 The HTTPClient is composed of:
00057 - The actual client (HTTPClient)
00058 - 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)
00059 */
00060 class HTTPClient
00061 {
00062 public:
00063   ///Instantiate the HTTP client
00064   HTTPClient();
00065   ~HTTPClient();
00066   
00067 #if 0 //TODO add header handlers
00068   /**
00069   Provides a basic authentification feature (Base64 encoded username and password)
00070   Pass two NULL pointers to switch back to no authentication
00071   @param user username to use for authentication, must remain valid durlng the whole HTTP session
00072   @param user password to use for authentication, must remain valid durlng the whole HTTP session
00073   */
00074   void basicAuth(const char* user, const char* password); //Basic Authentification
00075 #endif
00076   
00077   //High Level setup functions
00078   /** Execute a GET request on the url
00079   Blocks until completion
00080   @param url : url on which to execute the request
00081   @param pDataIn : pointer to an IHTTPDataIn instance that will collect the data returned by the request, can be NULL
00082   @param timeout waiting timeout in ms (osWaitForever for blocking function, not recommended)
00083   @return 0 on success, NET error (<0) on failure
00084   */
00085   int get(const char* url, IHTTPDataIn* pDataIn, uint32_t timeout = HTTP_CLIENT_DEFAULT_TIMEOUT); //Blocking
00086   
00087   /** Execute a GET request on the url
00088   Blocks until completion
00089   This is a helper to directly get a piece of text from a HTTP result
00090   @param url : url on which to execute the request
00091   @param result : pointer to a char array in which the result will be stored
00092   @param maxResultLen : length of the char array (including space for the NULL-terminating char)
00093   @param timeout waiting timeout in ms (osWaitForever for blocking function, not recommended)
00094   @return 0 on success, NET error on failure
00095   */
00096   int get(const char* url, char* result, size_t maxResultLen, uint32_t timeout = HTTP_CLIENT_DEFAULT_TIMEOUT); //Blocking
00097 
00098   /** Execute a POST request on the url
00099   Blocks until completion
00100   @param url : url on which to execute the request
00101   @param dataOut : a IHTTPDataOut instance that contains the data that will be posted
00102   @param pDataIn : pointer to an IHTTPDataIn instance that will collect the data returned by the request, can be NULL
00103   @param timeout waiting timeout in ms (osWaitForever for blocking function, not recommended)
00104   @return 0 on success, NET error on failure
00105   */
00106   int post(const char* url, const IHTTPDataOut& dataOut, IHTTPDataIn* pDataIn, uint32_t timeout = HTTP_CLIENT_DEFAULT_TIMEOUT); //Blocking
00107   
00108   /** Get last request's HTTP response code
00109   @return The HTTP response code of the last request
00110   */
00111   int getHTTPResponseCode();
00112   
00113 private:
00114   enum HTTP_METH
00115   {
00116     HTTP_GET,
00117     HTTP_POST,
00118     HTTP_HEAD
00119   };
00120 
00121   int connect(const char* url, HTTP_METH method, IHTTPDataOut* pDataOut, IHTTPDataIn* pDataIn, uint32_t timeout); //Execute request
00122   int recv(char* buf, size_t minLen, size_t maxLen, size_t* pReadLen); //0 on success, err code on failure
00123   int send(char* buf, size_t len = 0); //0 on success, err code on failure
00124   int parseURL(const char* url, char* scheme, size_t maxSchemeLen, char* host, size_t maxHostLen, uint16_t* port, char* path, size_t maxPathLen); //Parse URL
00125 
00126   //Parameters
00127   int m_sock;
00128   uint32_t m_timeout;
00129 
00130   const char* m_basicAuthUser;
00131   const char* m_basicAuthPassword;
00132   int m_httpResponseCode;
00133 
00134   struct sockaddr_in m_serverAddr;
00135 
00136 };
00137 
00138 //Including data containers here for more convenience
00139 #include "data/HTTPText.h"
00140 #include "data/HTTPMap.h"
00141 
00142 #endif