kopete/libkopete

Kopete::Account

Kopete::Account Class Reference

#include <kopeteaccount.h>

Inheritance diagram for Kopete::Account:

[legend]

List of all members.

Detailed Description

The Kopete::Account class handles one account.

Each protocol should subclass this class in its own custom accounts class. There are few pure virtual method that the protocol must implement. Examples are:

If your account requires a password, derive from PasswordedAccount instead of this class.

The accountId is an constant unique id, which represents the login. The myself() contact is one of the most important contacts, which represents the user tied to this account. You must create this contact in the contructor of your account and pass it to setMyself().

All account data is saved to KConfig. This includes the accountId, the autoconnect flag and the color. You can save more data using configGroup()

When you create a new account, you have to register it with the account manager by calling AccountManager::registerAccount.

Author:: Olivier Goffart <ogoffart@kde.org>

Definition at line 72 of file kopeteaccount.h.


Public Types
enum	AddMode { ChangeKABC = 0, DontChangeKABC = 1, Temporary = 2 }
enum	DisconnectReason { OtherClient = -4, BadPassword = -3, BadUserName = -2, InvalidHost = -1, Manual = 0, ConnectionReset = 1, Unknown = 99 }
Public Slots
virtual void	block (const QString &contactId)
virtual void	connect (const Kopete::OnlineStatus &initialStatus=OnlineStatus())=0
virtual void	disconnect ()=0
void	editAccount (QWidget *parent=0L)
virtual void	setOnlineStatus (const Kopete::OnlineStatus &status, const Kopete::StatusMessage &reason=Kopete::StatusMessage())=0
virtual void	setStatusMessage (const Kopete::StatusMessage &statusMessage)=0
virtual void	unblock (const QString &contactId)
Signals
void	accountDestroyed (const Kopete::Account *account)
void	colorChanged (const QColor &)
void	isConnectedChanged ()
Public Member Functions
	Account (Protocol *parent, const QString &accountID)
QPixmap	accountIcon (const int size=0) const
QString	accountId () const
QString	accountLabel () const
bool	addContact (const QString &contactId, MetaContact *parent, AddMode mode=DontChangeKABC)
MetaContact *	addContact (const QString &contactId, const QString &displayName=QString(), Group *group=0, AddMode mode=DontChangeKABC)
BlackLister *	blackLister ()
const QColor	color () const
KConfigGroup *	configGroup () const
const QHash< QString, Contact * > &	contacts ()
QString	customIcon () const
bool	excludeConnect () const
virtual void	fillActionMenu (KActionMenu *actionMenu)
virtual bool	hasCustomStatusMenu () const
Identity *	identity () const
bool	isAway () const
virtual bool	isBlocked (const QString &contactId)
bool	isConnected () const
Contact *	myself () const
uint	priority () const
Protocol *	protocol () const
void	registerContact (Contact *c)
virtual bool	removeAccount ()
void	setColor (const QColor &color)
void	setCustomIcon (const QString &)
void	setExcludeConnect (bool)
virtual bool	setIdentity (Kopete::Identity *ident)
void	setPriority (uint priority)
bool	suppressStatusNotification () const
	~Account ()
Protected Slots
virtual void	disconnected (Kopete::Account::DisconnectReason reason)
void	setAllContactsStatus (const Kopete::OnlineStatus &status)
Protected Member Functions
virtual bool	createContact (const QString &contactId, MetaContact *parentContact)=0
void	setAccountLabel (const QString &label)
void	setMyself (Contact *myself)
Properties
QPixmap	accountIcon
QString	accountId
QColor	color
bool	excludeConnect
bool	isAway
bool	isConnected
uint	priority
bool	suppressStatusNotification

Member Enumeration Documentation

enum Kopete::Account::AddMode

Describes what should be done when the contact is added to a metacontact.

See also:: addContact()

Enumerator:

