HTTP Client library
Dependents: weather_LCD_display News_LCD_display TwitterExample_1 GeoLocation_LCD_Display ... more
Diff: LPC2368/services/http/client/HTTPClient.h
- Revision:
- 5:d0be6af2d1db
- Parent:
- 0:a828ace1f38d
diff -r 76ca2a4fa528 -r d0be6af2d1db LPC2368/services/http/client/HTTPClient.h --- a/LPC2368/services/http/client/HTTPClient.h Fri Jul 09 14:35:21 2010 +0000 +++ b/LPC2368/services/http/client/HTTPClient.h Thu Aug 05 15:09:46 2010 +0000 @@ -21,12 +21,16 @@ THE SOFTWARE. */ +/** \file +HTTP Client header file +*/ + #ifndef HTTP_CLIENT_H #define HTTP_CLIENT_H class HTTPData; -#include "if/net/net.h" +#include "core/net.h" #include "api/TCPSocket.h" #include "api/DNSRequest.h" #include "HTTPData.h" @@ -38,33 +42,68 @@ #include <map> using std::map; +///HTTP client results enum HTTPResult { - HTTP_OK, - HTTP_PROCESSING, - HTTP_PARSE, //URI Parse error - HTTP_DNS, //Could not resolve name - HTTP_PRTCL, //Protocol error - HTTP_NOTFOUND, //404 Error - HTTP_REFUSED, //403 Error - HTTP_ERROR, //xxx error - HTTP_TIMEOUT, //Connection timeout - HTTP_CONN //Connection error + HTTP_OK, ///<Success + HTTP_PROCESSING, ///<Processing + HTTP_PARSE, ///<URI Parse error + HTTP_DNS, ///<Could not resolve name + HTTP_PRTCL, ///<Protocol error + HTTP_NOTFOUND, ///<HTTP 404 Error + HTTP_REFUSED, ///<HTTP 403 Error + HTTP_ERROR, ///<HTTP xxx error + HTTP_TIMEOUT, ///<Connection timeout + HTTP_CONN ///<Connection error }; +#include "core/netservice.h" - +///A simple HTTP Client +/** +The HTTPClient is composed of: +- The actual client (HTTPClient) +- 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) +*/ class HTTPClient : protected NetService { public: + ///Instantiates the HTTP client HTTPClient(); virtual ~HTTPClient(); + ///Provides a basic authentification feature (Base64 encoded username and password) void basicAuth(const char* user, const char* password); //Basic Authentification //High Level setup functions + ///Executes a GET Request (blocking) + /** + Executes a GET request on the URI uri + @param uri : URI on which to execute the request + @param pDataIn : pointer to an HTTPData instance that will collect the data returned by the request, can be NULL + Blocks until completion + */ HTTPResult get(const char* uri, HTTPData* pDataIn); //Blocking + + ///Executes a GET Request (non blocking) + /** + Executes a GET request on the URI uri + @param uri : URI on which to execute the request + @param pDataIn : pointer to an HTTPData instance that will collect the data returned by the request, can be NULL + @param pMethod : callback function + The function returns immediately and calls the callback on completion or error + */ HTTPResult get(const char* uri, HTTPData* pDataIn, void (*pMethod)(HTTPResult)); //Non blocking + + ///Executes a GET Request (non blocking) + /** + Executes a GET request on the URI uri + @param uri : URI on which to execute the request + @param pDataIn : pointer to an HTTPData instance that will collect the data returned by the request, can be NULL + @param pItem : instance of class on which to execute the callback method + @param pMethod : callback method + The function returns immediately and calls the callback on completion or error + */ template<class T> HTTPResult get(const char* uri, HTTPData* pDataIn, T* pItem, void (T::*pMethod)(HTTPResult)) //Non blocking { @@ -73,8 +112,37 @@ return HTTP_PROCESSING; } + ///Executes a POST Request (blocking) + /** + Executes a POST request on the URI uri + @param uri : URI on which to execute the request + @param dataOut : a HTTPData instance that contains the data that will be posted + @param pDataIn : pointer to an HTTPData instance that will collect the data returned by the request, can be NULL + Blocks until completion + */ HTTPResult post(const char* uri, const HTTPData& dataOut, HTTPData* pDataIn); //Blocking + + ///Executes a POST Request (non blocking) + /** + Executes a POST request on the URI uri + @param uri : URI on which to execute the request + @param dataOut : a HTTPData instance that contains the data that will be posted + @param pDataIn : pointer to an HTTPData instance that will collect the data returned by the request, can be NULL + @param pMethod : callback function + The function returns immediately and calls the callback on completion or error + */ HTTPResult post(const char* uri, const HTTPData& dataOut, HTTPData* pDataIn, void (*pMethod)(HTTPResult)); //Non blocking + + ///Executes a POST Request (non blocking) + /** + Executes a POST request on the URI uri + @param uri : URI on which to execute the request + @param dataOut : a HTTPData instance that contains the data that will be posted + @param pDataIn : pointer to an HTTPData instance that will collect the data returned by the request, can be NULL + @param pItem : instance of class on which to execute the callback method + @param pMethod : callback method + The function returns immediately and calls the callback on completion or error + */ template<class T> HTTPResult post(const char* uri, const HTTPData& dataOut, HTTPData* pDataIn, T* pItem, void (T::*pMethod)(HTTPResult)) //Non blocking { @@ -82,28 +150,68 @@ doPost(uri, dataOut, pDataIn); return HTTP_PROCESSING; } + + ///Executes a GET Request (non blocking) + /** + Executes a GET request on the URI uri + @param uri : URI on which to execute the request + @param pDataIn : pointer to an HTTPData instance that will collect the data returned by the request, can be NULL + The function returns immediately and calls the previously set callback on completion or error + */ + void doGet(const char* uri, HTTPData* pDataIn); - void doGet(const char* uri, HTTPData* pDataIn); + ///Executes a POST Request (non blocking) + /** + Executes a POST request on the URI uri + @param uri : URI on which to execute the request + @param dataOut : a HTTPData instance that contains the data that will be posted + @param pDataIn : pointer to an HTTPData instance that will collect the data returned by the request, can be NULL + @param pMethod : callback function + The function returns immediately and calls the previously set callback on completion or error + */ void doPost(const char* uri, const HTTPData& dataOut, HTTPData* pDataIn); + ///Setups the result callback + /** + @param pMethod : callback function + */ void setOnResult( void (*pMethod)(HTTPResult) ); + + ///Setups the result callback + /** + @param pItem : instance of class on which to execute the callback method + @param pMethod : callback method + */ class CDummy; template<class T> - //Linker bug : Must be defined here :( void setOnResult( T* pItem, void (T::*pMethod)(HTTPResult) ) { m_pCb = NULL; m_pCbItem = (CDummy*) pItem; m_pCbMeth = (void (CDummy::*)(HTTPResult)) pMethod; } - + + ///Setups timeout + /** + @param ms : time of connection inactivity in ms after which the request should timeout + */ void setTimeout(int ms); virtual void poll(); //Called by NetServices + ///Gets last request's HTTP response code + /** + @return The HTTP response code of the last request + */ int getHTTPResponseCode(); + + ///Sets a specific request header void setRequestHeader(const string& header, const string& value); + + ///Gets a response header string& getResponseHeader(const string& header); + + ///Clears request headers void resetRequestHeaders(); protected: