Documenting and some clean-up
[situare] / src / situareservice / situareservice.h
index 605dfe9..a85127c 100644 (file)
 #define SITUARESERVICE_H
 
 #include <QObject>
-#include "../facebookservice/facebookcredentials.h"
+
 #include "../user/user.h"
 #include "imagefetcher.h"
 
-class QNetworkAccessManager;
+class NetworkAccessManager;
 class QNetworkReply;
 class QNetworkRequest;
-class QPointF;
+class GeoCoordinate;
 class QUrl;
 
 /**
@@ -74,20 +74,26 @@ public:
     *
     * @param coordinates coordinates to be translated
     */
-    void reverseGeo(const QPointF &coordinates);
+    void reverseGeo(const GeoCoordinate &coordinates);
 
     /**
     * @brief Updates location to the Situare server
     *
     * @param coordinates current cordinates
     * @param status message
-    * @param publish publish location on Facebook wall (true/false)
+    * @param publish publish location on Facebook wall
     */
-    void updateLocation(const QPointF &coordinates, const QString &status, const bool &publish);
+    void updateLocation(const GeoCoordinate &coordinates, const QString &status, const bool &publish);
 
 public slots:
 
     /**
+    * @brief Public slot, to clear user data
+    *
+    */
+    void clearUserData();
+
+    /**
     * @brief Public slot, which indicates when http request has been completed
     *
     * @param reply storage for http reply
@@ -95,13 +101,52 @@ public slots:
     void requestFinished(QNetworkReply *reply);
 
     /**
-    * @brief Public slot, which indicates when facebook credentials are ready
+      * @brief Update session data
+      *
+      * @param session New session data
+      */
+    void updateSession(const QString &session);
+
+private:
+
+    /**
+    * @brief Requests ImageFetcher if user/friend has a profile image
+    *        uses members: m_user and m_friendsList
     *
-    * @param credentials New credentials
+    * @param imageUrlList list of image urls
     */
-    void credentialsReady(const FacebookCredentials &credentials);
+    void addProfileImages(const QList<QUrl> &imageUrlList);
 
-private:
+    /**
+      * @brief Append access_token and other session data to the reques url
+      *
+      * @param[in,out] requestUrl Request URL with other request parameters and ending to &
+      */
+    void appendAccessToken(QString &requestUrl);
+
+    /**
+      * @brief Convert coordinate value in degrees (double) to string with enough precision
+      *
+      * @param degrees Coordinate value in degrees
+      * @returns Coordinate value as string
+      */
+    QString degreesToString(double degrees);
+
+    /**
+    * @brief Forms a http cookie
+    *
+    * @param apiKeyValue application key
+    * @param expiresValue session expire date&time from Facebook
+    * @param userValue user id from Facebook
+    * @param sessionKeyValue session key from Facebook
+    * @param sessionSecretValue session secret from Facebook
+    * @param signatureValue md5 generated signature
+    * @param localeValue used locale
+    * @return QString formed cookie
+    */
+    QString formCookie(const QString &apiKeyValue, QString expiresValue, QString userValue,
+                       QString sessionKeyValue, QString sessionSecretValue,
+                       const QString &signatureValue, const QString &localeValue);
 
     /**
     * @brief Forms a http url
@@ -111,17 +156,19 @@ private:
     * @param urlParameters optional parameters for url
     * @return QUrl formed url
     */
-    QUrl formUrl(const QString &baseUrl, const QString &phpScript, QString urlParameters = 0);
+    QUrl formUrl(const QString &baseUrl, const QString &phpScript,
+                 QString urlParameters = QString());
 
     /**
     * @brief Forms url parameters
     *
     * @param coordinates current coordinates
     * @param status optional status message
-    * @param publish optional publish location on Facebook wall (true/false)
+    * @param publish optional publish location on Facebook wall
     * @return QString
     */
-    QString formUrlParameters(const QPointF &coordinates, QString status = 0, QString publish = 0);
+    QString formUrlParameters(const GeoCoordinate &coordinates, QString status = QString(),
+                              bool publish = false);
 
     /**
     * @brief Parses user and friend data from JSON string
@@ -140,14 +187,24 @@ private:
     void sendRequest(const QUrl &url, const QString &cookieType, const QString &cookie);
 
     /**
-    * @brief Requests ImageFetcher if user/friend has a profile image
-    *        uses members: m_user and m_friendsList
-    *
-    */
-    void addProfileImages();
+      * @brief Build and send request
+      *
+      * Appends script pathname and parameters to the server base URL. Access token is appended and
+      * the request sent if the access token is available, otherwise the request is queued.
+      *
+      * @param script Requested script pathname
+      * @param parameters Hash containing parameter key/value pairs.
+      */
+    void buildRequest(const QString &script, const QHash<QString,QString> &parameters);
 
-private slots:
+    /**
+      * @brief Send request
+      *
+      * @param requestUrl Request URL containing also all parameters
+      */
+    void sendRequest(const QString &requestUrl);
 
+private slots:
     /**
     * @brief Slot for received images
     *
@@ -165,9 +222,10 @@ signals:
     /**
     * @brief Signals error
     *
-    * @param error error message
+    * @param context error context
+    * @param error error code
     */
-    void error(const QString &error);
+    void error(const int context, const int error);
 
     /**
     * @brief Signal for image fetching
@@ -177,6 +235,13 @@ signals:
     void fetchImage(const QUrl &url);
 
     /**
+    * @brief Signals when user's/friend's image is downloaded
+    *
+    * @param user Instance of user/friend
+    */
+    void imageReady(User *user);
+
+    /**
     * @brief Signals when address data is retrieved
     *
     * @param address Street address
@@ -203,16 +268,18 @@ signals:
 
 private:
 
-    FacebookCredentials m_credentials; ///< handle for FacebookCredentials
-    QList<QNetworkReply *> m_currentRequests; ///< List of current http requests
-    QNetworkAccessManager *m_networkManager; ///< Pointer to QNetworkAccessManager
-    ImageFetcher *m_imageFetcher; ///< Instance of the image fetcher
+    bool m_defaultImage;    ///< Indicates if some of the friends/user doesn't have a image
+
+    QList<QNetworkReply *> m_currentRequests;       ///< List of current http requests
+    QList<QString> m_requestsWaitingAccessToken;    ///< Requests waiting for access_token
+    QList<User *> m_friendsList;                    ///< List of friends(User)
+
+    QString m_session;                          ///< Session data
+
+    NetworkAccessManager *m_networkManager;     ///< Pointer to QNetworkAccessManager
 
-    User *m_user; ///< Pointer to User
-    QList<User *> m_friendsList; ///< List of friends(User)
-    int m_visited; ///< Indicates number of friends with profile images
-    int m_nbrOfImages; ///< Indicates number of friends whose profile images have been downloaded
-    bool m_defaultImage; ///< Indicates if some of the friends or the user does not have a profile image
+    ImageFetcher *m_imageFetcher;               ///< Instance of the image fetcher
+    User *m_user;                               ///< Pointer to User
 };
 
 #endif // SITUARESERVICE_H