Revision 7:d97a4fc01c86, committed 2012-04-19

Comitter:

donatien

Date:

Thu Apr 19 09:52:54 2012 +0000

Parent:

6:3d3824893be1

Commit message:

Documentation++

Changed in this revision

--- a/HTTPClient.h	Thu Apr 19 09:19:58 2012 +0000
+++ b/HTTPClient.h	Thu Apr 19 09:52:54 2012 +0000
@@ -52,8 +52,7 @@
   HTTP_CONN ///<Connection error
 };
 
-///A simple HTTP Client
-/**
+/**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)
@@ -61,7 +60,7 @@
 class HTTPClient
 {
 public:
-  ///Instantiates the HTTP client
+  ///Instantiate the HTTP client
   HTTPClient();
   ~HTTPClient();
   
@@ -76,43 +75,37 @@
 #endif
   
   //High Level setup functions
-  ///Executes a GET Request (blocking)
-  /**
-  Executes a GET request on the url url
+  /** Execute a GET request on the url
+  Blocks until completion
   @param url : url on which to execute the request
   @param pDataIn : pointer to an IHTTPDataIn instance that will collect the data returned by the request, can be NULL
   @param timeout waiting timeout in ms (osWaitForever for blocking function, not recommended)
-  @return 0 on success, NET error on failure
-  Blocks until completion
+  @return 0 on success, NET error (<0) on failure
   */
   int get(const char* url, IHTTPDataIn* pDataIn, uint32_t timeout = HTTP_CLIENT_DEFAULT_TIMEOUT); //Blocking
   
-  ///Executes a GET Request (blocking)
-  /**
-  Executes a GET request on the url url
+  /** Execute a GET request on the url
+  Blocks until completion
+  This is a helper to directly get a piece of text from a HTTP result
   @param url : url on which to execute the request
   @param result : pointer to a char array in which the result will be stored
   @param maxResultLen : length of the char array (including space for the NULL-terminating char)
   @param timeout waiting timeout in ms (osWaitForever for blocking function, not recommended)
   @return 0 on success, NET error on failure
-  Blocks until completion
   */
   int get(const char* url, char* result, size_t maxResultLen, uint32_t timeout = HTTP_CLIENT_DEFAULT_TIMEOUT); //Blocking
 
-  ///Executes a POST Request (blocking)
-  /**
-  Executes a POST request on the url url
+  /** Execute a POST request on the url
+  Blocks until completion
   @param url : url on which to execute the request
   @param dataOut : a IHTTPDataOut instance that contains the data that will be posted
   @param pDataIn : pointer to an IHTTPDataIn instance that will collect the data returned by the request, can be NULL
   @param timeout waiting timeout in ms (osWaitForever for blocking function, not recommended)
   @return 0 on success, NET error on failure
-  Blocks until completion
   */
   int post(const char* url, const IHTTPDataOut& dataOut, IHTTPDataIn* pDataIn, uint32_t timeout = HTTP_CLIENT_DEFAULT_TIMEOUT); //Blocking
   
-  ///Gets last request's HTTP response code
-  /**
+  /** Get last request's HTTP response code
   @return The HTTP response code of the last request
   */
   int getHTTPResponseCode();
@@ -136,10 +129,6 @@
 
   const char* m_basicAuthUser;
   const char* m_basicAuthPassword;
-/*
-  HTTPData* m_pDataOut;
-  HTTPData* m_pDataIn;
-*/
   int m_httpResponseCode;
 
   struct sockaddr_in m_serverAddr;

--- a/IHTTPData.h	Thu Apr 19 09:19:58 2012 +0000
+++ b/IHTTPData.h	Thu Apr 19 09:52:54 2012 +0000
@@ -24,33 +24,62 @@
 #ifndef IHTTPDATA_H
 #define IHTTPDATA_H
 
-class IHTTPDataOut //This is a simple interface for HTTP data storage (impl examples are Key/Value Pairs, File, etc...)
+///This is a simple interface for HTTP data storage (impl examples are Key/Value Pairs, File, etc...)
+class IHTTPDataOut
 {
 protected:
   friend class HTTPClient;
 
+  /** Read a piece of data to be transmitted
+   * @param buf Pointer to the buffer on which to copy the data
+   * @param len Length of the buffer
+   * @param pReadLen Pointer to the variable on which the actual copied data length will be stored
+   */
   virtual int read(char* buf, size_t len, size_t* pReadLen) = 0;
   
+  /** Get MIME type
+   * @param type Internet media type from Content-Type header
+   */
   virtual int getDataType(char* type, size_t maxTypeLen) = 0; //Internet media type for Content-Type header
   
-  virtual bool getIsChunked() = 0; //For Transfer-Encoding header
+  /** Determine whether the HTTP client should chunk the data
+   *  Used for Transfer-Encoding header
+   */
+  virtual bool getIsChunked() = 0;
   
-  virtual size_t getDataLen() = 0; //For Content-Length header
+  /** If the data is not chunked, get its size
+   *  Used for Content-Length header
+   */
+  virtual size_t getDataLen() = 0;
 
 };
 
-class IHTTPDataIn //This is a simple interface for HTTP data storage (impl examples are Key/Value Pairs, File, etc...)
+///This is a simple interface for HTTP data storage (impl examples are Key/Value Pairs, File, etc...)
+class IHTTPDataIn
 {
 protected:
   friend class HTTPClient;
 
+  /** Write a piece of data transmitted by the server
+   * @param buf Pointer to the buffer from which to copy the data
+   * @param len Length of the buffer
+   */
   virtual int write(const char* buf, size_t len) = 0;
 
-  virtual void setDataType(const char* type) = 0; //Internet media type from Content-Type header
+  /** Set MIME type
+   * @param type Internet media type from Content-Type header
+   */
+  virtual void setDataType(const char* type) = 0;
 
-  virtual void setIsChunked(bool chunked) = 0; //From Transfer-Encoding header
+  /** Determine whether the data is chunked
+   *  Recovered from Transfer-Encoding header
+   */
+  virtual void setIsChunked(bool chunked) = 0;
   
-  virtual void setDataLen(size_t len) = 0; //From Content-Length header, or if the transfer is chunked, next chunk length
+  /** If the data is not chunked, set its size
+   * From Content-Length header
+   */
+  virtual void setDataLen(size_t len) = 0;
 
 };
 

--- a/data/HTTPMap.h	Thu Apr 19 09:19:58 2012 +0000
+++ b/data/HTTPMap.h	Thu Apr 19 09:52:54 2012 +0000
@@ -29,6 +29,9 @@
 
 #define HTTPMAP_TABLE_SIZE 32
 
+/** Map of key/value pairs
+ * Used to transmit POST data using the application/x-www-form-urlencoded encoding
+ */
 class HTTPMap: public IHTTPDataOut
 {
 public:

--- a/data/HTTPText.h	Thu Apr 19 09:19:58 2012 +0000
+++ b/data/HTTPText.h	Thu Apr 19 09:52:54 2012 +0000
@@ -27,10 +27,20 @@
 
 #include "../IHTTPData.h"
 
+/** A data endopint to store text
+*/
 class HTTPText : public IHTTPDataIn, public IHTTPDataOut
 {
 public:
+  /** Create an HTTPText instance for output
+   * @param str String to be transmitted
+   */
   HTTPText(char* str);
+
+  /** Create an HTTPText instance for input
+   * @param str Buffer to store the incoming string
+   * @param size Size of the buffer
+   */
   HTTPText(char* str, size_t size);
 
 protected: