Represents a single entry in contact list. More...

#include "iclentry.h"

Public Types
enum	Feature { FPermanentEntry = 0x0000, FSessionEntry = 0x0001, FMaskLongetivity = 0x0003, FSupportsRenames = 0x0020, FHasCustomChatWidget = 0x0040, FSupportsAuth = 0x0080, FSupportsGrouping = 0x0100, FSelfContact = 0x0200 }

enum	EntryType { EntryType::Chat, EntryType::MUC, EntryType::PrivateChat, EntryType::UnauthEntry }

Public Member Functions
virtual	~ICLEntry ()

virtual QObject *	GetQObject ()=0

virtual IAccount *	GetParentAccount () const =0

virtual ICLEntry *	GetParentCLEntry () const

QObject *	GetParentCLEntryObject () const

virtual Features	GetEntryFeatures () const =0

virtual EntryType	GetEntryType () const =0

virtual QString	GetEntryName () const =0

virtual void	SetEntryName (const QString &name)=0
	Sets the human-readable name of this entry. More...

virtual QString	GetEntryID () const =0
	Returns the ID of this entry. More...

virtual QString	GetHumanReadableID () const
	Returns the human-readable ID of this entry. More...

virtual QStringList	Groups () const =0
	Returns the list of human-readable names of the groups that this entry belongs to. More...

virtual void	SetGroups (const QStringList &groups)=0
	Sets the list of groups this item belongs to. More...

virtual QStringList	Variants () const =0
	Returns the list of destination variants. More...

virtual IMessage *	CreateMessage (IMessage::Type type, const QString &variant, const QString &body)=0
	Creates the message of the given type to the given variant. More...

virtual QList< IMessage * >	GetAllMessages () const =0
	Returns all already sent or received messages. More...

virtual void	PurgeMessages (const QDateTime &before)=0
	Purges messages before the given date. More...

virtual void	SetChatPartState (ChatPartState state, const QString &variant)=0
	Notifies about our chat participation state change. More...

virtual EntryStatus	GetStatus (const QString &variant=QString()) const =0
	Returns the current status of a variant of the item. More...

virtual void	ShowInfo ()=0
	Requests the entry to show dialog with info about it. More...

virtual QList< QAction * >	GetActions () const =0
	Returns the list of actions for the item. More...

virtual QMap< QString, QVariant >	GetClientInfo (const QString &variant) const =0
	Returns the client information for the given variant. More...

virtual void	MarkMsgsRead ()=0
	Called whenever new messages are read. More...

virtual void	ChatTabClosed ()=0
	Called by Azoth when the chat with the entry is closed. More...

virtual void	gotMessage (QObject *msg)=0
	This signal should be emitted whenever a new message is received. More...

virtual void	statusChanged (const EntryStatus &st, const QString &variant)=0
	This signal should be emitted whenever the status of a variant in this entry changes. More...

virtual void	availableVariantsChanged (const QStringList &newVars)=0
	This signal should be emitted whenever the list of available variants changes. More...

virtual void	nameChanged (const QString &name)=0
	This signal should be emitted whenever the entry changes name. More...

virtual void	groupsChanged (const QStringList &groups)=0
	This signal should be emitted whenever the entry's groups are changed. More...

virtual void	chatPartStateChanged (const ChatPartState &state, const QString &variant)=0
	This signal should be emitted whenever the chat participation state of this entry changes. More...

virtual void	permsChanged ()=0
	This signal should be emitted if it's a MUC participant and his role/affiliation changes. More...

virtual void	entryGenerallyChanged ()=0
	This signal should be emitted when the entry changes. More...

Detailed Description

Represents a single entry in contact list.

Everything that should go to the contact list should implement this interface: plain contacts, metacontacts, transports to other accounts in protocols like XMPP, and such.

In some protocol an entry can have several destinations, like resources in XMPP protocol. In this case, GetVariants() should return the up-to-date list of variants that this entry may have as destinations.

By default, entries are considered to be normal chat entries, and Azoth core would manage the chat widget (and, consequently, chat tabs) for such entries itself. Nevertheless, some entries may want to have custom behavior for their widgets or even have no widgets at all. In this case, they set FHasCustomChatWidget flag in GetEntryFeatures(). In this case Azoth core wouldn't care about their chat widgets at all. Instead, such entry would need to implement IMultiTabsWidget, for example, and the corresponding plugin would need to be a IMultiTabs.

This interface provides only more or less basic functionality. Advanced features, like drawing attention and such, are in IAdvancedCLEntry.

If the CL entry can have an avatar, it makes sense to implement the IHaveAvatars interface.

See also: IAdvancedCLEntry; IHaveAvatars

Definition at line 120 of file iclentry.h.

Member Enumeration Documentation

◆ EntryType

enum LC::Azoth::ICLEntry::EntryType

strong

Enumerator
Chat	This entry represents a standard chat.
MUC	This entry represents a multi-user chatroom.
PrivateChat	This entry represents a private conversation in a multi-user chatroom.
UnauthEntry	This entry represents an unauthorized user that has requested authorization.

Definition at line 174 of file iclentry.h.

◆ Feature

enum LC::Azoth::ICLEntry::Feature

Represents the features that may be supported by a contant list entry.

Enumerator
FPermanentEntry	This entry is permanent and would appear in the next session too. It makes sense to save it to disk, for example, when shutting down. This also means that the entry has been accepted into some kind of contact list by the user.
FSessionEntry	This entry is not permanent and would cease existing after this login session.
FMaskLongetivity	Mask (0000011) for FPermanentEntry and FSessionEntry.
FSupportsRenames	This entry supports renaming, so calls to SetEntryName() are not in vain.
FHasCustomChatWidget	This entry has a custom chat widget.
FSupportsAuth	This entry supports auth manipulations. It makes sense to request, remove, give, etc auth. In this case the entry should also implement IAuthable.
FSupportsGrouping	This entry supports moving between different groups.
FSelfContact	This entry represents a self-contact, for example, in XMPP.

Definition at line 128 of file iclentry.h.

Constructor & Destructor Documentation

◆ ~ICLEntry()

virtual LC::Azoth::ICLEntry::~ICLEntry ( )

inlinevirtual

Definition at line 123 of file iclentry.h.

Member Function Documentation

◆ availableVariantsChanged()

virtual void LC::Azoth::ICLEntry::availableVariantsChanged ( const QStringList & newVars )

pure virtual

This signal should be emitted whenever the list of available variants changes.

Note: This function is expected to be a signal in subclasses.

Parameters

[out] newVars The list of new variants, as returned by GetVariants().

◆ chatPartStateChanged()

virtual void LC::Azoth::ICLEntry::chatPartStateChanged	(	const ChatPartState &	state,
		const QString &	variant
	)

pure virtual

This signal should be emitted whenever the chat participation state of this entry changes.

Note: This function is expected to be a signal in subclasses.

Parameters

[out]	state	The new chat state.
[out]	variant	The variant that this change applies to, may be a null string if not applicable.

◆ ChatTabClosed()

virtual void LC::Azoth::ICLEntry::ChatTabClosed ( )

pure virtual

Called by Azoth when the chat with the entry is closed.

◆ CreateMessage()

virtual IMessage* LC::Azoth::ICLEntry::CreateMessage	(	IMessage::Type	type,
		const QString &	variant,
		const QString &	body
	)

pure virtual

Creates the message of the given type to the given variant.

Variant is a string from the list returned by Variants(). If a different string is passed, particularly, a null one, the implementation must choose the best variant itself: for example, the resource with the highest priority in XMPP.

No message should be sent as result of CreateMessage(). Instead, one would later call IMessage::Send() on the returned message.

Parameters

[in]	type	The type of the message.
[in]	variant	The variant to send to.
[in]	body	Message boxy.

Returns: The prepared message.

See also: Variants()

◆ entryGenerallyChanged()

virtual void LC::Azoth::ICLEntry::entryGenerallyChanged ( )

pure virtual

This signal should be emitted when the entry changes.

This signal should be emitted only if no other signals apply (even those from IAdvancedCLEntry or such): it is some kind of a fall-back notification.

Note: This function is expected to be a signal in subclasses.

◆ GetActions()

virtual QList<QAction*> LC::Azoth::ICLEntry::GetActions ( ) const

pure virtual

Returns the list of actions for the item.

The list is showed, for example, when user calls the context menu on the item, or such. You may want to place actions like "Info", etc, in this list.

Returns: The list of actions.

◆ GetAllMessages()

virtual QList<IMessage*> LC::Azoth::ICLEntry::GetAllMessages ( ) const

pure virtual

Returns all already sent or received messages.

Returns the list of all messages sent or received during the session.

If the entry represents a MUC, all the messages in the returned list should have "IN" direction.

Returns: The list of messages.

◆ GetClientInfo()

virtual QMap<QString, QVariant> LC::Azoth::ICLEntry::GetClientInfo ( const QString & variant ) const

pure virtual

Returns the client information for the given variant.

The returned map should have the following keys:

client_type The corresponding value is a QString with a client ID.
client_name The corresponding value is a QString with human-readable name of the client.
client_version The corresponding value is a QString with human-readable version of the client.
priority The corresponding value is a int with the priority of the variant. The priority spans from -1024 to 1024, with negative values indicating that the message won't be delivered to this resource unless it was explicitly created to be targeted at this resource.

Parameters

[in] variant Variant for which to return the client info.

Returns: Human-readable client name of the variant.

◆ GetEntryFeatures()

virtual Features LC::Azoth::ICLEntry::GetEntryFeatures ( ) const

pure virtual

Returns the OR-ed combination of Feature flags that describes the features supported by this contact list entry.

Returns: The features supported by this entry.

◆ GetEntryID()

virtual QString LC::Azoth::ICLEntry::GetEntryID ( ) const

pure virtual

Returns the ID of this entry.

The ID must be unique among all entries and should not depend on the value returned by GetEntryName() (the human-readable name).

The main difference between this and GetHumanReadableID() is that GetEntryID() is used for distinguishing different items in the contact list (and there may be several items for one remote), while GetHumanReadableID() is used to distinguish different remotes between each other. Also, GetEntryID() should be unique globally (for example, it may contain ID of the account in it).

Returns: The unique and persistent ID of this entry.

See also: GetHumanReadableID()

Referenced by GetHumanReadableID().

Here is the caller graph for this function:

◆ GetEntryName()

virtual QString LC::Azoth::ICLEntry::GetEntryName ( ) const

pure virtual

Returns the human-readable name of this entry.

Returns: Human-readable name of this entry.

See also: SetEntryName()

◆ GetEntryType()

virtual EntryType LC::Azoth::ICLEntry::GetEntryType ( ) const

pure virtual

Returns the type of this entry.

Returns: The type of this entry.

◆ GetHumanReadableID()

virtual QString LC::Azoth::ICLEntry::GetHumanReadableID ( ) const

inlinevirtual

Returns the human-readable ID of this entry.

This function is used to obtain the human-readable identifier of this entry (for example, Jabber ID in case of XMPP), which may be not so unique as GetEntryID(). For example, if an entry exists in the roster, but it has also requested auth, there would be two entries with the same human-readable ID, but they would still be distinguished by the result of the GetEntryID() function.

Various operations like buddy searches (in protocols that support this feature like Skype or ICQ) are expected to operate on strings that are among possible return values of this function. Also, when initiating entry addition, the entry is expected to be identified by a similar string.

The default implementation returns GetEntryID() as an unicode string.

Returns: Human-readable persistent ID of this entry.

See also: GetEntryID()

Definition at line 308 of file iclentry.h.

References GetEntryID().

Here is the call graph for this function:

◆ GetParentAccount()

virtual IAccount* LC::Azoth::ICLEntry::GetParentAccount ( ) const

pure virtual

Returns the pointer to the parent account that this entry belongs to.

Returns: The parent account of this entry.

◆ GetParentCLEntry()

virtual ICLEntry* LC::Azoth::ICLEntry::GetParentCLEntry ( ) const

inlinevirtual

Returns the pointer to the parent CL entry, if any.

This currently only makes sense for private chat entries, thus private chat entries (those that are of type ETPrivateChat) should return their parent room CL entry (of type ETMUC).

If parent CL entry is not applicable, NULL should be returned.

The default implementation returns NULL.

Returns: Parent CL entry if applicable, NULL otherwise.

Definition at line 222 of file iclentry.h.

Referenced by GetParentCLEntryObject().

Here is the caller graph for this function:

◆ GetParentCLEntryObject()

QObject* LC::Azoth::ICLEntry::GetParentCLEntryObject ( ) const

inline

Definition at line 227 of file iclentry.h.

References GetParentCLEntry().

Here is the call graph for this function:

◆ GetQObject()

virtual QObject* LC::Azoth::ICLEntry::GetQObject ( )

pure virtual

Returns the entry as a QObject.

Returns: Contact list entry as QObject.

◆ GetStatus()

virtual EntryStatus LC::Azoth::ICLEntry::GetStatus ( const QString & variant = QString() ) const

pure virtual

Returns the current status of a variant of the item.

Since different variants may have different status, this function should return the proper status for the given variant. If no such variant exists, an empty status structure should be returned.

Parameters

[in] variant The variant to return status for or null string for most important variant.

Returns: The current status.

◆ gotMessage()

virtual void LC::Azoth::ICLEntry::gotMessage ( QObject * msg )

pure virtual

This signal should be emitted whenever a new message is received.

Note: This function is expected to be a signal in subclasses.

Parameters

[out] msg The message that was just received.

◆ Groups()

virtual QStringList LC::Azoth::ICLEntry::Groups ( ) const

pure virtual

Returns the list of human-readable names of the groups that this entry belongs to.

Returns: The list of groups of this item.

◆ groupsChanged()

virtual void LC::Azoth::ICLEntry::groupsChanged ( const QStringList & groups )

pure virtual

This signal should be emitted whenever the entry's groups are changed.