ChangeKABC	The KDE Address book may be updated.
DontChangeKABC	The KDE Address book will not be changed.
Temporary	The contact will not be added on the contact list.

Definition at line 109 of file kopeteaccount.h.

enum Kopete::Account::DisconnectReason

Describes how the account was disconnected.

Manual means that the disconnection was done by the user and no reconnection will take place. Any other value will reconnect the account on disconnection. The case where the password is wrong will be handled differently.

See also:: disconnected

Enumerator:

OtherClient	connection went down because another client connected the same account
BadPassword	connection failed because password was incorrect
BadUserName	connection failed because user name was invalid / unknown
InvalidHost	connection failed because host is unreachable
Manual	the user disconnected normally
ConnectionReset	the connection was lost
Unknown	the reason for disconnection is unknown

Definition at line 95 of file kopeteaccount.h.

Constructor & Destructor Documentation

Kopete::Account::Account	(	Protocol *	parent,
		const QString &	accountID
	)

Parameters:

parent

the protocol for this account.

The account is a child object of the protocol, so it will be automatically deleted when the protocol is.

Parameters:

	accountID	the unique ID of this account.
	name	the name of this QObject.

Definition at line 96 of file kopeteaccount.cpp.

Kopete::Account::~Account ( )

Definition at line 113 of file kopeteaccount.cpp.

Member Function Documentation

void Kopete::Account::accountDestroyed ( const Kopete::Account * account ) [signal]

Emitted when the account is deleted.

Warning:: emitted in the Account destructor. It is not safe to call any functions on account.

QPixmap Kopete::Account::accountIcon ( const int size = 0 ) const

Get the icon for this account.

Generates an image of size size representing this account. The result is not cached.

Parameters:

size

the size of the icon. If the size is 0, the default size is used.

Returns:: the icon for this account, colored if needed

Definition at line 193 of file kopeteaccount.cpp.

QString Kopete::Account::accountId ( ) const

Returns:: the unique ID of this account used as the login

QString Kopete::Account::accountLabel ( ) const

Returns:: The label of this account, for the GUI

Definition at line 225 of file kopeteaccount.cpp.

bool Kopete::Account::addContact	(	const QString &	contactId,
		MetaContact *	parent,
		AddMode	mode = `DontChangeKABC`
	)

Create a new contact, adding it to an existing metacontact.

If a contact for this account with ID contactId is not already on the contact list, a new contact with that ID is created, and added to the metacontact parent.

Parameters:

	contactId	the Contact::contactId of the contact to create
	parent	the parent metacontact (must not be 0)
	mode	the mode used to add the contact. See addContact(const QString&,const QString&,Group*,AddMode) for details.

Returns:: true if creation of the contact succeeded or the contact was already in the list, false otherwise.

Definition at line 329 of file kopeteaccount.cpp.

Kopete::MetaContact * Kopete::Account::addContact	(	const QString &	contactId,
		const QString &	displayName = `QString()`,
		Group *	group = `0`,
		AddMode	mode = `DontChangeKABC`
	)

Create a contact (creating a new metacontact if necessary).

If a contact for this account with ID contactId is not already on the contact list, a new contact with that ID is created, and added to a new metacontact.

If mode is ChangeKABC, MetaContact::updateKABC will be called on the resulting metacontact. If mode is Temporary, MetaContact::setTemporary will be called on the resulting metacontact, and the metacontact will not be added to group. If mode is DontChangeKABC, no additional action is carried out.

Parameters:

	contactId	the Contact::contactId of the contact to create
	displayName	the displayname (alias) of the new metacontact. Leave as QString() if no alias is known, then by default, the nick will be taken as alias and tracked if changed.
	group	the group to add the created metacontact to, or 0 for the top-level group.
	mode	the mode used to add the contact. Use DontChangeKABC when deserializing.

Returns:: the new created metacontact or 0L if the operation failed

Definition at line 262 of file kopeteaccount.cpp.

BlackLister * Kopete::Account::blackLister ( )

