Provides means to establish a connection to an IRC server. More...

Inherited by IrcBot.

Public Types
enum	Status { Inactive, Waiting, Connecting, Connected, Closing, Closed, Error }

Public Slots
void	close ()

void	open ()

void	quit (const QString &reason=QString())

bool	sendCommand (IrcCommand *command)

bool	sendData (const QByteArray &data)

bool	sendRaw (const QString &message)

Signals
void	channelKeyRequired (const QString &channel, QString *key)

void	connecting ()

void	disconnected ()

void	messageReceived (IrcMessage *message)

void	nickNameRequired (const QString &reserved, QString *alternate)

void	secureError ()

void	socketError (QAbstractSocket::SocketError error)

void	socketStateChanged (QAbstractSocket::SocketState state)

Public Member Functions
	IrcConnection (QObject *parent=0)

	IrcConnection (const QString &host, QObject *parent=0)

virtual	~IrcConnection ()

Q_INVOKABLE IrcConnection *	clone (QObject *parent=0) const

void	installCommandFilter (QObject *filter)

void	installMessageFilter (QObject *filter)

void	removeCommandFilter (QObject *filter)

void	removeMessageFilter (QObject *filter)

Q_INVOKABLE bool	restoreState (const QByteArray &state, int version=0)

Q_INVOKABLE QByteArray	saveState (int version=0) const

Static Public Member Functions
static Q_INVOKABLE bool	isValidServer (const QString &server)

Protected Slots
virtual IrcCommand *	createCtcpReply (IrcPrivateMessage *request) const

Properties
bool	active

bool	connected

QString	displayName

bool	enabled

QByteArray	encoding

QString	host

IrcNetwork	network

QString	nickName

QStringList	nickNames

QString	password

int	port

IrcProtocol	protocol

QString	realName

int	reconnectDelay

QString	saslMechanism

bool	secure

bool	secureSupported

QStringList	servers

QAbstractSocket	socket

Status	status

QStringList	supportedSaslMechanisms

QVariantMap	userData

QString	userName

Detailed Description

Connection management

Before opening a connection, it must be first initialized with host, userName, nickName and realName.

The connection status may be queried at any time via status(). Also isActive() and isConnected() are provided for convenience. In addition to the statusChanged() signal, the most important statuses are informed via the following convenience signals:

connecting() - The connection is being established.
connected() - The IRC connection has been established, and the server is ready to receive commands.
disconnected() - The connection has been lost.

Receiving messages

Whenever a message is received from the server, the messageReceived() signal is emitted. Also message type specific signals are provided for convenience. See messageReceived() and IrcMessage and its subclasses for more details.

Sending commands

Sending commands to a server is most conveniently done by creating them via the various static IrcCommand::createXxx() methods and passing them to sendCommand(). Also sendData() is provided for more low-level access. See IrcCommand for more details.

Example

IrcConnection* connection = new IrcConnection(this);
connect(connection, SIGNAL(messageReceived(IrcMessage*)), this, SLOT(onMessageReceived(IrcMessage*)));
connection->setHost("irc.server.com");
connection->setUserName("me");
connection->setNickName("myself");
connection->setRealName("And I");
connection->sendCommand(IrcCommand::createJoin("#mine"));
connection->open();

See also: IrcNetwork, IrcMessage, IrcCommand

Member Enumeration Documentation

enum IrcConnection::Status

This enum describes the connection status.

Enumerator
Inactive	The connection is inactive.
Waiting	The connection is waiting for a reconnect.
Connecting	The connection is being established.
Connected	The connection has been established.
Closing	The connection is being closed.
Closed	The connection has been closed.
Error	The connection has encountered an error.

Constructor & Destructor Documentation

IrcConnection::IrcConnection ( QObject * parent = 0 )

explicit

Constructs a new IRC connection with parent.

IrcConnection::IrcConnection	(	const QString &	host,
		QObject *	parent = `0`
	)

explicit

Constructs a new IRC connection with host and parent.

IrcConnection::~IrcConnection ( )

virtual

Destructs the IRC connection.

Member Function Documentation

void IrcConnection::channelKeyRequired	(	const QString &	channel,
		QString *	key
	)

signal

This signal is emitted when joining a channel requires a key. The key may be set via the provided argument, or by sending a new join command directly.

See also: IrcCommand::createJoin(), Irc::ERR_BADCHANNELKEY

IrcConnection * IrcConnection::clone ( QObject * parent = 0 ) const

Since: 3.4

Clones the IRC connection.

void IrcConnection::close ( )

slot

Immediately closes the connection to the server.

