Removed useless file: curl_handle. The definition of curl_handle was,…

… fundamentally, useless.

Removed useless file: curl_message. Its definition and implementation has been moved into curl_multi as nested class with inline methods.
Added classes and methods documentation.
Use of unique_ptr to avoid explicit memory deallocation.
Fixed all the copy constructor and assignment operators.
Some small methods has been implemented as inline, to improve speed.
Other small bug fixes.

include/curl_easy.h

@@ -12,6 +12,7 @@
 #include <list>
 #include <algorithm>
 #include <curl/curl.h>
+#include <memory>
 #include <ostream>
 
 #include "curl_interface.h"
@@ -20,67 +21,178 @@
 using std::vector;
 using std::list;
 using std::for_each;
+using std::unique_ptr;
 using std::ostream;
+
 using curl::curl_pair;
 using curl::curl_interface;
 
 namespace curl  {
+    /**
+     * Easy interface is used to make requests and transfers. 
+     * You don't have to worry about freeing data or things like
+     * that. The class will do it for you.
+     */
     class curl_easy : public curl_interface<CURLcode> {
     public:
+        /**
+         * The default constructor will initialize the easy handler
+         * using libcurl functions.
+         */
         curl_easy();
+        /**
+         * This overloaded constructor allows users to specify a
+         * stream where they want to put the output of the libcurl
+         * operations.
+         */
         explicit curl_easy(ostream &);
+        /**
+         * This overloaded constructor allows users to specify a flag
+         * used to initialize libcurl environment.
+         */
         explicit curl_easy(const long);
+        /**
+         * This overloaded constructor allows to specify the environment
+         * initialization flags and a stream where to put libcurl output.
+         */
         curl_easy(const long, ostream &);
+        /**
+         * Copy constructor to handle pointer copy. Internally, it uses
+         * a function which duplicates the easy handler.
+         */
         curl_easy(const curl_easy &);
+        /**
+         * Assignment operator used to perform assignment between object
+         * of this class.
+         */
         curl_easy &operator=(const curl_easy &);
+        /**
+         * Override of equality operator. It has been overridden to check
+         * wheather two curl_easy object are equal.
+         */
         bool operator==(const curl_easy &) const;
+        /**
+         * The destructor will perform cleaning operations.
+         */
         ~curl_easy() noexcept;
+        /**
+         * Allows users to specify an option for the current easy handler,
+         * using a curl_pair object.
+         */
         template<typename T> void add(const curl_pair<CURLoption,T>);
+        /**
+         * Allows users to specify a vector of curl_pair options for the 
+         * current easy handler.
+         */
         template<typename T> void add(const vector<curl_pair<CURLoption,T>> &);
+        /**
+         * Allows users to specify a list of curl_pair options for the
+         * current easy handler.
+         */
         template<typename T> void add(const list<curl_pair<CURLoption,T>> &);
-        template<typename T> T *get_session_info(const CURLINFO, T *) const;
-        vector<string> get_session_info(const CURLINFO, struct curl_slist **) const;
+        /**
+         * This method allows users to request internal information from
+         * the curl session. I reccomend to read online documentation for
+         * further informations.
+         */
+        template<typename T> unique_ptr<T> get_info(const CURLINFO) const;
+        /**
+         * get_info overloaded method. It it used when the second argument is
+         * of struct_slist * type.
+         */
+        vector<string> get_info(const CURLINFO) const;
+        /**
+         * This method wraps the libcurl function that receives raw data from
+         * the established connection.
+         */
+        bool receive(void *, size_t, size_t *);
+        /**
+         * This method wraps the libcurl function that sends arbitrary data
+         * over the established connection.
+         */
+        void send(const void *, size_t, size_t *);
+        /**
+         * Using this function, you can explicitly mark a running connection 
+         * to get paused, and you can unpause a connection that was previously
+         * paused.
+         */
         void pause(const int);
+        /**
+         * This function converts the given input string to an URL encoded
+         * string and returns that as a new allocated string.
+         */
         void escape(string &);
+        /**
+         * This function converts the given URL encoded input string to a
+         * "plain string" and returns that in an allocated memory area. 
+         */
         void unescape(string &);
+        /**
+         * This fuctions performs all the operations that user has specified
+         * with the add methods.
+         */
         void perform();
+        /**
+         * Re-initializes all options previously set on a specified CURL handle
+         * to the default values. This puts back the handle to the same state as
+         * it was in when it was just created with.
+         */
         void reset() noexcept;
+        /**
+         * Simple getter method used to return the easy handle.
+         */
         CURL *get_curl() const;
     protected:
-        const string to_string(const CURLcode) const noexcept;
+        /**
+         * Utility function used to convert libcurl error code into
+         * error messages.
+         */
+        string to_string(const CURLcode) const noexcept;
     private:
         CURL *curl;
     };
 
-    // Implementation of addOption method
+    // Implementation of add method.
     template<typename T> void curl_easy::add(const curl_pair<CURLoption,T> pair) {
         const CURLcode code = curl_easy_setopt(this->curl,pair.first(),pair.second());
         if (code != CURLE_OK) {
             throw curl_error(this->to_string(code),__FUNCTION__);
         }
     }
 
-    // Implementation of overloaded method addOption
+    // Implementation of add overloaded method.
     template<typename T> void curl_easy::add(const vector<curl_pair<CURLoption,T>> &pairs) {
         for_each(pairs.begin(),pairs.end(),[this](curl_pair<CURLoption,T> option) {
             this->add(option);
         });
     }
 
-    // Implementation of overloaded method addOption
+    // Implementation of add overloaded method.
     template<typename T> void curl_easy::add(const list<curl_pair<CURLoption,T> > &pairs) {
         for_each(pairs.begin(),pairs.end(),[this](curl_pair<CURLoption,T> option) {
             this->add(option);
         });
     }
 
-    // Implementation of get_session_info method
-    template<typename T> T *curl_easy::get_session_info(const CURLINFO info, T *ptr_info) const {
-        const CURLcode code = curl_easy_getinfo(this->curl,info,ptr_info);
-        if (code != CURLE_OK && ptr_info) {
+    // Implementation of get_session_info method.
+    template<typename T> unique_ptr<T> curl_easy::get_info(const CURLINFO info) const {
+        // Use a unique_ptr to automatic destroy the memory reserved with new.
+        unique_ptr<T> ptr(new T);
+        const CURLcode code = curl_easy_getinfo(this->curl,info,ptr.get());
+        if (code != CURLE_OK) {
             throw curl_error(this->to_string(code),__FUNCTION__);
         }
-        return ptr_info;
+        return ptr;
+    }
+
+    // Implementation of get_curl method.
+    inline CURL *curl_easy::get_curl() const {
+        return this->curl;
+    }
+
+    // Implementation of to_string method.
+    inline string curl_easy::to_string(const CURLcode code) const noexcept {
+        return curl_easy_strerror(code);
     }
 }
 

include/curl_error.h

@@ -19,20 +19,55 @@ using std::endl;
 using std::string;
 using std::exception;
 using std::pair;
-using std::make_pair;
 using std::vector;
 
 namespace curl {
+    /**
+     * This class rapresent a custom exception for libcurl errors. 
+     * If a function throws an error, its name will be added to a
+     * vector (treated like a stack, because if I had used a stack,
+     * to print it, I should have to remove all the elements), so
+     * users can keep track of which method threw which exception.
+     */
     class curl_error : public exception {
     public:
+        /**
+         * This constructor is used to build the error.
+         */
         curl_error(const string, const string);
-        ~curl_error() throw() { /* ... nothing to delete */ }
+        /**
+         * The destructor, in this case, doesen't do anything.
+         */
+        ~curl_error() throw();
         using exception::what;
+        /**
+         * Override of exception's what method, used to returns
+         * the vector of errors.
+         */
         const vector<pair<string,string>> what();
-        const void print_traceback();
+        /**
+         * Simple method which prints the entire error stack.
+         */
+        void print_traceback() const;
     private:
+        /**
+         * The error container must be static or will be cleared
+         * when an exceptions is thrown.
+         */
         static vector<pair<string,string>> traceback;
     };
+
+    // Implementation of print_traceback
+    inline void curl_error::print_traceback() const {
+        for (vector<pair<string,string>>::const_iterator it = curl_error::traceback.begin(); it != curl_error::traceback.end(); ++it) {
+            cout<<"*** ERROR: "<<it->first<<" === FUNCTION: "<<it->second<<endl;
+        }
+    }
+
+    // Implementation of what method.
+    inline const vector<pair<string,string>> curl_error::what() {
+        return curl_error::traceback;
+    }
 }
 
-#endif /* defined(__curlcpp__curl_error__) */
+#endif /* defined(__curlcpp__curl_error__) */

include/curl_form.h

@@ -21,35 +21,100 @@ using std::bad_alloc;
 using curl::curl_pair;
 using curl::curl_error;
 
-// Simple class used to handle curl forms.
 namespace curl {
+    /**
+     * This class simplify the creation of a form. It wraps all the libcurl
+     * functions used to add content to a form and to destroy it.
+     */   
     class curl_form {
     public:
+        /**
+         * The default constructor will simply initialize the pointers to the
+         * list of form contents.
+         */
         curl_form();
+        /**
+         * The destructor will free the space allocated for the form content
+         * list.
+         */
         ~curl_form() noexcept;
+        /**
+         * Copy constructor used to perform a deep copy of the form content
+         * list. Without it we would be not able to perform copy. 
+         */
         curl_form(const curl_form &);
+        /**
+         * Assignment operator to implement assignment between two object
+         * of this class.
+         */
         curl_form &operator=(const curl_form &);
+        /**
+         * This method allows users to add content to a form, using the 
+         * curl_pair class.
+         */
         void add(const curl_pair<CURLformoption,string> &, const curl_pair<CURLformoption,string> &);
+        /**
+         * Overloaded add method.
+         */
         void add(const curl_pair<CURLformoption,string> &, const curl_pair<CURLformoption,string> &, const curl_pair<CURLformoption,string> &); 
+        /**
+         * Overloaded add method. It adds another curl_pair object to add more
+         * contents to the form contents list.
+         */
         void add(const curl_pair<CURLformoption,string> &, const curl_pair<CURLformoption,string> &, const curl_pair<CURLformoption,int> &); 
+        /**
+         * Overloaded add method. It adds another curl_pair object to add more
+         * contents to the form contents list.
+         */
         void add(const curl_pair<CURLformoption,string> &, const curl_pair<CURLformoption,int> &, const curl_pair<CURLformoption,string> &);
+        /**
+         * Overloaded add method. It adds another curl_pair object to add more
+         * contents to the form contents list.
+         */
         void add(const curl_pair<CURLformoption,string> &, const curl_pair<CURLformoption,string> &, const curl_pair<CURLformoption,int> &, const curl_pair<CURLformoption,string> &); 
+        /**
+         * Overloaded add method. This version is primarly used to upload multiple files. 
+         * You can pass a vector of filenames to upload them.
+         */
         void add(const curl_pair<CURLformoption,string> &, const vector<string> &);
+        /**
+         * Simple getter method used to return the head of the list.
+         */
         const struct curl_httppost *get() const;
     protected:
-        template<typename T> inline void is_null(const T *ptr) const;
+        /**
+         * This utility function is used to check if a given pointer, is null.
+         */
+        template<typename T> void is_null(const T *ptr) const;
+        /**
+         * This utility function is used to perform a deep copy of 
+         * the form contents list. We must traverse the new list to
+         * copy all the field in the left-object's list. This method
+         * puts the node in the tail. Indeed, libcurl keeps two 
+         * pointers to implement this list: a tail and a head.
+         */
         void copy_ptr(struct curl_httppost **, const struct curl_httppost *);
     private:
         struct curl_httppost *form_post;
         struct curl_httppost *last_ptr;
     };
+
+    // Implementation of copy constructor.
+    inline curl_form::curl_form(const curl_form &form) : form_post(nullptr), last_ptr(nullptr) {
+        *this = form;
+    }
 
     // Implementation of utility function to check if a pointer points to null.
-    template<typename T> void curl_form::is_null(const T *ptr) const {
+    template<typename T> inline void curl_form::is_null(const T *ptr) const {
         if (ptr == nullptr) {
             throw bad_alloc();
         }
     }
+
+    // Implementation of getter method that returns the list head.
+    inline const struct curl_httppost *curl_form::get() const {
+        return this->form_post;
+    }
 }
 
 #endif /* defined(__curlcpp__curl_form__) */