HTTPClient.h

00001 
00002 /*
00003 Copyright (c) 2010 Donatien Garnier (donatiengar [at] gmail [dot] com)
00004  
00005 Permission is hereby granted, free of charge, to any person obtaining a copy
00006 of this software and associated documentation files (the "Software"), to deal
00007 in the Software without restriction, including without limitation the rights
00008 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
00009 copies of the Software, and to permit persons to whom the Software is
00010 furnished to do so, subject to the following conditions:
00011  
00012 The above copyright notice and this permission notice shall be included in
00013 all 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
00021 THE SOFTWARE.
00022 */
00023 
00024 /** \file
00025 HTTP Client header file
00026 */
00027 
00028 #ifndef HTTP_CLIENT_H
00029 #define HTTP_CLIENT_H
00030 
00031 class HTTPData;
00032 
00033 #include "core/net.h"
00034 #include "api/TCPSocket.h"
00035 #include "api/DNSRequest.h"
00036 #include "HTTPData.h"
00037 #include "mbed.h"
00038 
00039 #include <string>
00040 using std::string;
00041 
00042 #include <map>
00043 using std::map;
00044 
00045 ///HTTP client results
00046 enum HTTPResult
00047 {
00048   HTTP_OK, ///<Success
00049   HTTP_PROCESSING, ///<Processing
00050   HTTP_PARSE, ///<URI Parse error
00051   HTTP_DNS, ///<Could not resolve name
00052   HTTP_PRTCL, ///<Protocol error
00053   HTTP_NOTFOUND, ///<HTTP 404 Error
00054   HTTP_REFUSED, ///<HTTP 403 Error
00055   HTTP_ERROR, ///<HTTP xxx error
00056   HTTP_TIMEOUT, ///<Connection timeout
00057   HTTP_CONN ///<Connection error
00058 };
00059 
00060 #include "core/netservice.h"
00061 
00062 ///A simple HTTP Client
00063 /**
00064 The HTTPClient is composed of:
00065 - The actual client (HTTPClient)
00066 - 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)
00067 */
00068 class HTTPClient : protected NetService
00069 {
00070 public:
00071   ///Instantiates the HTTP client
00072   HTTPClient();
00073   virtual ~HTTPClient();
00074   
00075   ///Provides a basic authentification feature (Base64 encoded username and password)
00076   void basicAuth(const char* user, const char* password); //Basic Authentification
00077   
00078   //High Level setup functions
00079   ///Executes a GET Request (blocking)
00080   /**
00081   Executes a GET request on the URI uri
00082   @param uri : URI on which to execute the request
00083   @param pDataIn : pointer to an HTTPData instance that will collect the data returned by the request, can be NULL
00084   Blocks until completion
00085   */
00086   HTTPResult get(const char* uri, HTTPData* pDataIn); //Blocking
00087   
00088   ///Executes a GET Request (non blocking)
00089   /**
00090   Executes a GET request on the URI uri
00091   @param uri : URI on which to execute the request
00092   @param pDataIn : pointer to an HTTPData instance that will collect the data returned by the request, can be NULL
00093   @param pMethod : callback function
00094   The function returns immediately and calls the callback on completion or error
00095   */
00096   HTTPResult get(const char* uri, HTTPData* pDataIn, void (*pMethod)(HTTPResult)); //Non blocking
00097   
00098   ///Executes a GET Request (non blocking)
00099   /**
00100   Executes a GET request on the URI uri
00101   @param uri : URI on which to execute the request
00102   @param pDataIn : pointer to an HTTPData instance that will collect the data returned by the request, can be NULL
00103   @param pItem : instance of class on which to execute the callback method
00104   @param pMethod : callback method
00105   The function returns immediately and calls the callback on completion or error
00106   */
00107   template<class T> 
00108   HTTPResult get(const char* uri, HTTPData* pDataIn, T* pItem, void (T::*pMethod)(HTTPResult)) //Non blocking
00109   {
00110     setOnResult(pItem, pMethod);
00111     doGet(uri, pDataIn);
00112     return HTTP_PROCESSING;
00113   }
00114   
00115   ///Executes a POST Request (blocking)
00116   /**
00117   Executes a POST request on the URI uri
00118   @param uri : URI on which to execute the request
00119   @param dataOut : a HTTPData instance that contains the data that will be posted
00120   @param pDataIn : pointer to an HTTPData instance that will collect the data returned by the request, can be NULL
00121   Blocks until completion
00122   */
00123   HTTPResult post(const char* uri, const HTTPData& dataOut, HTTPData* pDataIn); //Blocking
00124   
00125   ///Executes a POST Request (non blocking)
00126   /**
00127   Executes a POST request on the URI uri
00128   @param uri : URI on which to execute the request
00129   @param dataOut : a HTTPData instance that contains the data that will be posted
00130   @param pDataIn : pointer to an HTTPData instance that will collect the data returned by the request, can be NULL
00131   @param pMethod : callback function
00132   The function returns immediately and calls the callback on completion or error
00133   */
00134   HTTPResult post(const char* uri, const HTTPData& dataOut, HTTPData* pDataIn, void (*pMethod)(HTTPResult)); //Non blocking
00135   
00136   ///Executes a POST Request (non blocking)
00137   /**
00138   Executes a POST request on the URI uri
00139   @param uri : URI on which to execute the request
00140   @param dataOut : a HTTPData instance that contains the data that will be posted
00141   @param pDataIn : pointer to an HTTPData instance that will collect the data returned by the request, can be NULL
00142   @param pItem : instance of class on which to execute the callback method
00143   @param pMethod : callback method
00144   The function returns immediately and calls the callback on completion or error
00145   */
00146   template<class T> 
00147   HTTPResult post(const char* uri, const HTTPData& dataOut, HTTPData* pDataIn, T* pItem, void (T::*pMethod)(HTTPResult)) //Non blocking  
00148   {
00149     setOnResult(pItem, pMethod);
00150     doPost(uri, dataOut, pDataIn);
00151     return HTTP_PROCESSING;
00152   }
00153 
00154   ///Executes a GET Request (non blocking)
00155   /**
00156   Executes a GET request on the URI uri
00157   @param uri : URI on which to execute the request
00158   @param pDataIn : pointer to an HTTPData instance that will collect the data returned by the request, can be NULL
00159   The function returns immediately and calls the previously set callback on completion or error
00160   */  
00161   void doGet(const char* uri, HTTPData* pDataIn);  
00162   
00163   ///Executes a POST Request (non blocking)
00164   /**
00165   Executes a POST request on the URI uri
00166   @param uri : URI on which to execute the request
00167   @param dataOut : a HTTPData instance that contains the data that will be posted
00168   @param pDataIn : pointer to an HTTPData instance that will collect the data returned by the request, can be NULL
00169   @param pMethod : callback function
00170   The function returns immediately and calls the previously set callback on completion or error
00171   */
00172   void doPost(const char* uri, const HTTPData& dataOut, HTTPData* pDataIn); 
00173   
00174   ///Setups the result callback
00175   /**
00176   @param pMethod : callback function
00177   */
00178   void setOnResult( void (*pMethod)(HTTPResult) );
00179   
00180   ///Setups the result callback
00181   /**
00182   @param pItem : instance of class on which to execute the callback method
00183   @param pMethod : callback method
00184   */
00185   class CDummy;
00186   template<class T> 
00187   void setOnResult( T* pItem, void (T::*pMethod)(HTTPResult) )
00188   {
00189     m_pCb = NULL;
00190     m_pCbItem = (CDummy*) pItem;
00191     m_pCbMeth = (void (CDummy::*)(HTTPResult)) pMethod;
00192   }
00193 
00194   ///Setups timeout
00195   /**
00196   @param ms : time of connection inactivity in ms after which the request should timeout
00197   */
00198   void setTimeout(int ms);
00199   
00200   virtual void poll(); //Called by NetServices
00201   
00202   ///Gets last request's HTTP response code
00203   /**
00204   @return The HTTP response code of the last request
00205   */
00206   int getHTTPResponseCode();
00207   
00208   ///Sets a specific request header
00209   void setRequestHeader(const string& header, const string& value);
00210   
00211   ///Gets a response header
00212   string& getResponseHeader(const string& header);
00213   
00214   ///Clears request headers
00215   void resetRequestHeaders();
00216   
00217   
00218   ///Setups a proxy server to be used for requests
00219   /**
00220   @param proxy_url : HTTP proxy string (e.g. proxy.mycompany.com:3380)
00221                      port 8080 will be used if not specified
00222                      pass NULL to disable
00223   */
00224   void setProxy(const char* proxy_url);
00225   
00226 protected:
00227   void resetTimeout();
00228   
00229   void init();
00230   void close();
00231   
00232   void setup(const char* uri, HTTPData* pDataOut, HTTPData* pDataIn); //Setup request, make DNS Req if necessary
00233   void connect(); //Start Connection
00234   
00235   int  tryRead(); //Read data and try to feed output
00236   void readData(); //Data has been read
00237   void writeData(); //Data has been written & buf is free
00238   
00239   void onTCPSocketEvent(TCPSocketEvent e);
00240   void onDNSReply(DNSReply r);
00241   void onResult(HTTPResult r); //Called when exchange completed or on failure
00242   void onTimeout(); //Connection has timed out
00243   
00244 private:
00245   HTTPResult blockingProcess(); //Called in blocking mode, calls Net::poll() until return code is available
00246 
00247   bool readHeaders(); //Called first when receiving data
00248   bool writeHeaders(); //Called to create req
00249   int readLine(char* str, int maxLen, bool* pIncomplete = NULL);
00250   
00251   enum HTTP_METH
00252   {
00253     HTTP_GET,
00254     HTTP_POST,
00255     HTTP_HEAD
00256   };
00257   
00258   HTTP_METH m_meth;
00259   
00260   CDummy* m_pCbItem;
00261   void (CDummy::*m_pCbMeth)(HTTPResult);
00262   
00263   void (*m_pCb)(HTTPResult);
00264   
00265   TCPSocket* m_pTCPSocket;
00266   map<string, string> m_reqHeaders;
00267   map<string, string> m_respHeaders;
00268   
00269   Timer m_watchdog;
00270   int m_timeout;
00271   
00272   DNSRequest* m_pDnsReq;
00273   
00274   Host m_server; // server to connect to
00275   string m_path; // request path
00276   
00277   bool m_closed;
00278   bool m_proxy; // m_server is a proxy server
00279   
00280   enum HTTPStep
00281   {
00282    // HTTP_INIT,
00283     HTTP_WRITE_HEADERS,
00284     HTTP_WRITE_DATA,
00285     HTTP_READ_HEADERS,
00286     HTTP_READ_DATA,
00287     HTTP_READ_DATA_INCOMPLETE,
00288     HTTP_DONE,
00289     HTTP_CLOSED
00290   };
00291   
00292   HTTPStep m_state;
00293   
00294   HTTPData* m_pDataOut;
00295   HTTPData* m_pDataIn;
00296   
00297   bool m_dataChunked; //Data is encoded as chunks
00298   int m_dataPos; //Position in data
00299   int m_dataLen; //Data length
00300   char* m_buf;
00301   char* m_pBufRemaining; //Remaining
00302   int m_bufRemainingLen; //Data length in m_pBufRemaining
00303   
00304   int m_httpResponseCode;
00305   
00306   HTTPResult m_blockingResult; //Result if blocking mode
00307   
00308 };
00309 
00310 //Including data containers here for more convenience
00311 #include "data/HTTPFile.h"
00312 #include "data/HTTPStream.h"
00313 #include "data/HTTPText.h"
00314 #include "data/HTTPMap.h"
00315 
00316 #endif