Returns:: a pointer to the blacklist of the account

Todo:: remove or implement correctly (BlackLister)

Definition at line 544 of file kopeteaccount.cpp.

void Kopete::Account::block ( const QString & contactId ) [virtual, slot]

Add a user to the blacklist.

The default implementation calls blackList()->addContact( contactId )

Parameters:

contactId

the contact to be added to the blacklist

Todo:: remove or implement correctly (BlackLister)

Definition at line 549 of file kopeteaccount.cpp.

const QColor Kopete::Account::color ( ) const

Get the color for this account.

The color will be used to visually differentiate this account from other accounts on the same protocol.

Returns:: the user color for this account

void Kopete::Account::colorChanged ( const QColor & ) [signal]

The color of the account has been changed.

also emitted when the icon change

Todo:: probably rename to accountIconChanged

KConfigGroup * Kopete::Account::configGroup ( ) const

Return the KConfigGroup used to write and read special properties.

"Protocol", "AccountId" , "Color", "AutoConnect", "Priority", "Enabled" , "Icon" are reserved keyword already in use in that group.

for compatibility, try to not use key that start with a uppercase

Definition at line 215 of file kopeteaccount.cpp.

virtual void Kopete::Account::connect ( const Kopete::OnlineStatus & initialStatus = OnlineStatus() ) [pure virtual, slot]

Go online for this service.

Parameters:

initialStatus

is the status to connect with. If it is an invalid status for this account, the default online for the account should be used.

Todo:: probably deprecate in favor of setOnlineStatus

Implemented in Kopete::PasswordedAccount.

const QHash< QString, Contact * > & Kopete::Account::contacts ( )

Retrieve the list of contacts for this account.

The list is guaranteed to contain only contacts for this account, so you can safely use static_cast to your own derived contact class if needed.

Definition at line 256 of file kopeteaccount.cpp.

virtual bool Kopete::Account::createContact	(	const QString &	contactId,
		MetaContact *	parentContact
	)			`[protected, pure virtual]`

Create a new contact in the specified metacontact.

You shouldn't ever call this method yourself. To add contacts, use addContact().

This method is called by addContact(). In this method, you should create the new custom Contact, using parentContact as the parent.

If the metacontact is not temporary and the protocol supports it, you can add the contact to the server.

Parameters:

	contactId	the ID of the contact to create
	parentContact	the metacontact to add this contact to

Returns:: true if creating the contact succeeded, false on failure.

QString Kopete::Account::customIcon ( ) const

return the icon base This is the custom account icon set with setIcon.

if this icon is null, then the protocol icon is used don't use this function to get the icon that need to be displayed, use accountIcon

Definition at line 604 of file kopeteaccount.cpp.

virtual void Kopete::Account::disconnect ( ) [pure virtual, slot]

Go offline for this service.

If the service is connecting, you should abort the connection.

You should call the disconnected function from this function.

Todo:: probably deprecate in favor of setOnlineStatus

void Kopete::Account::disconnected ( Kopete::Account::DisconnectReason reason ) [protected, virtual, slot]

The service has been disconnected.

You have to call this method when you are disconnected. Depending on the value of reason, this function may attempt to reconnect to the server.

BadPassword will ask again for the password
OtherClient will show a message box

Parameters:

reason

the reason for the disconnection.

Reimplemented in Kopete::PasswordedAccount.

Definition at line 135 of file kopeteaccount.cpp.

void Kopete::Account::editAccount ( QWidget * parent = 0L ) [slot]

Display the edit account widget for the account.

Definition at line 564 of file kopeteaccount.cpp.

bool Kopete::Account::excludeConnect ( ) const

Get if the account should not log in.

Returns:: true if the account should not be connected when connectAll at startup, false otherwise.

void Kopete::Account::fillActionMenu ( KActionMenu * actionMenu ) [virtual]

Fill the menu with actions for this account.

