/**

 * 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 "smflocation.h"

#include "smfgroup.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

typedef QList<SmfContact>  SmfContactList;

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.

 * Note that to get the base provider info like service name, icon, description etc

 * use getProvider().

 * See also:

 * SmfProvider::serviceName(), SmfProvider::serviceIcon(), SmfProvider::description()

 *

 * All of the functionality described here should be implemented by a service

 * specific plug-in object.

 * Interface name:- org.symbian.smf.client.contact.fetcher

 */

class  SMFCLIENT_EXPORT SmfContactFetcher : public QObject

{

  Q_OBJECT

public:

  /**

   * Constructs the SmfContactFetcher.

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

   */

  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.

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

   */

  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.

   * 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

   */

  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(SmfLocation* 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. 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

   */

   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.

   * 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

   */

   bool searchInGroup(SmfGroup group,int pageNum=SMF_FIRST_PAGE,int perPage=SMF_ITEMS_PER_PAGE); // list of contact objects

   /**

    * Request for a custom operation.

    * @param operationId OperationId

    * @param customData Custom data to be sent

    * Note:-Interpretation of operationId and customData is upto the concerned

    * plugin and client application. service provider should provide some

    * serializing-deserializing utilities for these custom data

    */

   void customRequest(const int& operationId,QByteArray* customData);

  //APIs to get/set base provider info (SmfProvider)

  /**

   * Gets the base provider info

   */

   SmfProvider* getProvider() ;

signals:

	/**

	 * This signal is emitted when a request to get friends is completed.

	 * Note if number of friends is large, then it can download the list page by page.

	 * In that case this signal is emitted multiple times.

	 *  @param list list of friends

	 *  @param error error value

	 *  @param resultPage Page number info

	 *  @see friends()

	 */

	void friendsListAvailable(SmfContactList* list, SmfError error, SmfResultPage resultPage);

	/**

	 * This signal is emitted when a request to get followers is completed

	 *  Note if number of followers is large, then it can download the list page by page

	 *  In that case this signal is emitted multiple times.

	 *  @param list list of followers

	 *  @param error error value

	 *  @param resultPage Page number info

	 *  @see followers()

	 */

	void followersListAvailable(SmfContactList* list, SmfError 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 value

	 *  @param resultPage Page number info

	 *  @see groups()

	 */

	void groupListAvailable(SmfGroupList* list, SmfError 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 resultPage Page number info

	 * @see search()

	 */

	void searchContactFinished(SmfContactList* list,SmfError 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,SmfError 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 resultPage Page number info

	 * @see searchInGroup()

	 */

	void searchInGroupFinished(SmfContactList* list,SmfError error, SmfResultPage resultPage);

	/**

	 * Emitted when custom data is available

	 * @param operationId Requested operation id

	 * @param customData Custom data received, interpretation is not the responsibility of Smf

	 */

	void customDataAvailable(int operationId, QByteArray* customData);

	//so that private impl can directly call emit

	friend class SmfContactFetcherPrivate;

private:

  SmfProvider* m_baseProvider;

  SmfContact* m_frndContact; //used for searching

  //private impl wrapper

  SmfContactFetcherPrivate* m_private;

};

SMF_SERVICE_NAME(SmfContactFetcher, "org.symbian.smf.client.contact.fetcher\0.2")

#endif // SMFCONTACTHETCHER_H