This signal should be emitted both if the list of groups changes as the result of our actions (particularly, the SetGroups() method) and as a result of some other event, for example, a roster push in XMPP.

Note: This function is expected to be a signal in subclasses.

Parameters

[out] groups The new list of groups of this entry.

◆ MarkMsgsRead()

virtual void LC::Azoth::ICLEntry::MarkMsgsRead ( )

pure virtual

Called whenever new messages are read.

This function is called by Azoth Core whenever any unread messages that could be present in this entry are read. For example, this may happen when user opens the chat tab with this entry.

Please note that this function is always called, even when there are no messages at all, for example.

◆ nameChanged()

virtual void LC::Azoth::ICLEntry::nameChanged ( const QString & name )

pure virtual

This signal should be emitted whenever the entry changes name.

This signal should be emitted both if the name of the entry changes as the result of our actions (particularly, the SetEntryName() method) and as a result of some other event, for example, a roster push in XMPP.

Note: This function is expected to be a signal in subclasses.

Parameters

[out] name The new name of this entry.

◆ permsChanged()

virtual void LC::Azoth::ICLEntry::permsChanged ( )

pure virtual

This signal should be emitted if it's a MUC participant and his role/affiliation changes.

Note: This function is expected to be a signal in subclasses.

◆ PurgeMessages()

virtual void LC::Azoth::ICLEntry::PurgeMessages ( const QDateTime & before )

pure virtual

Purges messages before the given date.

This function should purge all the messages before the given date. After the call, the corresponding messages should not appear in the result of GetAllMessages() function. It's also suggested to remove them from any internal memory storage to conserve memory.

If before is an invalid date, this function should purge all messages.

Parameters

[in] before The date before which messages should be purged.

◆ SetChatPartState()

virtual void LC::Azoth::ICLEntry::SetChatPartState	(	ChatPartState	state,
		const QString &	variant
	)

pure virtual

Notifies about our chat participation state change.

If variant is a null string, a variant with the highest priority should be used.

Parameters

[in]	state	Our new chat participation state.
[in]	variant	Target variant.

◆ SetEntryName()

virtual void LC::Azoth::ICLEntry::SetEntryName ( const QString & name )

pure virtual

Sets the human-readable name of this entry.

The name is expected to be updated on the server immediately.

Parameters

[in] name The new human-readable name of this entry.

See also: GetEntryName()

◆ SetGroups()

virtual void LC::Azoth::ICLEntry::SetGroups ( const QStringList & groups )

pure virtual

Sets the list of groups this item belongs to.

If updating the list of groups is not applicable, this function should do nothing.

Parameters

[in] groups The new list of groups.

◆ ShowInfo()

virtual void LC::Azoth::ICLEntry::ShowInfo ( )

pure virtual

Requests the entry to show dialog with info about it.

◆ statusChanged()

virtual void LC::Azoth::ICLEntry::statusChanged	(	const EntryStatus &	st,
		const QString &	variant
	)

pure virtual

This signal should be emitted whenever the status of a variant in this entry changes.

Note: This function is expected to be a signal in subclasses.

Parameters

[out]	st	The new status of this entry.
[out]	variant	What variant is subject to change.

◆ Variants()

virtual QStringList LC::Azoth::ICLEntry::Variants ( ) const

pure virtual

Returns the list of destination variants.

For example, for an entry representing a contact in XMPP protocol variants would be the list of resources for the contact.

Strings in the list should not be null, though they may be empty. There should be no duplicates in returned list.

The strings in the returned list should be sorted in descending order according to importance. For example, for XMPP protocol, the first variant should be the resource with the highest priority.

Returns: The list of variants of this entry.

The documentation for this class was generated from the following file:

/home/d34df00d/leechcraft/src/plugins/azoth/interfaces/azoth/iclentry.h

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ EntryType

◆ Feature

Constructor & Destructor Documentation

◆ ~ICLEntry()

Member Function Documentation

◆ availableVariantsChanged()

◆ chatPartStateChanged()

◆ ChatTabClosed()

◆ CreateMessage()

◆ entryGenerallyChanged()

◆ GetActions()

◆ GetAllMessages()

◆ GetClientInfo()

◆ GetEntryFeatures()

◆ GetEntryID()

◆ GetEntryName()

◆ GetEntryType()

◆ GetHumanReadableID()

◆ GetParentAccount()

◆ GetParentCLEntry()

◆ GetParentCLEntryObject()

◆ GetQObject()

◆ GetStatus()

◆ gotMessage()

◆ Groups()

◆ groupsChanged()

◆ MarkMsgsRead()

◆ nameChanged()

◆ permsChanged()

◆ PurgeMessages()

◆ SetChatPartState()

◆ SetEntryName()

◆ SetGroups()

◆ ShowInfo()

◆ statusChanged()

◆ Variants()