You have to reimplement this method to add custom actions to the actionMenu which will be shown in the statusbar. It is the caller's responsibility to ensure the menu is deleted.

The default implementation provides a generic menu, with actions generated from the protocol's registered statuses, and an action to show the account's settings dialog.

You should call the default implementation from your reimplementation, and add more actions you require to the resulting action menu.

See also:: OnlineStatusManager::registerOnlineStatus

Definition at line 371 of file kopeteaccount.cpp.

bool Kopete::Account::hasCustomStatusMenu ( ) const [virtual]

Return true if account has custom status menu.

You have to reimplement this method and return true if you don't want to have status menu in menu which will be shown in the statusbar

The default implementation returns false.

Definition at line 398 of file kopeteaccount.cpp.

Identity * Kopete::Account::identity ( ) const

Retrieve the identity this account belongs to.

Returns:: a pointer to the Identity object this account belongs to.

See also:: setIdentity().

Definition at line 412 of file kopeteaccount.cpp.

bool Kopete::Account::isAway ( ) const

Indicate whether the account is away.

This is a convenience method that queries Contact::onlineStatus() on myself(). This function is safe to call if setMyself() has not been called yet.

bool Kopete::Account::isBlocked ( const QString & contactId ) [virtual]

Returns:: true if the contact with ID contactId is in the blacklist, false otherwise.

Todo:: remove or implement correctly (BlackLister)

Definition at line 559 of file kopeteaccount.cpp.

bool Kopete::Account::isConnected ( ) const

Indicate whether the account is connected at all.

This is a convenience method that calls Contact::isOnline() on myself(). This function is safe to call if setMyself() has not been called yet.

See also:: isConnectedChanged()

void Kopete::Account::isConnectedChanged ( ) [signal]

Emitted whenever isConnected() changes.

Contact * Kopete::Account::myself ( ) const

Retrieve the 'myself' contact.

Returns:: a pointer to the Contact object for this account

See also:: setMyself().

Definition at line 435 of file kopeteaccount.cpp.

uint Kopete::Account::priority ( ) const

Get the priority of this account.

Used for sorting and determining the preferred account to message a contact.

Protocol * Kopete::Account::protocol ( ) const

Returns:: the Protocol for this account

Definition at line 156 of file kopeteaccount.cpp.

void Kopete::Account::registerContact ( Contact * c )

Definition at line 243 of file kopeteaccount.cpp.

bool Kopete::Account::removeAccount ( ) [virtual]

Remove the account from the server.

Reimplement this if your protocol supports removing the accounts from the server. This function is called by AccountManager::removeAccount typically when you remove the account on the account config page.

You should add a confirmation message box before removing the account. The default implementation does nothing.

Returns:: false only if the user requested for the account to be deleted, and deleting the account failed. Returns true in all other cases.

Reimplemented in Kopete::PasswordedAccount.

Definition at line 537 of file kopeteaccount.cpp.

void Kopete::Account::setAccountLabel ( const QString & label ) [protected]

Sets the account label.

Parameters:

label

The label to set

Definition at line 220 of file kopeteaccount.cpp.

void Kopete::Account::setAllContactsStatus ( const Kopete::OnlineStatus & status ) [protected, slot]

Sets the online status of all contacts in this account to the same value.

Some protocols do not provide status-changed events for all contacts when an account becomes connected or disconnected. For such protocols, this function may be useful to set all contacts offline.

Calls Kopete::Contact::setOnlineStatus on all contacts of this account (except the myself() contact), passing status as the status.

Parameters:

status

the status to set all contacts of this account except myself() to.

Definition at line 501 of file kopeteaccount.cpp.

void Kopete::Account::setColor ( const QColor & color )

Set the color for this account.

This is called by Kopete's account config page; you don't have to set the color yourself.

See also:: color()

Definition at line 171 of file kopeteaccount.cpp.

void Kopete::Account::setCustomIcon ( const QString & i )

change the account icon.