Calling close() makes the connection close immediately and thus might lead to "remote host closed the connection". In order to quit gracefully, call quit() first. This function attempts to flush the underlying socket, but this does not guarantee that the server ever receives the QUIT command if the connection is closed immediately after sending the command. In order to ensure a graceful quit, let the server handle closing the connection.

C++ example:

connection->quit(reason);

QTimer::singleShot(timeout, connection, SLOT(deleteLater()));

QML example:

connection.quit(reason);

connection.destroy(timeout);

See also: quit()

void IrcConnection::connecting ( )

signal

This signal is emitted when the connection is being established.

The underlying socket has connected, but the IRC handshake is not yet finished and the server is not yet ready to receive commands.

IrcCommand * IrcConnection::createCtcpReply ( IrcPrivateMessage * request ) const

protectedvirtualslot

Creates a reply command for the CTCP request.

The default implementation handles the following CTCP requests: CLIENTINFO, PING, SOURCE, TIME and VERSION.

Reimplement this function in order to alter or omit the default replies.

void IrcConnection::disconnected ( )

signal

This signal is emitted when the connection has been lost.

void IrcConnection::installCommandFilter ( QObject * filter )

Installs a command filter on the connection. The filter must implement the IrcCommandFilter interface.

A command filter receives all commands that are sent from the connection. The filter receives commands via the commandFilter() function. The function must return true if the command should be filtered, (i.e. stopped); otherwise it must return false.

If multiple command filters are installed on the same connection, the filter that was installed last is activated first.

See also: removeCommandFilter()

void IrcConnection::installMessageFilter ( QObject * filter )

Installs a message filter on the connection. The filter must implement the IrcMessageFilter interface.

A message filter receives all messages that are sent to the connection. The filter receives messages via the messageFilter() function. The function must return true if the message should be filtered, (i.e. stopped); otherwise it must return false.

If multiple message filters are installed on the same connection, the filter that was installed last is activated first.

See also: removeMessageFilter()

bool IrcConnection::isValidServer ( const QString & server )

static

Since: 3.3

Returns true if the server line syntax is valid.

The syntax is:

host <[+]port>

where port is optional (defaults to 6667) and + prefix denotes SSL.

See also: servers

void IrcConnection::messageReceived ( IrcMessage * message )

signal

This signal is emitted when a message is received.

In addition, message type specific signals are provided for convenience:

void accountMessageReceived(IrcAccountMessage* message) (since 3.3)
void awayMessageReceived(IrcAwayMessage* message) (since 3.3)
void capabilityMessageReceived(IrcCapabilityMessage* message)
void errorMessageReceived(IrcErrorMessage* message)
void hostChangeMessageReceived(IrcHostChangeMessage* message) (since 3.4)
void inviteMessageReceived(IrcInviteMessage* message)
void joinMessageReceived(IrcJoinMessage* message)
void kickMessageReceived(IrcKickMessage* message)
void modeMessageReceived(IrcModeMessage* message)
void motdMessageReceived(IrcMotdMessage* message)
void namesMessageReceived(IrcNamesMessage* message)
void nickMessageReceived(IrcNickMessage* message)
void noticeMessageReceived(IrcNoticeMessage* message)
void numericMessageReceived(IrcNumericMessage* message)
void partMessageReceived(IrcPartMessage* message)
void pingMessageReceived(IrcPingMessage* message)
void pongMessageReceived(IrcPongMessage* message)
void privateMessageReceived(IrcPrivateMessage* message)
void quitMessageReceived(IrcQuitMessage* message)
void topicMessageReceived(IrcTopicMessage* message)
void whoisMessageReceived(IrcWhoisMessage* message) (since 3.3)
void whowasMessageReceived(IrcWhowasMessage* message) (since 3.3)
void whoReplyMessageReceived(IrcWhoReplyMessage* message) (since 3.1)

void IrcConnection::nickNameRequired	(	const QString &	reserved,
		QString *	alternate
	)

signal

This signal is emitted when the requested nick name is reserved and an alternate nick name should be provided.

An alternate nick name may be set via the provided argument, by changing the nickName property, or by sending a nick command directly.

See also: nickNames, IrcCommand::createNick(), Irc::ERR_NICKNAMEINUSE, Irc::ERR_NICKCOLLISION

void IrcConnection::open ( )

slot

Opens a connection to the server.

The function does nothing when the connection is already active or explicitly disabled.

Note: The function merely outputs a warnings and returns immediately if either host, userName, nickName or realName is empty.

void IrcConnection::quit ( const QString & reason = QString() )

slot

Sends a quit command with an optionally specified reason.

This method is provided for convenience. It is equal to:

IrcCommand* command = IrcCommand::createQuit(reason);

connection->sendCommand(command);

