dbus-tubes: Update and improve the API documentation

4 files changed, 132 insertions, 168 deletions

diff --git a/TelepathyQt/dbus-tube-channel.cpp b/TelepathyQt/dbus-tube-channel.cpp
index 53fabff6..0a173923 100644
--- a/TelepathyQt/dbus-tube-channel.cpp
+++ b/TelepathyQt/dbus-tube-channel.cpp
@@ -1,7 +1,8 @@
-/*
+/**
  * This file is part of TelepathyQt
  *
- * Copyright (C) 2010 Collabora Ltd. <http://www.collabora.co.uk/>
+ * @copyright Copyright (C) 2010-2011 Collabora Ltd. <http://www.collabora.co.uk/>
+ * @license LGPL 2.1
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public
@@ -157,22 +158,25 @@ void DBusTubeChannel::Private::introspectDBusTube(DBusTubeChannel::Private *self
 
 /**
  * \class DBusTubeChannel
+<<<<<<< HEAD
  * \headerfile TelepathyQt/stream-tube-channel.h <TelepathyQt/DBusTubeChannel>
+=======
+ * \ingroup clientchannel
+ * \headerfile TelepathyQt4/dbus-tube-channel.h <TelepathyQt4/DBusTubeChannel>
+>>>>>>> 523c3c3... dbus-tubes: Update and improve the API documentation
+ *
+ * \brief The DBusTubeChannel class represents a Telepathy channel of type DBusTube.
  *
- * A class representing a DBus Tube
+ * It provides a private bus which can be used as a peer-to-peer connection in case of a
+ * Contact Channel, or as a full-fledged bus in case of a Room Channel.
  *
- * \c DBusTubeChannel is an high level wrapper for managing Telepathy interface
- * #TELEPATHY_INTERFACE_CHANNEL_TYPE_DBUS_TUBE.
- * It provides a private DBus connection, either peer-to-peer or between a group of contacts, which
- * can be used just like a standard DBus connection. As such, services exposed MUST adhere to the
- * DBus specification.
+ * DBusTubeChannel is an intermediate base class; OutgoingDBusTubeChannel and
+ * IncomingDBusTubeChannel are the specialized classes used for locally and remotely initiated
+ * tubes respectively.
  *
- * This class provides high level methods for managing both incoming and outgoing tubes - however,
- * you probably want to use one of its subclasses, #OutgoingDBusTubeChannel or
- * #IncomingDBusTubeChannel, which both provide higher level methods for accepting
- * or offering tubes.
+ * For more details, please refer to \telepathy_spec.
  *
- * For more details, please refer to Telepathy spec.
+ * See \ref async_model, \ref shared_ptr
  */
 
 // Features declaration and documentation
