example/clientapi/smf/inc/smfclient/smfcontactfetcher.h
changeset 2 86af6c333601
parent 1 4b1e636e8a71
--- a/example/clientapi/smf/inc/smfclient/smfcontactfetcher.h	Thu Mar 25 14:44:08 2010 +0530
+++ b/example/clientapi/smf/inc/smfclient/smfcontactfetcher.h	Tue Apr 06 16:35:37 2010 +0530
@@ -1,36 +1,39 @@
-/*
-* Copyright (c) 2010 Sasken Communication Technologies Ltd.
-* All rights reserved.
-* This component and the accompanying materials are made available
-* under the terms of the "{License}"
-* which accompanies  this distribution, and is available
-* at the URL "{LicenseUrl}".
-*
-* Initial Contributors:
-* Chandradeep Gandhi, Sasken Communication Technologies Ltd - Initial contribution
-*
-* Contributors:
-*
-* Description:
-* Interface spefication for list of contacts from a site
-*
-*/
+/**
+ * Copyright (c) 2010 Sasken Communication Technologies Ltd.
+ * All rights reserved.
+ * This component and the accompanying materials are made available
+ * under the terms of the "Eclipse Public License v1.0" 
+ * which accompanies  this distribution, and is available
+ * at the URL "http://www.eclipse.org/legal/epl-v10.html"
+ *
+ * Initial Contributors:
+ * Chandradeep Gandhi, Sasken Communication Technologies Ltd - Initial contribution
+ *
+ * Contributors:
+ * Manasij Roy, Nalina Hariharan
+ * 
+ * Description:
+ * The SmfEvent class represents an event
+ *
+ */
 
 #ifndef SMFCONTACTHETCHER_H
 #define SMFCONTACTHETCHER_H
 
 #include <QObject>
+#include "smfglobal.h"
 #include "smfprovider.h"
 #include "smfcontact.h"
-
+#include "smfplace.h"
 class SmfProvider; //base-class for service provider
 class SmfContact; //class for Contact in a social network
 class SmfGroup; //class for a group in social network
-class SmfContactList;
+typedef QList<SmfContact>  SmfContactList;
 
 //List of SmfGroup
 typedef QList<SmfGroup> SmfGroupList;
 /**
+ * @ingroup smf_client_group 
  * Interface to search for contacts/connections from a service provider. This class
  * provides basic functionality to allow applications to obtain list of
  * contacts or friends in a social networking service.
@@ -54,61 +57,88 @@
    * @param parent base provider info
    * @param contact Used for searching friends of the given contact
    * Seeing as this is a plug-in implementation, these will realistically
-   * be generated by SMF factory of some kind 
+   * be generated by SMF factory of some kind
    */
-  SmfContactFetcher(SmfProvider* baseProvider = 0, SmfContact* contact = 0);
+  SmfContactFetcher(SmfProvider* baseProvider);
+  SmfContactFetcher(SmfProvider* baseProvider, SmfContact* contact);
   ~SmfContactFetcher();
 
 public:
   /**
    * Get the friend listing asynchronously. The friendsListAvailable() signal
-   * is emitted with SmfContactList once data is arrived. 
+   * is emitted with SmfContactList once data is arrived.
+   * When the list is big user can specify the page number and per page item data.
+   * If not supplied by the user default values are used.
+   * @param pageNum Page number to download, SMF_FIRST_PAGE denotes fresh query.
+   * @param perPage Item per page, default is SMF_ITEMS_PER_PAGE
    */
-  virtual void friends() = 0; // list of contact objects
-  
+  bool friends(int pageNum=SMF_FIRST_PAGE,int perPage=SMF_ITEMS_PER_PAGE);
+
   /**
    * Get the list of followers asynchronously. The followersListAvailable() signal
-   * is emitted with SmfContactList once data is arrived. 
+   * is emitted with SmfContactList once data is arrived. Please note that some
+   * service may not support followers/fans - FALSE is returned if not supported.
+   * When the list is big user can specify the page number and per page item data.
+   * If not supplied by the user default values are used.
+   * @param pageNum Page number to download, SMF_FIRST_PAGE denotes fresh query.
+   * @param perPage Item per page, default is SMF_ITEMS_PER_PAGE
    */
-  virtual void followers() = 0; // list of contact objects
-  
+  bool followers(int pageNum=SMF_FIRST_PAGE,int perPage=SMF_ITEMS_PER_PAGE); // list of contact objects
+
   /**
    * Searches for a contact The searchContactFinished() signal
-   * is emitted with SmfContactList once data is arrived.
+   * is emitted with SmfContactList once data is arrived.
+   * When the list is big user can specify the page number and per page item data.
+   * If not supplied by the user default values are used.
+   * @param pageNum Page number to download, SMF_FIRST_PAGE denotes fresh query.
+   * @param perPage Item per page, default is SMF_ITEMS_PER_PAGE
    */
-  virtual void search(SmfContact* contact) = 0; // list of contact objects
-  
+  void search(SmfContact* contact,int pageNum=SMF_FIRST_PAGE,int perPage=SMF_ITEMS_PER_PAGE) ; // list of contact objects
+
+  /**
+   * Searches for a contacts (friends) who are near the user.
+   * Signal searchNearFinished() is emitted with SmfContactList once data is arrived.
+   * Proximity defines accuracy level
+   * When the list is big user can specify the page number and per page item data.
+   * If not supplied by the user default values are used.
+   * @param pageNum Page number to download, SMF_FIRST_PAGE denotes fresh query.
+   * @param perPage Item per page, default is SMF_ITEMS_PER_PAGE
+   */
+   bool searchNear(SmfPlace* location,SmfLocationSearchBoundary proximity,int pageNum=SMF_FIRST_PAGE,int perPage=SMF_ITEMS_PER_PAGE) ;
+
+
   /**
    * Get the list of groups. The groupListAvailable() signal
-   * is emitted with SmfGroupList once data is arrived. 
+   * is emitted with SmfGroupList once data is arrived. False might be returned
+   * if this service doesn't support any mode of grouping (very rare).
+   * When the list is big user can specify the page number and per page item data.
+   * If not supplied by the user default values are used.
+   * @param pageNum Page number to download, SMF_FIRST_PAGE denotes fresh query.
+   * @param perPage Item per page, default is SMF_ITEMS_PER_PAGE
    */
