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

Inherits QObject.

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 (const QString &host, QObject *parent=nullptr)

	IrcConnection (QObject *parent=nullptr)

	~IrcConnection () override

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

QVariantMap	ctcpReplies () const

QString	displayName () const

QByteArray	encoding () const

QString	host () const

void	installCommandFilter (QObject *filter)

void	installMessageFilter (QObject *filter)

IrcNetwork *	network () const

QString	nickName () const

QStringList	nickNames () const

QString	password () const

int	port () const

IrcProtocol *	protocol () const

QString	realName () const

void	removeCommandFilter (QObject *filter)

void	removeMessageFilter (QObject *filter)

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

QString	saslMechanism () const

Q_INVOKABLE QByteArray	saveState (int version=0) const

QStringList	servers () const

QAbstractSocket *	socket () const

QVariantMap	userData () const

QString	userName () const

Static Public Member Functions
static bool	isSecureSupported ()

static Q_INVOKABLE bool	isValidServer (const QString &server)

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

Properties
bool	active

bool	connected

int	connectionCount

bool	enabled

int	reconnectDelay

bool	secure

Status	status

QStringList	supportedSaslMechanisms

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

◆ Status

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() [1/2]

IrcConnection::IrcConnection ( QObject * parent = nullptr )

explicit

Constructs a new IRC connection with parent.

◆ IrcConnection() [2/2]

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

explicit

Constructs a new IRC connection with host and parent.

◆ ~IrcConnection()

IrcConnection::~IrcConnection ( )

override

Destructs the IRC connection.

Member Function Documentation

◆ channelKeyRequired

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

◆ clone()

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

Since: 3.4

Clones the IRC connection.

◆ close

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()

◆ connecting

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.

◆ createCtcpReply

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

protectedvirtualslot

Creates a reply command for the CTCP request.

The default implementation first checks whether the ctcpReplies property contains a user-supplied reply for the request. In case it does, the reply is sent automatically. In case there is no user-supplied reply, 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.

See also: ctcpReplies

◆ ctcpReplies()

QVariantMap IrcConnection::ctcpReplies ( ) const

Since: 3.5

This property holds CTCP (client to client protocol) replies.

This is a convenient request-reply map for customized static CTCP replies. For dynamic replies, override createCtcpReply() instead.

Note: Set an empty reply to omit the automatic reply.

Access functions:

QVariantMap ctcpReplies() const
void setCtcpReplies(const QVariantMap& replies)

Notifier signal:

void ctcpRepliesChanged(const QVariantMap& replies)

See also: createCtcpReply()

◆ disconnected

void IrcConnection::disconnected ( )

signal

This signal is emitted when the connection has been lost.

◆ displayName()

QString IrcConnection::displayName ( ) const

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)

◆ encoding()

QByteArray IrcConnection::encoding ( ) const

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()

◆ host()

QString IrcConnection::host ( ) const

This property holds the server host.

Access functions:

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

Notifier signal:

void hostChanged(const QString& host)

◆ installCommandFilter()

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()

◆ installMessageFilter()

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()

◆ isSecureSupported()

bool IrcConnection::isSecureSupported ( )

static

Deprecated:: Use Irc::isSecureSupported() instead.

◆ isValidServer()

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

◆ messageReceived

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 batchMessageReceived(IrcBatchMessage* message) (since 3.5)
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)

◆ network()

IrcNetwork * IrcConnection::network ( ) const

This property holds the network information.

Access function:

IrcNetwork* network() const

◆ nickName()

QString IrcConnection::nickName ( ) const

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

◆ nickNameRequired

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

◆ nickNames()

QStringList IrcConnection::nickNames ( ) const

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()

◆ open

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.

◆ password()

QString IrcConnection::password ( ) const

This property holds the password.

Access functions:

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

Notifier signal:

void passwordChanged(const QString& password)

◆ port()

int IrcConnection::port ( ) const

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)

◆ protocol()

IrcProtocol * IrcConnection::protocol ( ) const

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)

◆ quit

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:

if (connection->isActive())

connection->sendCommand(IrcCommand::createQuit(reason));

IrcCommand::createQuit

static Q_INVOKABLE IrcCommand * createQuit(const QString &reason=QString())

Definition: irccommand.cpp:780

See also: IrcCommand::createQuit()

◆ realName()

QString IrcConnection::realName ( ) const

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)

◆ removeCommandFilter()

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()

◆ removeMessageFilter()

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()

◆ restoreState()

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()

◆ saslMechanism()

QString IrcConnection::saslMechanism ( ) const

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

◆ 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().

◆ secureError

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.

◆ sendCommand

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()

◆ sendData

bool IrcConnection::sendData ( const QByteArray & data )

slot

Sends raw data to the server.

See also: sendCommand()

◆ sendRaw

bool IrcConnection::sendRaw ( const QString & message )

slot

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

See also: sendData(), sendCommand()

◆ servers()

QStringList IrcConnection::servers ( ) const

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()

◆ socket()

QAbstractSocket * IrcConnection::socket ( ) const

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

◆ socketError

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

signal

This signal is emitted when a socket error occurs.

See also: QAbstractSocket::error()

◆ socketStateChanged

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

signal

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

See also: QAbstractSocket::stateChanged()

◆ userData()

QVariantMap IrcConnection::userData ( ) const

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)

◆ userName()

QString IrcConnection::userName ( ) const

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)

Property Documentation

◆ active

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

◆ connected

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()

◆ connectionCount

int IrcConnection::connectionCount

read

This property holds the amount of times a connection was established.

The default value is 0 (no connections where established).

Access functions:

int connectionCount() const

◆ enabled

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)

◆ reconnectDelay

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)

◆ secure

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

◆ status

Status IrcConnection::status

read

This property holds the connection status.

Access function:

Status status() const

Notifier signal:

void statusChanged(Status status)

◆ supportedSaslMechanisms

QStringList IrcConnection::supportedSaslMechanisms

read

Deprecated:: Use Irc::supportedSaslMechanisms() instead.

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

◆ Status

Constructor & Destructor Documentation

◆ IrcConnection() [1/2]

◆ IrcConnection() [2/2]

◆ ~IrcConnection()

Member Function Documentation

◆ channelKeyRequired

◆ clone()

◆ close

◆ connecting

◆ createCtcpReply

◆ ctcpReplies()

◆ disconnected

◆ displayName()

◆ encoding()

◆ host()

◆ installCommandFilter()

◆ installMessageFilter()

◆ isSecureSupported()

◆ isValidServer()

◆ messageReceived

◆ network()

◆ nickName()

◆ nickNameRequired

◆ nickNames()

◆ open

◆ password()

◆ port()

◆ protocol()

◆ quit

◆ realName()

◆ removeCommandFilter()

◆ removeMessageFilter()

◆ restoreState()

◆ saslMechanism()

◆ saveState()

◆ secureError

◆ sendCommand

◆ sendData

◆ sendRaw

◆ servers()

◆ socket()

◆ socketError

◆ socketStateChanged

◆ userData()

◆ userName()

Property Documentation

◆ active

◆ connected

◆ connectionCount

◆ enabled

◆ reconnectDelay

◆ secure

◆ status

◆ supportedSaslMechanisms