@@ -186,10 +190,11 @@ void DBusTubeChannel::Private::introspectDBusTube(DBusTubeChannel::Private *self
  */
 const Feature DBusTubeChannel::FeatureCore = Feature(QLatin1String(DBusTubeChannel::staticMetaObject.className()), 0);
 /**
- * Feature used in order to monitor connections to this tube.
- * Please note that this feature makes sense only in Group tubes.
+ * Feature used in order to monitor bus names in this DBus tube.
+ *
+ * See bus name monitoring specific methods' documentation for more details.
  *
- * %busNamesChanged will be emitted when the participants of this tube change
+ * \sa busNameAdded(), busNameRemoved()
  */
 const Feature DBusTubeChannel::FeatureBusNameMonitoring = Feature(QLatin1String(DBusTubeChannel::staticMetaObject.className()), 1);
 
@@ -239,7 +244,8 @@ DBusTubeChannel::~DBusTubeChannel()
 }
 
 /**
- * Returns the service name which will be used over the tube.
+ * Returns the service name which will be used over the tube. This should be a
+ * well-known and valid DBus service name, in the form "org.my.service".
  *
  * This method requires DBusTubeChannel::FeatureCore to be enabled.
  *
@@ -258,27 +264,21 @@ QString DBusTubeChannel::serviceName() const
 
 /**
  * Checks if this tube is capable to accept or offer a private bus which
- * will require credentials upon connection.
+ * will allow connections only from the current user
  *
- * When this capability is available and enabled, the connecting process must send a byte when
- * it first connects, which is not considered to be part of the data stream.
- * If the operating system uses sendmsg() with SCM_CREDS or SCM_CREDENTIALS to pass
- * credentials over sockets, the connecting process must do so if possible;
- * if not, it must still send the byte.
+ * This method is useful only if your appliance is really security-sensitive:
+ * in general, this restriction is always enabled by default on all tubes offered
+ * or accepted from Telepathy-Qt4, falling back to a general connection allowance
+ * if this feature is not available.
  *
- * The listening process will disconnect the connection unless it can determine
- * by OS-specific means that the connecting process has the same user ID as the listening process.
+ * If your application does not have specific needs regarding DBus credentials,
+ * you can trust Telepathy-Qt4 to do the right thing - in any case, the most secure
+ * method available will be used by default.
  *
  * This method requires DBusTubeChannel::FeatureCore to be enabled.
  *
- * \note It is strongly advised to call this method before attempting to call
- *       #IncomingDBusTubeChannel::acceptTube or
- *       #OutgoingDBusTubeChannel::offerTube requiring
- *       credentials to prevent failures, as the spec implies
- *       this feature is not compulsory for connection managers.
- *
  * \return Whether this DBus tube is capable to accept or offer a private bus
- *         requiring credentials for connecting to it.
+ *         restricting access to it to the current user only.
  *
  * \sa IncomingDBusTubeChannel::acceptTube
  * \sa OutgoingDBusTubeChannel::offerTube
@@ -302,6 +302,11 @@ bool DBusTubeChannel::supportsRestrictingToCurrentUser() const
  * been opened successfully: in case of failure or the tube being still pending, an empty QString will be
  * returned.
  *
+ * \note If you plan to use QtDBus for the DBus connection, please note you should always use
+ *       QDBusConnection::connectToPeer(), regardless of the fact this tube is a p2p or a group one.
+ *       The above function has been introduced in Qt 4.8, previous versions of Qt do not allow the use
+ *       of DBus Tubes through QtDBus.
+ *
  * \returns The address of the private bus opened by this tube
  */
 QString DBusTubeChannel::address() const
@@ -316,9 +321,11 @@ QString DBusTubeChannel::address() const
 }
 
 /**
- * This function returns all the known active connections since FeatureBusNameMonitoring has
- * been enabled. For this method to return all known connections, you need to make
- * FeatureBusNameMonitoring ready before accepting or offering the tube.
+ * This function returns all the known active bus names in this tube. It requires
+ * FeatureBusNameMonitoring to be activated; however, even a late activation of the
+ * feature will make this function return a full list of all the connected bus
+ * names, including the ones which appeared before the activation of the feature
+ * itself.
  *
  * This function will always return an empty hash in case the tube is p2p, even if
  * FeatureBusNameMonitoring has been activated.
@@ -461,15 +468,15 @@ void DBusTubeChannel::setAddress(const QString& address)
 
 // Signals documentation
 /**
- * \fn void DBusTubeChannel::busNamesChanged(const QHash< ContactPtr, QString > &added, const QList< ContactPtr > &removed)
+ * \fn void DBusTubeChannel::busNameAdded(const QString &busName, const Tp::ContactPtr &contact)
  *
- * Emitted when the participants of this tube change.
+ * Emitted when a new participant joins this tube.
  *
  * This signal will be emitted only if the tube is a group tube (not p2p), and if the
  * FeatureBusNameMonitoring feature has been enabled.
  *
- * \param added An hash containing the contacts who joined this tube, with their respective bus name.
- * \param removed A list containing the contacts who left this tube.
+ * \param busName The bus name of the new participant
+ * \param contact The ContactPtr identifying the participant
  */
 
 }