See also: IrcCommand::createQuit()

void IrcConnection::removeCommandFilter ( QObject * filter )

Removes a command filter from the connection.

The request is ignored if such command filter has not been installed. All command filters for a connection are automatically removed when the connection is destroyed.

See also: installCommandFilter()

void IrcConnection::removeMessageFilter ( QObject * filter )

Removes a message filter from the connection.

The request is ignored if such message filter has not been installed. All message filters for a connection are automatically removed when the connection is destroyed.

See also: installMessageFilter()

bool IrcConnection::restoreState	(	const QByteArray &	state,
		int	version = `0`
	)

Since: 3.1

Restores the state of the connection. The version number is compared with that stored in state. If they do not match, the connection state is left unchanged, and this function returns false; otherwise, the state is restored, and true is returned.

See also: saveState()

QByteArray IrcConnection::saveState ( int version = 0 ) const

Since: 3.1

Saves the state of the connection. The version number is stored as part of the state data.

To restore the saved state, pass the return value and version number to restoreState().

void IrcConnection::secureError ( )

signal

Since: 3.2

This signal is emitted when SSL socket error occurs.

Either QSslSocket::sslErrors() was emitted, or the handshake failed meaning that the server is not SSL-enabled.

bool IrcConnection::sendCommand ( IrcCommand * command )

slot

Sends a command to the server.

If the connection is not active, the command is queued and sent later when the connection has been established.

Note: If the command has a valid parent, it is an indication that the caller of this method is be responsible for freeing the command. If the command does not have a valid parent (like the commands created via various IrcCommand::createXxx() methods) the connection will take ownership of the command and delete it once it has been sent. Thus, the command must have been allocated on the heap and it is not safe to access the command after it has been sent.

See also: sendData()

bool IrcConnection::sendData ( const QByteArray & data )

slot

Sends raw data to the server.

See also: sendCommand()

bool IrcConnection::sendRaw ( const QString & message )

slot

Sends raw message to the server using UTF-8 encoding.

See also: sendData(), sendCommand()

void IrcConnection::socketError ( QAbstractSocket::SocketError error )

signal

This signal is emitted when a socket error occurs.

See also: QAbstractSocket::error()

void IrcConnection::socketStateChanged ( QAbstractSocket::SocketState state )

signal

This signal is emitted when the state of the underlying socket changes.

See also: QAbstractSocket::stateChanged()

Property Documentation

bool IrcConnection::active

read

This property holds whether the connection is active.

The connection is considered active when its either connecting, connected or closing.

Access function:

bool isActive() const

bool IrcConnection::connected

read

This property holds whether the connection has been established.

The connection has been established when the welcome message has been received and the server is ready to receive commands.

See also: Irc::RPL_WELCOME

Access function:

bool isConnected() const

Notifier signal:

void connected()

QString IrcConnection::displayName

readwrite

This property holds the display name.

Unless explicitly set, display name resolves to IrcNetwork::name or IrcConnection::host while the former is not known.

Access functions:

QString displayName() const
void setDisplayName(const QString& name)

Notifier signal:

void displayNameChanged(const QString& name)

bool IrcConnection::enabled

readwrite

This property holds whether the connection is enabled.

The default value is true.

When set to false, a disabled connection does nothing when open() is called.

Access functions:

bool isEnabled() const
void setEnabled(bool enabled) [slot]
void setDisabled(bool disabled) [slot]

Notifier signal:

void enabledChanged(bool enabled)

QByteArray IrcConnection::encoding

readwrite

This property holds the FALLBACK encoding for received messages.

The fallback encoding is used when the message is detected not to be valid UTF-8 and the consequent auto-detection of message encoding fails. See QTextCodec::availableCodecs() for the list of supported encodings.

The default value is ISO-8859-15.

Access functions:

QByteArray encoding() const
void setEncoding(const QByteArray& encoding)

See also: QTextCodec::availableCodecs(), QTextCodec::codecForLocale()

QString IrcConnection::host

readwrite

This property holds the server host.

Access functions:

QString host() const
void setHost(const QString& host)

Notifier signal:

void hostChanged(const QString& host)

IrcNetwork * IrcConnection::network

read

This property holds the network information.

Access function:

IrcNetwork* network() const

QString IrcConnection::nickName

readwrite

This property holds the current nick name.

Access functions:

QString nickName() const
void setNickName(const QString& name)

Notifier signal:

void nickNameChanged(const QString& name)

See also: nickNames

QStringList IrcConnection::nickNames

readwrite

Since: 3.3

This property holds the nick names.

The list of nick names is automatically cycled through when the current nick name is reserved. If all provided nick names are reserved, the nickNameRequired() signal is emitted.

