/**

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

 * Interface spefication for managing associations between various social contacts

 * 

 */

#ifndef SMFRELATIONMGR_H

#define SMFRELATIONMGR_H

#include <smfprovider.h>

#include <smfcontact.h>

#include <smfglobal.h>

// forward declaation

class SmfRelationMgrPrivate;

// implementaion constants

const int maxSmfRelationIdSize = 500;

const int maxSmfRelationItemSize = 1000;

const int maxRelationItems = 1000;

// persistent Id of a relation.

typedef QString SmfRelationId;

/**

 * One record of a contact in a relation. Index specifies their position in the relationship.

 */

class SMFCLIENT_EXPORT SmfRelationItem : public SmfContact

	{

public:

	SmfRelationItem(SmfProvider* provider=0);

public:

	SmfProvider getProvider() const;

	void setProvider(SmfProvider& provider);

	SmfContact getContact() const;

	void setContact(SmfContact& contact);

	quint32	getIndex() const;

	void setIndex(quint32 index);

private:

	SmfProvider m_provider;

	SmfContact  m_contact;

	quint32		 m_index;

	};

SMFCLIENT_EXPORT QDataStream &operator<<( QDataStream &aDataStream, 

	const SmfRelationItem &aRelnItem );

SMFCLIENT_EXPORT QDataStream &operator>>( QDataStream &aDataStream, 

		SmfRelationItem &aRelnItem);

/**

 * All remote profiles (e.g. facebook, twitter, flicker) for a particular

 * person (or entity) constitutes a relation. Relation Manager stores

 * these relations in persistent memory.

 *

 * Relations and Items can be visualized in rows and columns.

 * Each row is identified by a RelationId.

 * Each column is identified by index of that Item in the relation

 * Each Items holds necessary information for SmfProvider and SmfContact.

 * In the diagram below C1, C2... could be local or remote contacts, which means

 * that C1, C2 .. could be contacts from device-resident phonebook. For example, for contact C1,

 * items at index 1,2,3.. in this relationship denotes C1's id in Facebook, Twitter, flickr,... .

 *

 *                                  Relation Item           Relation Item          Relation Item      Relation Item        Relation Item

 *                                        Index1                  index2                  index3                  index4                  index5

 *                             _______________________________________________________________________

 *                             |                           |                             |                            |                          |                          |

 * RelationId 1         |           C1           |        Remote        |        Remote       |         Remote    |         Remote     |

 *                             |                           |        Contact        |        Contact       |         Contact     |         Contact     |

 *                             ------------------------------------------------------------------------------------------------------------------

 *                             |                           |                             |                           |                           |                          |

 * RelationId 2         |           C2           |        Remote        |        Remote       |                          |                          |

 *                             |                           |        Contact        |        Contact       |                          |                          |

 *                             -----------------------------------------------------------------------------------------------------------------

 *                             |                           |                             |                            |                          |                          |

 * RelationId 3         |          C3            |        Remote        |                            |                          |                          |

 *                             |                           |        Contact        |                            |                          |                          |

 *                             -----------------------------------------------------------------------------------------------------------------

 *                             |                           |                             |                           |                           |                          |

 * RelationId 4         |           C4           |        Remote        |        Remote       |                          |                          |

 *                             |                           |        Contact        |        Contact       |                          |                          |

 *                             -----------------------------------------------------------------------------------------------------------------

 *                             |                           |                             |                           |                           |                          |

 * RelationId 5         |           C5           |        Remote        |                           |                           |                          |

 *                             |                           |        Contact        |                           |                           |                          |

 *                             -----------------------------------------------------------------------------------------------------------------

 *

 * Items can be added (associated) to a given relation. So this is one-to-many

 * relationship. Typically no items be present in more than one relation.

 *

 * All functions are synchronous at this moment.

 */

class SMFCLIENT_EXPORT SmfRelationMgr : public QObject

	{

	Q_OBJECT

public:

	SmfRelationMgr(QObject* parent = 0);

	~SmfRelationMgr();

public slots:

	/** create a new relation. The contact provided is the first contact in this

	 * relation.

	 * Please note that contact should have valid Guid @ref QtMobility::QContactGuid

	 * (used by Smf to store the unique id of user from facebook, etc.) and valid Url

	 * @ref QtMobility::QContactUrl

	 *

	 * If the contact is already stored with ContactManager (e.g. contact exists in phonebook),

	 * then it would have QtMobility::QContactId properly filled with managerUri and localId.

	 * These two field would also be stored in SmfRelationMgr (for easily identifying the SmfContacts).

	 *

	 * After successful creation, a relationId would be returned. More and more SmfContacts can

	 * be added to this relation using this RelationId

	 */

	SmfRelationId create(SmfProvider *provider=NULL, SmfContact *contact=NULL);

	/** assign contact to a relation */

	SmfError associate( SmfRelationId& relation,

						const SmfContact* contact,

						SmfProvider* provider);

	/** remove contact from a relation */

	SmfError remove(SmfRelationId& relation,

					const SmfContact* contact);

	/** returns first relation item in the relation when exists, NULL otherwise */

	SmfRelationItem* searchById(const SmfRelationId& relation);

	/** returns relation Id for a given contacts if exists, NULL otherwise */

	SmfRelationId searchByContact( SmfContact contact);

	/** returns number of contacts in a relation*/

	uint count(SmfRelationId relation);

	/** contacts and their provider */

	SmfRelationItem* get(SmfRelationId& relation, quint32 index);

	/** list of contacts and their provider */

	QList<SmfRelationItem> getAll(SmfRelationId& relation);

	/** list of all relations */

	QList<SmfRelationId> getAllRelations();

	/** delete a particular relation*/

	SmfError Delete(SmfRelationId& relation);

private:

	SmfRelationMgrPrivate* m_private;	//private impl wrapper

	};

#endif // SMFRELATIONMGR_H