diff --git a/TelepathyQt/incoming-dbus-tube-channel.cpp b/TelepathyQt/incoming-dbus-tube-channel.cpp
index 84ba4d68..5bd775b9 100644
--- a/TelepathyQt/incoming-dbus-tube-channel.cpp
+++ b/TelepathyQt/incoming-dbus-tube-channel.cpp
@@ -1,7 +1,8 @@
-/*
+/**
  * This file is part of TelepathyQt
  *
- * Copyright (C) 2010 Collabora Ltd. <http://www.collabora.co.uk/>
+ * @copyright Copyright (C) 2010-2011 Collabora Ltd. <http://www.collabora.co.uk/>
+ * @license LGPL 2.1
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public
@@ -58,82 +59,28 @@ IncomingDBusTubeChannel::Private::~Private()
 
 /**
  * \class IncomingDBusTubeChannel
+ * \ingroup clientchannel
  * \headerfile TelepathyQt/incoming-dbus-tube-channel.h <TelepathyQt/IncomingDBusTubeChannel>
  *
- * An high level wrapper for managing an incoming DBus tube
- *
- * \c IncomingDBusTubeChannel is an high level wrapper for managing Telepathy interface
- * #TELEPATHY_INTERFACE_CHANNEL_TYPE_DBUS_TUBE.
- * In particular, this class is meant to be used as a comfortable way for accepting incoming requests.
- *
- * \section incoming_dbus_tube_usage_sec Usage
- *
- * \subsection incoming_dbus_tube_create_sec Obtaining an incoming DBus tube
- *
- * Whenever a contact invites you to open an incoming DBus tube, if you are registered
- * as a channel handler for the channel type #TELEPATHY_INTERFACE_CHANNEL_TYPE_DBUS_TUBE,
- * you will be notified of the offer and you will be able to handle the channel.
- * Please refer to the documentation of #AbstractClientHandler for more
- * details on channel handling.
- *
- * Supposing your channel handler has been created correctly, you would do:
- *
- * \code
- * void MyChannelManager::handleChannels(const Tp::MethodInvocationContextPtr<> &context,
- *                               const Tp::AccountPtr &account,
- *                               const Tp::ConnectionPtr &connection,
- *                               const QList<Tp::ChannelPtr> &channels,
- *                               const QList<Tp::ChannelRequestPtr> &requestsSatisfied,
- *                               const QDateTime &userActionTime,
- *                               const QVariantMap &handlerInfo)
- * {
- *     foreach(const Tp::ChannelPtr &channel, channels) {
- *         QVariantMap properties = channel->immutableProperties();
- *
- *         if (properties[TELEPATHY_INTERFACE_CHANNEL ".ChannelType"] ==
- *                        TELEPATHY_INTERFACE_CHANNEL_TYPE_DBUS_TUBE) {
- *
- *             // Handle the channel
- *             Tp::IncomingDBusTubeChannelPtr myTube =
- *                      Tp::IncomingDBusTubeChannelPtr::qObjectCast(channel);
- *
- *          }
- *     }
- *
- *     context->setFinished();
- * }
- * \endcode
- *
- * \subsection incoming_dbus_tube_accept_sec Accepting the tube
- *
- * Before being ready to accept the tube, we must be sure the required features on our object
- * are ready. In this case, we need to enable TubeChannel::FeatureTube and
- * DBusTubeChannel::FeatureCore.
- *
- * DBusTubeChannel features can be enabled by constructing a ChannelFactory and enabling the desired features,
- * and passing it to ChannelRequest or ClientRegistrar when creating them as appropriate. However,
- * if a particular feature is only ever used in a specific circumstance, such as an user opening
- * some settings dialog separate from the general view of the application, features can be later
- * enabled as needed by calling becomeReady().
+ * \brief The IncomingStreamTubeChannel class represents an incoming Telepathy channel
+ * of type StreamTube.
  *
- * Once your object is ready, you can use #acceptTube to accept the tube and create a brand
- * new private DBus connection.
+ * In particular, this class is meant to be used as a comfortable way for
+ * accepting incoming DBus tubes. Unless a different behavior is specified, tubes
+ * will be always accepted allowing connections just from the current user, unless this
+ * or one of the other ends do not support that. Unless your application has specific needs,
+ * you usually want to keep this behavior.
  *
- * The returned PendingDBusTubeConnection serves both for monitoring the state of the tube and for
- * obtaining, upon success, the address of the new connection.
- * When the operation finishes, you can do:
+ * Once a tube is successfully accepted and open (the PendingDBusTubeConnection returned from the
+ * accepting methods has finished), the application can connect to the DBus server, the address of which
+ * can be retrieved from PendingDBusTubeConnection::address().
  *
- * \code
- * void MyTubeReceiver::onDBusTubeAccepted(PendingDBusTubeConnection *op)
- * {
- *     if (op->isError()) {
- *        return;
- *     }
+ * \note If you plan to use QtDBus for the DBus connection, please note you should always use
+ *       QDBusConnection::connectToPeer(), regardless of the fact this tube is a p2p or a group one.
+ *       The above function has been introduced in Qt 4.8, previous versions of Qt do not allow the use
+ *       of DBus Tubes through QtDBus.
  *
- *     QString address = op->address();
- *     // Connect to the address
- * }
- * \endcode
+ * For more details, please refer to \telepathy_spec.
  *
  * See \ref async_model, \ref shared_ptr
  */
