diff options
| -rw-r--r-- | TelepathyQt4/channel.cpp | 386 |
1 files changed, 245 insertions, 141 deletions
diff --git a/TelepathyQt4/channel.cpp b/TelepathyQt4/channel.cpp index 44aaa9ee..6fa20c9a 100644 --- a/TelepathyQt4/channel.cpp +++ b/TelepathyQt4/channel.cpp @@ -1254,31 +1254,38 @@ struct TELEPATHY_QT4_NO_EXPORT Channel::GroupMemberChangeDetails::Private : publ * \ingroup clientchannel * \headerfile TelepathyQt4/channel.h <TelepathyQt4/Channel> * - * Class opaquely storing information on a group membership change for a - * single member. + * \brief The Channel::GroupMemberChangeDetails class represents the details of a group membership + * change. * * Extended information is not always available; this will be reflected by * the return value of isValid(). */ /** - * \fn Channel::GroupMemberChangeDetails::GroupMemberChangeDetails() - * - * \internal + * Constructs a new invalid GroupMemberChangeDetails instance. */ Channel::GroupMemberChangeDetails::GroupMemberChangeDetails() { } +/** + * Copy constructor. + */ Channel::GroupMemberChangeDetails::GroupMemberChangeDetails(const GroupMemberChangeDetails &other) : mPriv(other.mPriv) { } +/** + * Class destructor. + */ Channel::GroupMemberChangeDetails::~GroupMemberChangeDetails() { } +/** + * Assigns all information (validity, details) from other to this. + */ Channel::GroupMemberChangeDetails &Channel::GroupMemberChangeDetails::operator=( const GroupMemberChangeDetails &other) { @@ -1287,25 +1294,31 @@ Channel::GroupMemberChangeDetails &Channel::GroupMemberChangeDetails::operator=( } /** - * \fn bool Channel::GroupMemberChangeDetails::isValid() const; + * \fn bool Channel::GroupMemberChangeDetails::isValid() const * - * Return whether or not this object actually contains valid - * information received from the service. If the returned value is - * false, the values returned by the other methods for this object are - * undefined. + * Return whether the details are valid (have actually been received from the service). * - * \return Whether the information stored in this object is valid. + * \return Validity of the details. */ +/** + * Return whether the details specify an actor. + * + * If present, actor() will return the contact object representing the person who made the change. + * + * \return Whether the actor is known. + * \sa actor() + */ bool Channel::GroupMemberChangeDetails::hasActor() const { return isValid() && !mPriv->actor.isNull(); } /** - * Return the contact requesting or causing the change. + * Return the contact object representing the person who made the change (actor), if known. * - * \return The handle of the contact. + * \return The actor contact, or a null contact object if the actor is unknown. + * \sa hasActor() */ ContactPtr Channel::GroupMemberChangeDetails::actor() const { @@ -1313,34 +1326,98 @@ ContactPtr Channel::GroupMemberChangeDetails::actor() const } /** - * \fn ChannelGroupChangeReason Channel::GroupMemberChangeDetails::reason() const + * \fn bool Channel::GroupMemberChangeDetails::hasReason() const + * + * Return whether the details specify the reason for the change. + * + * \return Whether the reason for the change is known. + * \sa reason() + */ + +/** + * \fn QString Channel::GroupMemberChangeDetails::reason() const + * + * Return the reason for the change, if known. + * + * \return The reason for the change, or an empty string if the reason is unknown. + * \sa hasReason() + */ + +/** + * \fn bool Channel::GroupMemberChangeDetails::hasMessage() const + * + * Return whether the details specify a human-readable message from the contact represented by + * actor() pertaining to the change. + * + * \return Whether the message is known. + * \sa message() + */ + +/** + * \fn QString Channel::GroupMemberChangeDetails::message() const + * + * Return a human-readable message from the contact represented by actor() pertaining to the change, + * if known. + * + * \return A message from the contact represented by actor() regarding the change, + * or an empty string if the message is unknown. + * \sa hasMessage() + */ + +/** + * \fn bool Channel::GroupMemberChangeDetails::hasError() const + * + * Return whether the details specify a D-Bus error describing the change. + * + * \return Whether a D-Bus error describing the change is known. + * \sa error() + */ + +/** + * \fn QString Channel::GroupMemberChangeDetails::error() const + * + * Return the D-Bus error describing the change, if known. * - * Return the reason for the change. + * The D-Bus error provides more specific information than the reason() and should be used if + * applicable. * - * \return The reason, as specified in #ChannelGroupChangeReason. + * \return A D-Bus error describing the change, or an empty string if the error is unknown. + * \sa hasError() */ /** - * \fn const QString &Channel::GroupMemberChangeDetails::message() const + * \fn bool Channel::GroupMemberChangeDetails::hasDebugMessage() const * - * Return a human-readable message from the contact represented by - * actor() pertaining to the change, or an empty string if there is no - * message. + * Return whether the details specify a debug message. * - * \return The message as a string. + * \return Whether a debug message is provided. + * \sa debugMessage() */ +/** + * \fn QString Channel::GroupMemberChangeDetails::debugMessage() const + * + * Return the debug message specified by the details, if any. + * + * The debug message is purely informational, offered for display for bug reporting purposes, and + * should not be attempted to be parsed. + * + * \return The debug message, or an empty string if there is none. + * \sa hasDebugMessage() + */ + +/** + * Return a map containing all details of the group members change. + * + * This is useful for accessing domain-specific additional details. + * + * \return A map containing all details of the group members change. + */ QVariantMap Channel::GroupMemberChangeDetails::allDetails() const { return isValid() ? mPriv->details : QVariantMap(); } -/** - * \fn Channel::GroupMemberChangeDetails::GroupMemberChangeDetails( - * const ContactPtr &actor, const QVariantMap &details) - * - * \internal - */ Channel::GroupMemberChangeDetails::GroupMemberChangeDetails(const ContactPtr &actor, const QVariantMap &details) : mPriv(new Private(actor, details)) @@ -1355,46 +1432,31 @@ Channel::GroupMemberChangeDetails::GroupMemberChangeDetails(const ContactPtr &ac * \brief The Channel class represents a Telepathy channel. * * All communication in the Telepathy framework is carried out via channel - * objects which are created and managed by connections. Specialized classes for - * some specific channel types such as StreamedMediaChannel, TextChannel, - * FileTransferChannel are provided. - * - * It adds the following features compared to using Client::ChannelInterface - * directly: - * <ul> - * <li>Life cycle tracking</li> - * <li>Getting the channel type, handle type, handle and interfaces - * automatically</li> - * <li>High-level methods for the - * Group/Conference/MergeableConference/Splittable interfaces</li> - * <li>A fake group implementation when handle type is HandleTypeContact</li> - * </ul> - * - * The remote object state accessor functions on this object (interfaces(), - * channelType(), targetHandleType(), targetHandle(), requested(), - * initiatorContact(), and so on) don't make any D-Bus calls; - * instead, they return/use values cached from a previous introspection run. The - * introspection process populates their values in the most efficient way - * possible based on what the service implements. Their return value is mostly - * undefined until the introspection process is completed, i.e. isReady() - * returns true. See the individual accessor descriptions for more details. - * - * Additionally, the state of the group interface on the remote object (if - * present) will be cached in the introspection process, and also tracked for - * any changes. - * - * To avoid unnecessary D-Bus traffic, some methods only return valid - * information after a specific feature has been enabled by calling - * becomeReady() with the desired set of features as an argument, and waiting - * for the resulting PendingOperation to finish. For instance, to retrieve the - * initial invitee contacts of a conference channel, it is necessary to call - * becomeReady() with Channel::FeatureConferenceInitialInviteeContacts included - * in the argument. - * The required features are documented by each method. - * - * Each channel is owned by a connection. If the Connection object becomes dead - * (as signaled by Connection::invalidated()), the Channel object will also get - * invalidated. + * objects. Specialized classes for some specific channel types such as + * StreamedMediaChannel, TextChannel, FileTransferChannel are provided. + * + * The remote object accessor functions on this object (channelType(), targetHandleType(), + * and so on) don't make any D-Bus calls; instead, they return/use + * values cached from a previous introspection run. The introspection process + * populates their values in the most efficient way possible based on what the + * service implements. + * + * To avoid unnecessary D-Bus traffic, some accessors only return valid + * information after specific features have been enabled. + * For instance, to retrieve the initial invitee contacts in a conference channel, + * it is necessary to enable the feature Channel::FeatureConferenceInitialInviteeContacts. + * See the individual methods descriptions for more details. + * + * Channel features can be enabled by constructing a ChannelFactory and enabling + * the desired features, and passing it to AccountManager, Account 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() with the additional + * features, and waiting for the resulting PendingOperation to finish. + * + * Each channel is owned by a connection. If the Connection object becomes invalidated + * the Channel object will also get invalidated. * * \section chan_usage_sec Usage * @@ -1489,8 +1551,8 @@ const Feature Channel::FeatureConferenceInitialInviteeContacts = Feature(QLatin1 * * \param connection Connection owning this channel, and specifying the * service. - * \param objectPath The object path of this channel. - * \param immutableProperties The immutable properties of this channel. + * \param objectPath The channel object path. + * \param immutableProperties The channel immutable properties. * \return A ChannelPtr object pointing to the newly created Channel object. */ ChannelPtr Channel::create(const ConnectionPtr &connection, @@ -1505,10 +1567,10 @@ ChannelPtr Channel::create(const ConnectionPtr &connection, * * \param connection Connection owning this channel, and specifying the * service. - * \param objectPath The object path of this channel. - * \param immutableProperties The immutable properties of this channel. + * \param objectPath The channel object path. + * \param immutableProperties The channel immutable properties. * \param coreFeature The core feature of the channel type. The corresponding introspectable should - * depend on Channel::FeatureCore. + * depend on Channel::FeatureCore. */ Channel::Channel(const ConnectionPtr &connection, const QString &objectPath, @@ -1532,8 +1594,6 @@ Channel::~Channel() /** * Return the connection owning this channel. * - * This method requires Channel::FeatureCore to be enabled. - * * \return The connection owning this channel. */ ConnectionPtr Channel::connection() const @@ -1632,11 +1692,12 @@ QString Channel::channelType() const /** * Return the type of the handle returned by targetHandle() as specified in - * HandleType. + * #HandleType. * * This method requires Channel::FeatureCore to be enabled. * * \return The type of the handle returned by targetHandle(). + * \sa targetHandle(), targetId() */ HandleType Channel::targetHandleType() const { @@ -1654,6 +1715,7 @@ HandleType Channel::targetHandleType() const * This method requires Channel::FeatureCore to be enabled. * * \return The handle, which is of the type targetHandleType() indicates. + * \sa targetHandleType(), targetId() */ uint Channel::targetHandle() const { @@ -1667,8 +1729,8 @@ uint Channel::targetHandle() const /** * Return the persistent unique ID of the remote party with which this channel communicates. * - * If targetHandleType() is HandleTypeContact, this will be the ID of the remote contact, and - * similarly the unique ID of the room when targetHandleType() is HandleTypeRoom. + * If targetHandleType() is #HandleTypeContact, this will be the ID of the remote contact, and + * similarly the unique ID of the room when targetHandleType() is #HandleTypeRoom. * * This is not necessarily the best identifier to display to the user, though. In particular, for * contacts, their alias should be displayed instead. It can be used for matching channels and UI @@ -1677,7 +1739,8 @@ uint Channel::targetHandle() const * * This method requires Channel::FeatureCore to be enabled. * - * \return The identifier, which is of the type targetHandleType() indicates. + * \return The identifier of the remote party with which this channel communicates. + * \sa targetHandle(), targetContact() */ QString Channel::targetId() const { @@ -1697,6 +1760,7 @@ QString Channel::targetId() const * This method requires Channel::FeatureCore to be enabled. * * \return Pointer to the target contact. + * \sa targetHandle(), targetId() */ ContactPtr Channel::targetContact() const { @@ -1733,7 +1797,7 @@ bool Channel::isRequested() const * This method requires Channel::FeatureCore to be enabled. * * \return The contact who initiated this channel, - * or a null ContactPtr object if it can't be retrieved. + * or a null contact pointer if it can't be retrieved. */ ContactPtr Channel::initiatorContact() const { @@ -1753,6 +1817,7 @@ ContactPtr Channel::initiatorContact() const * * \return A PendingOperation, which will emit PendingOperation::finished * when the call has finished. + * \sa requestLeave() */ PendingOperation *Channel::requestClose() { @@ -1877,23 +1942,23 @@ void Channel::PendingLeave::onCloseFinished(Tp::PendingOperation *op) /** * Start an asynchronous request to leave this channel as gracefully as possible. * - * If leaving any more gracefully is not possible, this will revert to the same as requestClose. In - * particular, this will be the case for channels with no Group interface - * (TP_QT4_IFACE_CHANNEL_INTERFACE_GROUP not in the list returned by interfaces()). + * If leaving any more gracefully is not possible, this will revert to the same as requestClose(). + * In particular, this will be the case for channels with no group interface + * (#TP_QT4_IFACE_CHANNEL_INTERFACE_GROUP not in the list returned by interfaces()). * * The returned PendingOperation object will signal the success or failure * of this request; under normal circumstances, it can be expected to * succeed. * * A message and a reason may be provided along with the request, which will be sent to the server - * if supported, which is indicated by ChannelGroupFlagMessageDepart and/or - * ChannelGroupFlagMessageReject. + * if supported, which is indicated by #ChannelGroupFlagMessageDepart and/or + * #ChannelGroupFlagMessageReject. * * Attempting to leave again when we have already left, either by our request or forcibly, will be a * no-op, with the returned PendingOperation immediately finishing successfully. * * \param message The message, which can be blank if desired. - * \param reason A reason for leaving. + * \param reason A reason for leaving. * \return A PendingOperation, which will emit PendingOperation::finished * when the call has finished. */ @@ -1933,21 +1998,21 @@ PendingOperation *Channel::requestLeave(const QString &message, ChannelGroupChan * Cached access to state of the group interface on the associated remote * object, if the interface is present. Almost all methods return undefined * values if the list returned by interfaces() doesn't include - * #TELEPATHY_INTERFACE_CHANNEL_INTERFACE_GROUP or if the object is not ready. + * #TP_QT4_IFACE_CHANNEL_INTERFACE_GROUP or if the object is not ready. * - * Some methods can be used when targetHandleType() == HandleTypeContact, such + * Some methods can be used when targetHandleType() == #HandleTypeContact, such * as groupFlags(), groupCanAddContacts(), groupCanRemoveContacts(), * groupSelfContact() and groupContacts(). * - * As the Group interface state can change freely during the lifetime of the + * As the group interface state can change freely during the lifetime of the * channel due to events like new contacts joining the group, the cached state * is automatically kept in sync with the remote object's state by hooking * to the change notification signals present in the D-Bus interface. * * As the cached value changes, change notification signals are emitted. * - * Signals are emitted to indicate that properties have changed, for - * groupMembersChanged(), groupSelfContactChanged(), etc. + * Signals such as groupMembersChanged(), groupSelfContactChanged(), etc., are emitted to + * indicate that properties have changed. * * Check the individual signals' descriptions for details. */ @@ -1958,6 +2023,8 @@ PendingOperation *Channel::requestLeave(const QString &message, ChannelGroupChan * Return a set of flags indicating the capabilities and behaviour of the * group on this channel. * + * Change notification is via the groupFlagsChanged() signal. + * * This method requires Channel::FeatureCore to be enabled. * * \return Bitfield combination of flags, as defined in #ChannelGroupFlags. @@ -1975,11 +2042,13 @@ ChannelGroupFlags Channel::groupFlags() const /** * Return whether contacts can be added or invited to this channel. * + * Change notification is via the groupCanAddContactsChanged() signal. + * * This method requires Channel::FeatureCore to be enabled. * * \return \c true if contacts can be added or invited to this channel, * \c false otherwise. - * \sa groupAddContacts() + * \sa groupFlags(), groupAddContacts() */ bool Channel::groupCanAddContacts() const { @@ -1997,7 +2066,7 @@ bool Channel::groupCanAddContacts() const * This method requires Channel::FeatureCore to be enabled. * * \return \c true if a message is expected, \c false otherwise. - * \sa groupAddContacts() + * \sa groupFlags(), groupAddContacts() */ bool Channel::groupCanAddContactsWithMessage() const { @@ -2015,7 +2084,7 @@ bool Channel::groupCanAddContactsWithMessage() const * This method requires Channel::FeatureCore to be enabled. * * \return \c true if a message is expected, \c false otherwise. - * \sa groupAddContacts() + * \sa groupFlags(), groupAddContacts() */ bool Channel::groupCanAcceptContactsWithMessage() const { @@ -2046,7 +2115,7 @@ bool Channel::groupCanAcceptContactsWithMessage() const * \param message A string message, which can be blank if desired. * \return A PendingOperation which will emit PendingOperation::finished * when the call has finished. - * \sa groupCanAddContacts() + * \sa groupCanAddContacts(), groupCanAddContactsWithMessage(), groupCanAcceptContactsWithMessage() */ PendingOperation *Channel::groupAddContacts(const QList<ContactPtr> &contacts, const QString &message) @@ -2091,10 +2160,12 @@ PendingOperation *Channel::groupAddContacts(const QList<ContactPtr> &contacts, * Return whether contacts in groupRemotePendingContacts() can be removed from * this channel (i.e. whether an invitation can be rescinded). * + * Change notification is via the groupCanRescindContactsChanged() signal. + * * This method requires Channel::FeatureCore to be enabled. * * \return \c true if contacts can be removed, \c false otherwise. - * \sa groupRemoveContacts() + * \sa groupFlags(), groupRemoveContacts() */ bool Channel::groupCanRescindContacts() const { @@ -2107,13 +2178,13 @@ bool Channel::groupCanRescindContacts() const /** * Return whether a message is expected when removing contacts who are in - * groupRemotePendingContacts() from this channel, i.e. rescinding an - * invitation. + * groupRemotePendingContacts() from this channel (i.e. rescinding an + * invitation). * * This method requires Channel::FeatureCore to be enabled. * * \return \c true if a message is expected, \c false otherwise. - * \sa groupRemoveContacts() + * \sa groupFlags(), groupRemoveContacts() */ bool Channel::groupCanRescindContactsWithMessage() const { @@ -2130,10 +2201,12 @@ bool Channel::groupCanRescindContactsWithMessage() const * Note that contacts in local pending lists, and the groupSelfContact(), can * always be removed from the channel. * + * Change notification is via the groupCanRemoveContactsChanged() signal. + * * This method requires Channel::FeatureCore to be enabled. * * \return \c true if contacts can be removed, \c false otherwise. - * \sa groupRemoveContacts() + * \sa groupFlags(), groupRemoveContacts() */ bool Channel::groupCanRemoveContacts() const { @@ -2151,7 +2224,7 @@ bool Channel::groupCanRemoveContacts() const * This method requires Channel::FeatureCore to be enabled. * * \return \c true if a message is expected, \c false otherwise. - * \sa groupRemoveContacts() + * \sa groupFlags(), groupRemoveContacts() */ bool Channel::groupCanRemoveContactsWithMessage() const { @@ -2164,13 +2237,13 @@ bool Channel::groupCanRemoveContactsWithMessage() const /** * Return whether a message is expected when removing contacts who are in - * groupLocalPendingContacts() from this channel, i.e. rejecting a request to - * join. + * groupLocalPendingContacts() from this channel (i.e. rejecting a request to + * join). * * This method requires Channel::FeatureCore to be enabled. * * \return \c true if a message is expected, \c false otherwise. - * \sa groupRemoveContacts() + * \sa groupFlags(), groupRemoveContacts() */ bool Channel::groupCanRejectContactsWithMessage() const { @@ -2183,10 +2256,10 @@ bool Channel::groupCanRejectContactsWithMessage() const /** * Return whether a message is expected when removing the groupSelfContact() - * from this channel, i.e. departing from the channel. + * from this channel (i.e. departing from the channel). * * \return \c true if a message is expected, \c false otherwise. - * \sa groupRemoveContacts() + * \sa groupFlags(), groupRemoveContacts() */ bool Channel::groupCanDepartWithMessage() const { @@ -2233,7 +2306,10 @@ bool Channel::groupCanDepartWithMessage() const * #ChannelGroupChangeReason * \return A PendingOperation which will emit PendingOperation::finished * when the call has finished. - * \sa groupCanRemoveContacts() + * \sa groupCanRemoveContacts(), groupCanRemoveContactsWithMessage(), + * groupCanRejectContactsWithMessage(), groupCanRescindContacts(), + * groupCanRescindContacts(), groupCanRescindContactsWithMessage(), + * groupCanDepartWithMessage() */ PendingOperation *Channel::groupRemoveContacts(const QList<ContactPtr> &contacts, const QString &message, ChannelGroupChangeReason reason) @@ -2281,9 +2357,12 @@ PendingOperation *Channel::groupRemoveContacts(const QList<ContactPtr> &contacts /** * Return the current contacts of the group. * + * Change notification is via the groupMembersChanged() signal. + * * This method requires Channel::FeatureCore to be enabled. * - * \return List of contact of the group. + * \return List of contacts of the group. + * \sa groupLocalPendingContacts(), groupRemotePendingContacts() */ Contacts Channel::groupContacts() const { @@ -2298,10 +2377,13 @@ Contacts Channel::groupContacts() const * Return the contacts currently waiting for local approval to join the * group. * + * Change notification is via the groupMembersChanged() signal. + * * This method requires Channel::FeatureCore to be enabled. * * \return List of contacts currently waiting for local approval to join the * group. + * \sa groupContacts(), groupRemotePendingContacts() */ Contacts Channel::groupLocalPendingContacts() const { @@ -2318,10 +2400,13 @@ Contacts Channel::groupLocalPendingContacts() const * Return the contacts currently waiting for remote approval to join the * group. * + * Change notification is via the groupMembersChanged() signal. + * * This method requires Channel::FeatureCore to be enabled. * * \return List of contacts currently waiting for remote approval to join the * group. + * \sa groupContacts(), groupLocalPendingContacts() */ Contacts Channel::groupRemotePendingContacts() const { @@ -2364,15 +2449,15 @@ Channel::GroupMemberChangeDetails Channel::groupLocalPendingContactChangeInfo( /** * Return information on the removal of the local user from the group. If * the user hasn't been removed from the group, an object for which - * GroupMemberChangeDetails::isValid() Return <code>false</code> is returned. + * GroupMemberChangeDetails::isValid() returns <code>false</code> is returned. * * This method should be called only after you've left the channel. * This is useful for getting the remove information after missing the * corresponding groupMembersChanged() signal, as the local user being - * removed usually causes the remote Channel to be closed. + * removed usually causes the remote channel to be closed. * * The returned information is not guaranteed to be correct if - * groupIsSelfHandleTracked() Return false and a self handle change has + * groupIsSelfHandleTracked() returns false and a self handle change has * occurred on the remote object. * * This method requires Channel::FeatureCore to be enabled. @@ -2400,13 +2485,12 @@ Channel::GroupMemberChangeDetails Channel::groupSelfContactRemoveInfo() const * Handle owner lookup is only available if: * <ul> * <li>The object is ready - * <li>The list returned by interfaces() contains - * #TELEPATHY_INTERFACE_CHANNEL_INTERFACE_GROUP</li> + * <li>The list returned by interfaces() contains #TP_QT4_IFACE_CHANNEL_INTERFACE_GROUP</li> * <li>The set of flags returned by groupFlags() contains - * GroupFlagProperties and GroupFlagChannelSpecificHandles</li> + * #GroupFlagProperties and #GroupFlagChannelSpecificHandles</li> * </ul> * - * If this function Return <code>false</code>, the return value of + * If this function returns \c false, the return value of * groupHandleOwners() is undefined and groupHandleOwnersChanged() will * never be emitted. * @@ -2439,6 +2523,8 @@ bool Channel::groupAreHandleOwnersAvailable() const * channel. Handles which are channel-specific, but for which the owner is * unknown, appear in this mapping with 0 as owner. * + * Change notification is via the groupHandleOwnersChanged() signal. + * * This method requires Channel::FeatureCore to be enabled. * * \return A mapping from group-specific handles to globally valid handles. @@ -2461,7 +2547,7 @@ HandleOwnerMap Channel::groupHandleOwners() const /** * Return whether the value returned by groupSelfContact() is guaranteed to - * stay synchronized with what groupInterface()->GetSelfHandle() would + * stay synchronized with what group interface SelfHandle property would * return. Older services not providing group properties don't necessarily * emit the SelfHandleChanged signal either, so self contact changes can't be * reliably tracked. @@ -2486,6 +2572,8 @@ bool Channel::groupIsSelfContactTracked() const * Return a Contact object representing the user in the group if at all possible, otherwise a * Contact object representing the user globally. * + * Change notification is via the groupSelfContactChanged() signal. + * * This method requires Channel::FeatureCore to be enabled. * * \return A contact object representing the user. @@ -2551,13 +2639,15 @@ PendingOperation *Channel::groupAddSelfHandle() ChannelPtr(this)); } +//@} + /** - * Return whether this channel implements the - * org.freedesktop.Telepathy.Channel.Interface.Conference interface. + * Return whether this channel implements the conference interface + * (#TP_QT4_IFACE_CHANNEL_INTERFACE_CONFERENCE is in the list returned by interfaces()). * * This method requires Channel::FeatureCore to be enabled. * - * \return \c true if the interface is supported, \c false otherwise. + * \return \c true if the conference interface is supported, \c false otherwise. */ bool Channel::isConference() const { @@ -2656,8 +2746,7 @@ QHash<uint, ChannelPtr> Channel::conferenceOriginalChannels() const } /** - * Return whether this channel implements the - * org.freedesktop.Telepathy.Channel.Interface.MergeableConference interface. + * Return whether this channel implements the mergeable conference interface. * * This method requires Channel::FeatureCore to be enabled. * @@ -2691,8 +2780,7 @@ PendingOperation *Channel::conferenceMergeChannel(const ChannelPtr &channel) } /** - * Return whether this channel implements the - * org.freedesktop.Telepathy.Channel.Interface.Splittable interface. + * Return whether this channel implements the splittable interface. * * This method requires Channel::FeatureCore to be enabled. * @@ -2705,7 +2793,7 @@ bool Channel::supportsConferenceSplitting() const } /** - * Request that this channel is removed from any Conference of which it is + * Request that this channel is removed from any conference of which it is * a part. * * This method requires Channel::FeatureCore to be enabled. @@ -2727,7 +2815,7 @@ PendingOperation *Channel::conferenceSplitChannel() /** * \fn void Channel::groupFlagsChanged(uint flags, uint added, uint removed) * - * Emitted when the value returned by groupFlags() changes. + * This signal is emitted when the value of groupFlags() changes. * * \param flags The value which would now be returned by groupFlags(). * \param added Flags added compared to the previous value. @@ -2735,6 +2823,33 @@ PendingOperation *Channel::conferenceSplitChannel() */ /** + * \fn void Channel::groupCanAddContactsChanged(bool canAddContacts) + * + * This signal is emitted when the value of groupCanAddContacts() changes. + * + * \param canAddContacts Whether a contact can be added to this channel. + * \sa groupCanAddContacts() + */ + +/** + * \fn void Channel::groupCanRemoveContactsChanged(bool canRemoveContacts) + * + * This signal is emitted when the value of groupCanRemoveContacts() changes. + * + * \param canRemoveContacts Whether a contact can be removed from this channel. + * \sa groupCanRemoveContacts() + */ + +/** + * \fn void Channel::groupCanRescindContactsChanged(bool canRescindContacts) + * + * This signal is emitted when the value of groupCanRescindContacts() changes. + * + * \param canRescindContacts Whether contact invitations can be rescinded. + * \sa groupCanRescindContacts() + */ + +/** * \fn void Channel::groupMembersChanged( * const Tp::Contacts &groupMembersAdded, * const Tp::Contacts &groupLocalPendingMembersAdded, @@ -2774,8 +2889,6 @@ PendingOperation *Channel::conferenceSplitChannel() * Emitted when the value returned by groupSelfContact() changes. */ -//@} - /** * \fn void Channel::conferenceChannelMerged(const Tp::ChannelPtr &channel); * @@ -2795,28 +2908,19 @@ PendingOperation *Channel::conferenceSplitChannel() */ /** - * \name Optional interface proxy factory - * - * Factory functions fabricating proxies for optional %Channel interfaces and - * interfaces for specific channel types. - */ - -//@{ - -/** - * Return the ChannelInterface for this Channel class. This method is - * protected since the convenience methods provided by this class should - * always be used instead of the interface by users of the class. + * Return the Client::ChannelInterface interface proxy object for this channel. + * This method is protected since the convenience methods provided by this + * class should generally be used instead of calling D-Bus methods + * directly. * - * \return A pointer to the existing ChannelInterface for this Channel + * \return A pointer to the existing Client::ChannelInterface object for this + * Account object. */ Client::ChannelInterface *Channel::baseInterface() const { return mPriv->baseInterface; } -//@} - void Channel::gotMainProperties(QDBusPendingCallWatcher *watcher) { QDBusPendingReply<QVariantMap> reply = *watcher; |