--- 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