by default the icon of an account is the protocol one, but it may be overide it. Set QString() to go back to the default (the protocol icon)

this call will emit colorChanged()

Definition at line 594 of file kopeteaccount.cpp.

void Kopete::Account::setExcludeConnect ( bool b )

Set if the account should not log in automatically.

This function can be used by the EditAccountPage. Kopete handles connection automatically.

See also:: excludeConnect

Definition at line 232 of file kopeteaccount.cpp.

bool Kopete::Account::setIdentity ( Kopete::Identity * ident ) [virtual]

Sets the identity this account belongs to.

Setting the account to a new identity implies it to be removed from the identity it was previously associated.

Parameters:

ident

The identity this account should be associated to

Returns:: true if the identity was changed, false otherwise

Note:: You should call the default implementation from your reimplementation

Definition at line 417 of file kopeteaccount.cpp.

void Kopete::Account::setMyself ( Contact * myself ) [protected]

Set the 'myself' contact.

This contact must be defined for every account, because it holds the online status of the account. You must call this function in the constructor of your account.

The myself contact can't be deleted as long as the account still exists. The myself contact is used as a member of every ChatSession involving this account. myself's contactId should be the accountID. The online status of the myself contact represents the account's status.

The myself should have the ContactList::myself() as parent metacontact

Definition at line 440 of file kopeteaccount.cpp.

virtual void Kopete::Account::setOnlineStatus	(	const Kopete::OnlineStatus &	status,
		const Kopete::StatusMessage &	reason = `Kopete::StatusMessage()`
	)			`[pure virtual, slot]`

Reimplement this function to set the online status.

Parameters:

	status	is the new status
	reason	is the status message to set.

Note:: If needed, you need to connect. if the offline status is given, you should disconnect

void Kopete::Account::setPriority ( uint priority )

Set the priority of this account.

Note:: This method is called by the UI, and should not be called elsewhere.

Definition at line 181 of file kopeteaccount.cpp.

virtual void Kopete::Account::setStatusMessage ( const Kopete::StatusMessage & statusMessage ) [pure virtual, slot]

Reimplement this function to set the status message(with metadata).

You should use this method to set the status message instead of using setOnlineStatus.

Parameters:

statusMessage

is the status message to set. (Use Kopete::StatusMessage).

bool Kopete::Account::suppressStatusNotification ( ) const

Indicates whether or not we should suppress status notifications for contacts belonging to this account.

This is used when we just connected or disconnected, and every contact has their initial status set.

Returns:: true if notifications should not be used, false otherwise

void Kopete::Account::unblock ( const QString & contactId ) [virtual, slot]

Remove a user from the blacklist.

The default implementation calls blackList()->removeContact( contactId )

Parameters:

contactId

the contact to be removed from the blacklist

Todo:: remove or implement correctly (BlackLister)

Definition at line 554 of file kopeteaccount.cpp.

Property Documentation

QPixmap Kopete::Account::accountIcon [read]

Definition at line 80 of file kopeteaccount.h.

QString Kopete::Account::accountId [read]

Definition at line 77 of file kopeteaccount.h.

const QColor Kopete::Account::color [read, write]

Definition at line 79 of file kopeteaccount.h.

bool Kopete::Account::excludeConnect [read, write]

Definition at line 78 of file kopeteaccount.h.

bool Kopete::Account::isAway [read]

Definition at line 82 of file kopeteaccount.h.

bool Kopete::Account::isConnected [read]

Definition at line 81 of file kopeteaccount.h.

uint Kopete::Account::priority [read, write]

Definition at line 84 of file kopeteaccount.h.

bool Kopete::Account::suppressStatusNotification [read]

Definition at line 83 of file kopeteaccount.h.

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

kopete/libkopete

Kopete::Account Class Reference

Detailed Description

Public Types

Public Slots

Signals

Public Member Functions

Protected Slots

Protected Member Functions

Properties

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Property Documentation

kopete/libkopete

kdenetwork