Access functions:

QStringList nickNames() const
void setNickNames(const QStringList& names)

Notifier signal:

void nickNamesChanged(const QStringList& names)

See also: nickName, nickNameRequired()

QString IrcConnection::password

readwrite

This property holds the password.

Access functions:

QString password() const
void setPassword(const QString& password)

Notifier signal:

void passwordChanged(const QString& password)

int IrcConnection::port

readwrite

This property holds the server port.

The default value is 6667.

Access functions:

int port() const
void setPort(int port)

Notifier signal:

void portChanged(int port)

IrcProtocol * IrcConnection::protocol

readwrite

Since: 3.2

This property holds the protocol.

The previously set protocol is deleted if its parent is this.

Access functions:

IrcProtocol* protocol() const
void setProtocol(IrcProtocol* protocol)

QString IrcConnection::realName

readwrite

This property holds the real name.

Note: Changing the real name has no effect until the connection is re-established.

Access functions:

QString realName() const
void setRealName(const QString& name)

Notifier signal:

void realNameChanged(const QString& name)

int IrcConnection::reconnectDelay

readwrite

This property holds the reconnect delay in seconds.

A positive (greater than zero) value enables automatic reconnect. When the connection is lost due to a socket error, IrcConnection will automatically attempt to reconnect after the specified delay.

The default value is 0 (automatic reconnect disabled).

Access functions:

int reconnectDelay() const
void setReconnectDelay(int seconds)

Notifier signal:

void reconnectDelayChanged(int seconds)

QString IrcConnection::saslMechanism

readwrite

This property holds the used SASL (Simple Authentication and Security Layer) mechanism.

Access functions:

QString saslMechanism() const
void setSaslMechanism(const QString& mechanism)

Notifier signal:

void saslMechanismChanged(const QString& mechanism)

See also: supportedSaslMechanisms, IRCv3 support

bool IrcConnection::secure

readwrite

This property holds whether the socket is an SSL socket.

This property is provided for convenience. Calling

connection->setSecure(true);

is equivalent to:

QSslSocket* socket = new QSslSocket(socket);
socket->setPeerVerifyMode(QSslSocket::QueryPeer);
connection->setSocket(socket);

Note: IrcConnection does not handle SSL errors, see QSslSocket::sslErrors() for more details on the subject.

Access functions:

bool isSecure() const
void setSecure(bool secure)

Notifier signal:

void secureChanged(bool secure)

See also: secureSupported, IrcConnection::socket

bool IrcConnection::secureSupported

read

Since: 3.2

This property holds whether SSL is supported.

The value may be false for the following reasons:

Qt was built without SSL support (QT_NO_SSL is defined), or
The platform does not support SSL (QSslSocket::supportsSsl() returns false).

Access function:

static bool isSecureSupported()

See also: secure, QSslSocket::supportsSsl()

QStringList IrcConnection::servers

readwrite

Since: 3.3

This property holds the list of servers.

The list of servers is automatically cycled through when reconnecting.

Access functions:

QStringList servers() const
void setServers(const QStringList& servers)

Notifier signal:

void serversChanged(const QStringList& servers)

See also: isValidServer()

QAbstractSocket * IrcConnection::socket

readwrite

This property holds the socket. The default value is an instance of QTcpSocket.

The previously set socket is deleted if its parent is this.

Note: IrcConnection supports QSslSocket in the way that it automatically calls QSslSocket::startClientEncryption() while connecting.

Access functions:

QAbstractSocket* socket() const
void setSocket(QAbstractSocket* socket)

See also: IrcConnection::secure

IrcConnection::Status IrcConnection::status

read

This property holds the connection status.

Access function:

Status status() const

Notifier signal:

void statusChanged(Status status)

QStringList IrcConnection::supportedSaslMechanisms

read

This property holds the list of supported SASL (Simple Authentication and Security Layer) mechanisms.

Access function:

static QStringList supportedSaslMechanisms()

See also: saslMechanism, IRCv3 support

QVariantMap IrcConnection::userData

readwrite

Since: 3.1

This property holds arbitrary user data.

Access functions:

QVariantMap userData() const
void setUserData(const QVariantMap& data)

Notifier signal:

void userDataChanged(const QVariantMap& data)

QString IrcConnection::userName

readwrite

This property holds the user name.

Note: Changing the user name has no effect until the connection is re-established.

Access functions:

QString userName() const
void setUserName(const QString& name)

Notifier signal:

void userNameChanged(const QString& name)

Public Types

Public Slots

Signals

Public Member Functions

Static Public Member Functions

Protected Slots

Properties

Detailed Description

Connection management

Receiving messages

Sending commands

Example

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Property Documentation