@@ -191,8 +138,18 @@ IncomingDBusTubeChannel::~IncomingDBusTubeChannel()
  *
  * This method requires DBusTubeChannel::FeatureCore to be enabled.
  *
- * \param requireCredentials Whether the server should require an SCM_CREDENTIALS message
- *                           upon connection.
+ * \param allowOtherUsers Whether the server should allow other users to connect to this tube more
+ *                        than just the current one. If your application has no specific needs, it is
+ *                        advisable not to modify the default value of this argument.
+ *
+ * \note If allowOtherUsers == false, but one of the ends does not support current user restriction,
+ *       the tube will be offered regardless, falling back to allowing any connection. If your
+ *       application requires strictly this condition to be enforced, you should check
+ *       DBusTubeChannel::supportsRestrictingToCurrentUser <b>before</b> accepting the tube,
+ *       and take action from there.
+ *       The tube is guaranteed either to be accepted with the desired
+ *       restriction or to fail the accept phase if supportsRestrictingToCurrentUser is true
+ *       and allowOtherUsers is false.
  *
  * \return A %PendingDBusTubeConnection which will finish as soon as the tube is ready to be used
  *         (hence in the Open state)
diff --git a/TelepathyQt/outgoing-dbus-tube-channel.cpp b/TelepathyQt/outgoing-dbus-tube-channel.cpp
index fd62ca4e..66d5cf7e 100644
--- a/TelepathyQt/outgoing-dbus-tube-channel.cpp
+++ b/TelepathyQt/outgoing-dbus-tube-channel.cpp
@@ -1,7 +1,8 @@
-/*
+/**
  * This file is part of TelepathyQt
  *
- * Copyright (C) 2010 Collabora Ltd. <http://www.collabora.co.uk/>
+ * @copyright Copyright (C) 2010-2011 Collabora Ltd. <http://www.collabora.co.uk/>
+ * @license LGPL 2.1
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public
@@ -53,54 +54,26 @@ OutgoingDBusTubeChannel::Private::~Private()
 
 /**
  * \class OutgoingDBusTubeChannel
+ * \ingroup clientchannel
  * \headerfile TelepathyQt/outgoing-dbus-tube-channel.h <TelepathyQt/OutgoingDBusTubeChannel>
  *
- * An high level wrapper for managing an outgoing DBus tube
- *
- * \c OutgoingDBusTubeChannel is an high level wrapper for managing Telepathy interface
- * #TELEPATHY_INTERFACE_CHANNEL_TYPE_DBUS_TUBE.
- * In particular, this class is meant to be used as a comfortable way for exposing new tubes.
- *
- * \section outgoing_dbus_tube_usage_sec Usage
- *
- * \subsection outgoing_dbus_tube_create_sec Creating an outgoing DBus tube
- *
- * The easiest way to create a DBus tube is through Account. One can
- * just use the Account convenience methods such as
- * Account::createDBusTube() to get a brand new DBus tube channel ready to be used.
- *
- * To create such a channel, it is required to pass Account::createDBusTube()
- * the contact identifier and the DBus service name which will be used over the tube.
- * For example:
+ * \brief The OutgoingDBusTubeChannel class represents an outgoing Telepathy channel
+ * of type DBusTube.
  *
- * \code
- * AccountPtr myaccount = getMyAccountSomewhere();
- * ContactPtr myfriend = getMyFriendSomewhereElse();
+ * Outgoing (locally initiated/requested) tubes are initially in the #TubeChannelStateNotOffered state.
+ * When offerTube is called, the connection manager takes care of instantiating a new DBus server,
+ * at which point the tube state becomes #TubeChannelStateRemotePending.
  *
- * PendingChannelRequest *tube = myaccount->createDBusTube(myfriend, "org.my.service");
- * \endcode
+ * If the target accepts the connection request, the state goes #TubeChannelStateOpen and both sides
+ * can start using the new private bus, the address of which can be retrieved from the completed
+ * PendingDBusTubeConnection or from this class.
  *
- * \subsection outgoing_dbus_tube_offer_sec Offering the tube
+ * \note If you plan to use QtDBus for the DBus connection, please note you should always use
+ *       QDBusConnection::connectToPeer(), regardless of the fact this tube is a p2p or a group one.
+ *       The above function has been introduced in Qt 4.8, previous versions of Qt do not allow the use
+ *       of DBus Tubes through QtDBus.
  *
- * Before being ready to offer the tube, we must be sure the required features on our object
- * are ready. In this case, we need to enable TubeChannel::FeatureTube
- * and DBusTubeChannel::FeatureCore.
- *
- * DBusTubeChannel features can be enabled by constructing a ChannelFactory and enabling the desired features,
- * and passing it to ChannelRequest or ClientRegistrar when creating them as appropriate. However,
- * if a particular feature is only ever used in a specific circumstance, such as an user opening
- * some settings dialog separate from the general view of the application, features can be later
- * enabled as needed by calling becomeReady().
- *
- * You can also enable DBusTubeChannel::FeatureBusNameMonitoring to monitor connections
- * to the tube.
- *
- * Once your object is ready, you can use offerTube to create a brand new DBus connection and offer
- * it over the tube.
- *
- * You can now monitor the returned operation to know when the tube will be ready.
- * It is guaranteed that when the operation finishes,
- * the tube will be already opened and ready to be used.
+ * For more details, please refer to \telepathy_spec.
  *
  * See \ref async_model, \ref shared_ptr
  */