-  virtual void groups() = 0; // list of group objects
-  
+   bool groups(int pageNum=SMF_FIRST_PAGE,int perPage=SMF_ITEMS_PER_PAGE) ; // list of group objects
+
   /**
-   * Searches for Smf Contacts in an Smf group
+   * Searches for Smf Contacts in an Smf group.
+   * When the list is big user can specify the page number and per page item data.
+   * If not supplied by the user default values are used.
+   * @param pageNum Page number to download, SMF_FIRST_PAGE denotes fresh query.
+   * @param perPage Item per page, default is SMF_ITEMS_PER_PAGE
    * @param  group The group to be searcged in
-   * The nextDataPageAvailable() signal
-   * of SmfProvider is emitted with SmfContactList once data is arrived.
    */
-  virtual void searchInGroup(SmfGroup group) = 0; // list of contact objects
+   bool searchInGroup(SmfGroup group,int pageNum=SMF_FIRST_PAGE,int perPage=SMF_ITEMS_PER_PAGE) ; // list of contact objects
+
 
- 
   //APIs to get/set base provider info (SmfProvider)
-  
+
   /**
    * Gets the base provider info
    */
-  virtual SmfProvider* getProvider() = 0;
-  
-  /**
-   * Sets the base provider info
-   */
-  virtual void setProvider(SmfProvider* provider) = 0;
-
+   SmfProvider* getProvider() ;
 
 public slots:
 
-Q_SIGNALS:
+signals:
 
 	/**
 	 * This signal is emitted when a request to get friends is completed.
@@ -116,10 +146,10 @@
 	 * In that case this signal is emitted multiple times.
 	 *  @param list list of friends
 	 *  @param error error string
-	 *  @param pageNumber Page number
+	 *  @param resultPage Page number info
 	 *  @see friends()
 	 */
-	void friendsListAvailable(SmfContactList* list, QString error, int pageNumber=0); 
+	void friendsListAvailable(SmfContactList* list, QString error, SmfResultPage resultPage);
 
 	/**
 	 * This signal is emitted when a request to get followers is completed
@@ -127,45 +157,56 @@
 	 *  In that case this signal is emitted multiple times.
 	 *  @param list list of followers
 	 *  @param error error string
-	 *  @param pageNumber Page number
+	 *  @param resultPage Page number info
 	 *  @see followers()
 	 */
-	void followersListAvailable(SmfContactList* list, QString error, int pageNumber=0); 
-	
+	void followersListAvailable(SmfContactList* list, QString error, SmfResultPage resultPage);
+
 	/**
 	 * This signal is emitted when a request to get groups is completed
 	 * Note if number of groups is large, then it can download the list page by page
 	 *  In that case this signal is emitted multiple times.
 	 *  @param list list of groups
 	 *  @param error error string
-	 *  @param pageNumber Page number
+	 *  @param resultPage Page number info
 	 *  @see groups()
 	 */
-	void groupListAvailable(SmfGroupList* list, QString error, int pageNumber=0);
-	
+	void groupListAvailable(SmfGroupList* list, QString error, SmfResultPage resultPage);
+
 	/**
 	 * Emitted when search for a contact is finished.
 	 * Note if number of contacts in the search is large, then it can download the list page by page
 	 * In that case this signal is emitted multiple times.
 	 * @param list List of filtered contacts
-	 * @param pageNumber Page number
+	 * @param resultPage Page number info
 	 * @see search()
 	 */
-	void searchContactFinished(SmfContactList* list,QString error, int pageNumber=0);
-	
+	void searchContactFinished(SmfContactList* list,QString error, SmfResultPage resultPage);
+
+
+	/**
+	 * Emitted when search for contacts who are near a geographic location, is finished.
+	 * Note if number of contacts in the search is large, then it can download the list page by page
+	 * In that case this signal is emitted multiple times.
+	 * @param list List of filtered contacts
+	 * @param resultPage Page number info
+	 * @see search()
+	 */
+	void searchNearFinished(SmfContactList* list,QString error, SmfResultPage resultPage);
+
 	/**
 	 * Emitted when search for a contact in a group is finished
 	 * Note if number of contacts in the search is large, then it can download the list page by page
 	 * In that case this signal is emitted multiple times.
 	 * @param list list of filtered contacts
-	 * @param pageNumber Page number
+	 * @param resultPage Page number info
 	 * @see searchInGroup()
 	 */
-	void searchInGroupFinished(SmfContactList* list,QString error, int pageNumber=0);
+	void searchInGroupFinished(SmfContactList* list,QString error, SmfResultPage resultPage);
 
 private:
   SmfProvider* m_baseProvider;
 };
 
-SMF_GETSERVICES(SmfContactFetcher, "org.symbian.smf.client.contact.fetcher\0.2")
+SMF_SERVICE_NAME(SmfContactFetcher, "org.symbian.smf.client.contact.fetcher\0.2")
 #endif // SMFCONTACTHETCHER_H