[telepathy-qt4/master] ContactManager: Added some docs.
Andre Moreira Magalhaes (andrunko)
andre.magalhaes at collabora.co.uk
Wed Jul 22 11:40:17 PDT 2009
---
TelepathyQt4/contact-manager.cpp | 75 ++++++++++++++++++++++++++++++++++++++
1 files changed, 75 insertions(+), 0 deletions(-)
diff --git a/TelepathyQt4/contact-manager.cpp b/TelepathyQt4/contact-manager.cpp
index c07556c..9534564 100644
--- a/TelepathyQt4/contact-manager.cpp
+++ b/TelepathyQt4/contact-manager.cpp
@@ -158,11 +158,30 @@ Contacts ContactManager::allKnownContacts() const
return mPriv->allKnownContacts();
}
+/**
+ * Return a list of user-defined contact list groups names.
+ *
+ * This method requires Connection::FeatureRosterGroups to be enabled.
+ *
+ * \return List of user-defined contact list groups names.
+ */
QStringList ContactManager::allKnownGroups() const
{
return mPriv->contactListGroupsChannels.keys();
}
+/**
+ * Attempt to add an user-defined contact list group named \a group.
+ *
+ * On some protocols (e.g. XMPP) empty groups are not represented on the server,
+ * so disconnecting from the server and reconnecting might cause empty groups to
+ * vanish.
+ *
+ * \param group Group name.
+ * \return A pending operation which will return when an attempt has been made
+ * to add an user-defined contact list group.
+ * \sa groupAdded(), groupAddContacts()
+ */
PendingOperation *ContactManager::addGroup(const QString &group)
{
if (group.isEmpty() || group.trimmed().isEmpty()) {
@@ -174,6 +193,19 @@ PendingOperation *ContactManager::addGroup(const QString &group)
QStringList() << group);
}
+/**
+ * Attempt to remove an user-defined contact list group named \a group.
+ *
+ * User-defined contact list groups may only be deleted if the group is
+ * already empty.
+ *
+ * This method requires Connection::FeatureRosterGroups to be enabled.
+ *
+ * \param group Group name.
+ * \return A pending operation which will return when an attempt has been made
+ * to remove an user-defined contact list group.
+ * \sa groupRemoved(), groupRemoveContacts()
+ */
PendingOperation *ContactManager::removeGroup(const QString &group)
{
if (!mPriv->contactListGroupsChannels.contains(group)) {
@@ -185,6 +217,16 @@ PendingOperation *ContactManager::removeGroup(const QString &group)
return channel->requestClose();
}
+/**
+ * Return a list of user-defined contact list groups a given contact
+ * \a contact belongs.
+ *
+ * This method requires Connection::FeatureRosterGroups to be enabled.
+ *
+ * \param contact Contact to get the groups from.
+ * \return List of user-defined contact list groups names for a given contact.
+ * \sa groupContacts()
+ */
QStringList ContactManager::contactGroups(const ContactPtr &contact) const
{
if (!contact) {
@@ -207,6 +249,17 @@ QStringList ContactManager::contactGroups(const ContactPtr &contact) const
return result;
}
+/**
+ * Return a list of contacts on a given user-defined contact list group
+ * named \a group.
+ *
+ * This method requires Connection::FeatureRosterGroups to be enabled.
+ *
+ * \param group Group name.
+ * \return List of contacts on a user-defined contact list group, or an empty
+ * list if the group does not exist.
+ * \sa allKnownGroups(), contactGroups()
+ */
Contacts ContactManager::groupContacts(const QString &group) const
{
if (!mPriv->contactListGroupsChannels.contains(group)) {
@@ -217,6 +270,17 @@ Contacts ContactManager::groupContacts(const QString &group) const
return channel->groupContacts();
}
+/**
+ * Attempt to add the given \a contacts to the user-defined contact list
+ * group named \a group.
+ *
+ * This method requires Connection::FeatureRosterGroups to be enabled.
+ *
+ * \param group Group name.
+ * \param contacts Contacts to add.
+ * \return A pending operation which will return when an attempt has been made
+ * to add the contacts to the user-defined contact list group.
+ */
PendingOperation *ContactManager::groupAddContacts(const QString &group,
const QList<ContactPtr> &contacts)
{
@@ -229,6 +293,17 @@ PendingOperation *ContactManager::groupAddContacts(const QString &group,
return channel->groupAddContacts(contacts);
}
+/**
+ * Attempt to remove the given \a contacts from the user-defined contact list
+ * group named \a group.
+ *
+ * This method requires Connection::FeatureRosterGroups to be enabled.
+ *
+ * \param group Group name.
+ * \param contacts Contacts to remove.
+ * \return A pending operation which will return when an attempt has been made
+ * to remove the contacts from the user-defined contact list group.
+ */
PendingOperation *ContactManager::groupRemoveContacts(const QString &group,
const QList<ContactPtr> &contacts)
{
--
1.5.6.5
More information about the telepathy-commits
mailing list