Lots of (mostly) doxygen fixes/cleanup.

[simgear.git] / simgear / io / HTTPClient.hxx

diff --git a/simgear/io/HTTPClient.hxx b/simgear/io/HTTPClient.hxx
index 0e04cdc9347b5d4b148c45ec8a059982d08341cd..c726dc60e608cb61fa0edb34d13faab0ed62b1cb 100644 (file)
--- a/simgear/io/HTTPClient.hxx
+++ b/simgear/io/HTTPClient.hxx
@@ -1,9 +1,34 @@
+/**
+ * \file HTTPClient.hxx - simple HTTP client engine for SimHear
+ */
+
+// Written by James Turner
+//
+// Copyright (C) 2013  James Turner  <zakalawe@mac.com>
+//
+// This library is free software; you can redistribute it and/or
+// modify it under the terms of the GNU Library General Public
+// License as published by the Free Software Foundation; either
+// version 2 of the License, or (at your option) any later version.
+//
+// This library is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+// Library General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, write to the Free Software
+// Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+//
+
 #ifndef SG_HTTP_CLIENT_HXX
 #define SG_HTTP_CLIENT_HXX
 
-#include <map>
+#include <memory> // for std::auto_ptr
+#include <stdint.h> // for uint_64t
 
-#include <simgear/io/HTTPRequest.hxx>
+#include <simgear/io/HTTPFileRequest.hxx>
+#include <simgear/io/HTTPMemoryRequest.hxx>
 
 namespace simgear
 {
@@ -11,37 +36,78 @@ namespace simgear
 namespace HTTP
 {
 
+// forward decls
 class Connection;
-
+    
 class Client
 {
 public:
     Client();
+    ~Client();
     
-    void makeRequest(const Request_ptr& r);
+    void update(int waitTimeout = 0);
     
+    void makeRequest(const Request_ptr& r);
+
+    /**
+     * Download a resource and save it to a file.
+     *
+     * @param url       The resource to download
+     * @param filename  Path to the target file
+     * @param data      Data for POST request
+     */
+    FileRequestRef save( const std::string& url,
+                         const std::string& filename );
+
+    /**
+     * Request a resource and keep it in memory.
+     *
+     * @param url   The resource to download
+     */
+    MemoryRequestRef load(const std::string& url);
+
     void setUserAgent(const std::string& ua);
-    void setProxy(const std::string& proxy, const std::string& auth = "");
+    void setProxy(const std::string& proxy, int port, const std::string& auth = "");
+    
+    /**
+     * Specify the maximum permitted simultaneous connections
+     * (default value is 1)
+     */
+    void setMaxConnections(unsigned int maxCons);
     
-    const std::string& userAgent() const
-        { return _userAgent; }
+    const std::string& userAgent() const;
         
-    const std::string& proxyHost() const
-        { return _proxy; }
+    const std::string& proxyHost() const;
         
-    const std::string& proxyAuth() const
-        { return _proxyAuth; }
+    const std::string& proxyAuth() const;
+    
+    /**
+     * predicate, check if at least one connection is active, with at
+     * least one request active or queued.
+     */
+    bool hasActiveRequests() const;
+    
+    /**
+     * crude tracking of bytes-per-second transferred over the socket.
+     * suitable for user feedback and rough profiling, nothing more.
+     */
+    unsigned int transferRateBytesPerSec() const;
+    
+    /**
+     * total bytes downloaded by this HTTP client, for bandwidth usage
+     * monitoring
+     */
+    uint64_t totalBytesDownloaded() const;
 private:
     void requestFinished(Connection* con);
     
-    friend class Connection;
+    void receivedBytes(unsigned int count);
     
-    std::string _userAgent;
-    std::string _proxy;
-    std::string _proxyAuth;
+    friend class Connection;
+    friend class Request;
     
-// connections by host
-    std::map<std::string, Connection*> _connections;
+    class ClientPrivate;
+    std::auto_ptr<ClientPrivate> d;
 };
 
 } // of namespace HTTP