@@ -154,11 +127,23 @@ OutgoingDBusTubeChannel::~OutgoingDBusTubeChannel()
  * The %PendingDBusTubeConnection returned by this method will be completed as soon as the tube is
  * opened and ready to be used.
  *
+ * This method requires DBusTubeChannel::FeatureCore to be enabled.
+ *
  * \param parameters A dictionary of arbitrary Parameters to send with the tube offer.
  *                   The other end will receive this QVariantMap in the parameters() method
- *                   of the corresponding IncomingStreamTubeChannel.
- * \param requireCredentials Whether the server should require an SCM_CREDENTIALS message
- *                           upon connection.
+ *                   of the corresponding IncomingDBusTubeChannel.
+ * \param allowOtherUsers Whether the server should allow other users to connect to this tube more
+ *                        than just the current one. If your application has no specific needs, it is
+ *                        advisable not to modify the default value of this argument.
+ *
+ * \note If allowOtherUsers == false, but one of the ends does not support current user restriction,
+ *       the tube will be offered regardless, falling back to allowing any connection. If your
+ *       application requires strictly this condition to be enforced, you should check
+ *       DBusTubeChannel::supportsRestrictingToCurrentUser <b>before</b> offering the tube,
+ *       and take action from there.
+ *       The tube is guaranteed either to be offered with the desired
+ *       restriction or to fail the accept phase if supportsRestrictingToCurrentUser is true
+ *       and allowOtherUsers is false.
  *
  * \returns A %PendingDBusTubeConnection which will finish as soon as the tube is ready to be used
  *          (hence in the Open state)
