Communi  3.0.0
A cross-platform IRC framework written with Qt
 All Classes Namespaces Files Functions Variables Enumerations Enumerator Properties Macros Groups Pages
Public Types | Public Slots | Signals | 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

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 connecting ()
 
void disconnected ()
 
void messageReceived (IrcMessage *message)
 
void nickNameReserved (QString *alternate)
 
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 ()
 
void installCommandFilter (QObject *filter)
 
void installMessageFilter (QObject *filter)
 
void removeCommandFilter (QObject *filter)
 
void removeMessageFilter (QObject *filter)
 

Protected Slots

virtual IrcCommandcreateCtcpReply (IrcPrivateMessage *request) const
 

Properties

bool active
 
bool connected
 
QString displayName
 
bool enabled
 
QByteArray encoding
 
QString host
 
IrcNetwork network
 
QString nickName
 
QString password
 
int port
 
QString realName
 
int reconnectDelay
 
QString saslMechanism
 
bool secure
 
QAbstractSocket socket
 
Status status
 
QStringList supportedSaslMechanisms
 
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::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()
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::nickNameReserved ( 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
Irc::ERR_NICKNAMEINUSE, Irc::ERR_NICKCOLLISION
void IrcConnection::open ( )
slot

Opens a connection to the server.

The function does nothing when the connection is 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:

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::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:
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 nick name.

Access functions:
Notifier signal:
  • void nickNameChanged(const QString& name)
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)
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
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
IrcConnection::socket
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

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

Access function:
See Also
saslMechanism
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)