Communi  3.5.0
A cross-platform IRC framework written with Qt
Public Types | Public Slots | Signals | Public Member Functions | Static Public Member Functions | Protected Slots | Properties | List of all members
IrcConnection Class Reference

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

Inherits QObject.

Inherited by IrcBot.

Public Types

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 IrcConnectionclone (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 bool isSecureSupported ()
 
static Q_INVOKABLE bool isValidServer (const QString &server)
 

Protected Slots

virtual IrcCommandcreateCtcpReply (IrcPrivateMessage *request) const
 

Properties

bool active
 
bool connected
 
QVariantMap ctcpReplies
 
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
 
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:

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

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 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
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::isSecureSupported ( )
static
Deprecated:
Use Irc::isSecureSupported() instead.
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 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:

if (connection->isActive())
connection->sendCommand(IrcCommand::createQuit(reason));
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()
QVariantMap IrcConnection::ctcpReplies
readwrite
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()
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:
See also
QTextCodec::availableCodecs(), QTextCodec::codecForLocale()
QString IrcConnection::host
readwrite

This property holds the server host.

Access functions:
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:
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:
Notifier signal:
See also
nickName, nickNameRequired()
QString IrcConnection::password
readwrite

This property holds the password.

Access functions:
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:
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:
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
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:
Notifier signal:
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:
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
Deprecated:
Use Irc::supportedSaslMechanisms() instead.
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:
Notifier signal:
  • void userNameChanged(const QString& name)