diff --git a/TelepathyQt/pending-dbus-tube-connection.cpp b/TelepathyQt/pending-dbus-tube-connection.cpp
index 182df196..42572720 100644
--- a/TelepathyQt/pending-dbus-tube-connection.cpp
+++ b/TelepathyQt/pending-dbus-tube-connection.cpp
@@ -1,7 +1,8 @@
-/*
+/**
  * This file is part of TelepathyQt
  *
- * Copyright (C) 2011 Collabora Ltd. <http://www.collabora.co.uk/>
+ * @copyright Copyright (C) 2010 Collabora Ltd. <http://www.collabora.co.uk/>
+ * @license LGPL 2.1
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public
@@ -58,6 +59,7 @@ PendingDBusTubeConnection::Private::~Private()
 
 /**
  * \class PendingDBusTubeConnection
+ * \ingroup clientchannel
  * \headerfile TelepathyQt4/pending-dbus-tube-connection.h <TelepathyQt4/PendingDBusTubeConnection>
  *
  * A pending operation for accepting or offering a DBus tube
@@ -117,6 +119,11 @@ PendingDBusTubeConnection::~PendingDBusTubeConnection()
  * been completed successfully: in case of failure or non-completion, an empty QString will be
  * returned.
  *
+ * \note If you plan to use QtDBus for the DBus connection, please note you should always use
+ *       QDBusConnection::connectToPeer(), regardless of the fact this tube is a p2p or a group one.
+ *       The above function has been introduced in Qt 4.8, previous versions of Qt do not allow the use
+ *       of DBus Tubes through QtDBus.
+ *
  * \returns The address of the opened DBus connection.
  */
 QString PendingDBusTubeConnection::address() const
@@ -125,14 +132,22 @@ QString PendingDBusTubeConnection::address() const
 }
 
 /**
- * Return whether sending a credential byte once connecting to the socket is required.
+ * Return whether this tube allows other users more than the current one to connect to the
+ * private bus created by the tube.
+ *
+ * Note that even if the tube was accepted or offered specifying not to allow other users, this
+ * method might still return true if one of the ends did not support such a restriction.
+ *
+ * In fact, if one of the ends does not support current user restriction,
+ * the tube will be offered regardless, falling back to allowing any connection. If your
+ * application requires strictly this condition to be enforced, you should check
+ * DBusTubeChannel::supportsRestrictingToCurrentUser <b>before</b> offering the tube,
+ * and take action from there.
  *
- * Note that if this method returns \c true, one should send a SCM_CREDS or SCM_CREDENTIALS
- * and the credentialByte() once connected. If SCM_CREDS or SCM_CREDENTIALS cannot be sent,
- * the credentialByte() should still be sent.
+ * This function, however, is guaranteed to return the same value of the given allowOtherUsers
+ * parameter when accepting or offering a tube if supportsRestrictingToCurrentUser is true.
  *
- * \return \c true if sending credentials is required, \c false otherwise.
- * \sa credentialByte()
+ * \return \c true if any user is allow to connect, \c false otherwise.
  */
 bool PendingDBusTubeConnection::allowsOtherUsers() const
 {