org.jibble.pircbot
Class PircBot

java.lang.Object
  |
  +--org.jibble.pircbot.PircBot

public abstract class PircBot
extends Object

PircBot is a framework for an IRC Bot written in Java. It allows you to create your own custom IRC Bots using Java by building on the framework that is already provided by the abstract PircBot.

Methods of the PircBot class can be called to send events to the IRC server that it connects to. For example, calling the sendMessage method will send a message to a channel on the IRC server.

To perform an action when the PircBot receives a message from the IRC server, you would override the onMessage method defined in the PircBot class. All onXYZ methods in the PircBot class are automatically called when the event XYZ happens, so you would override these if you wish to do something when it does happen.

Some event methods, such as onPing, should only really perform a specific function (i.e. return a PING back to the server). For your convenience, such methods are already correctly implemented in the PircBot and should not normally need to be overridden. Please read the full documentation for each method to see which ones are already implemented by the PircBot class.

Version:
0.9.4 (Build time: Sun Jun 2 01:10:24 2002)
Author:
Paul James Mutton, http://www.jibble.org/

Field Summary
static String VERSION
          The definitive version number of this release of PircBot.
 
Constructor Summary
PircBot()
          Constructs a PircBot with the default settings.
 
Method Summary
 void ban(String channel, String hostmask)
          Bans a user from a channel.
 void changeNick(String newNick)
          Attempt to change the current nick of this user.
 void connect(String hostname)
          Attempt to connect to the specified IRC server.
 void connect(String hostname, int port)
          Attempt to connect to the specified IRC server and port number.
 void connect(String hostname, int port, String password)
          Attempt to connect to the specified IRC server using the supplied password.
protected  DccChat dccAcceptChatRequest(String sourceNick, long address, int port)
          Attempts to accept a DCC CHAT request by a client.
protected  void dccReceiveFile(File file, long address, int port, int size)
          Receives a file that is being sent to us by a DCC SEND request.
 void dccSendFile(File file, String nick, int timeout)
          Issues a DCC SEND request to the specified nick.
 void deOp(String channel, String nick)
          Removes operator privilidges from a user on a channel.
 void deVoice(String channel, String nick)
          Removes voice privilidges from a user on a channel.
protected  void disconnect()
          This method disconnects from the server by closing the socket and ending the threads that read from and write to the server.
 String getFinger()
          Gets the internal finger message of the PircBot.
 String getLogin()
          Gets the internal login of the PircBot.
 int getMaxLineLength()
          Gets the maximum length of any line that is sent via the IRC protocol.
 long getMessageDelay()
          Returns the number of milliseconds that will be used to separate consecutive messages to the server from the outgoing message queue.
 String getName()
          Gets the internal name of the PircBot.
 String getVersion()
          Gets the internal version of the PircBot.
protected  void handleLine(String line)
          This method handles events when any line of text arrives from the server, then calling the appropriate method in the PircBot.
 boolean isConnected()
          Returns whether or not the PircBot is currently connected to a server.
 void joinChannel(String channel)
          Joins a channel.
 void joinChannel(String channel, String key)
          Joins a channel with a key.
 void kick(String channel, String nick)
          Kicks a user from a channel.
 void kick(String channel, String nick, String reason)
          Kicks a user from a channel, giving a reason.
 void log(String line)
          Adds a line to the log.
 int[] longToIp(long address)
          A convenient method that accepts an I.P.
protected  void onAction(String sender, String login, String hostname, String target, String action)
          This method is called whenever an ACTION is sent from a user.
protected  void onDccChatRequest(String sourceNick, String sourceLogin, String sourceHostname, long address, int port)
          This method is called whenever a DCC CHAT request is sent to the PircBot.
protected  void onDccSendRequest(String sourceNick, String sourceLogin, String sourceHostname, String filename, long address, int port, int size)
          This method is called whenever a DCC SEND request is sent to the PircBot.
protected  void onDisconnect()
          This method carries out the actions to be performed when the PircBot gets disconnected.
protected  void onFinger(String sourceNick, String sourceLogin, String sourceHostname, String target)
          This method is called whenever we receive a FINGER request.
protected  void onInvite(String targetNick, String sourceNick, String sourceLogin, String sourceHostname, String channel)
          Called when we are invited to a channel by a user.
protected  void onJoin(String channel, String sender, String login, String hostname)
          This method is called whenever someone (possibly us) joins a channel which we are on.
protected  void onKick(String channel, String kickerNick, String kickerLogin, String kickerHostname, String recipientNick, String reason)
          This method is called whenever someone (possibly us) is kicked from any of the channels that we are in.
protected  void onMessage(String channel, String sender, String login, String hostname, String message)
          This method is called whenever a message is sent to a channel.
protected  void onMode(String channel, String sourceNick, String sourceLogin, String sourceHostname, String mode)
          Called when the mode of a channel is set.
protected  void onNickChange(String oldNick, String login, String hostname, String newNick)
          This method is called whenever someone (possibly us) changes nick on any of the channels that we are on.
protected  void onNotice(String sourceNick, String sourceLogin, String sourceHostname, String target, String notice)
          This method is called whenever we receive a notice.
protected  void onPart(String channel, String sender, String login, String hostname)
          This method is called whenever someone (possibly us) parts a channel which we are on.
protected  void onPing(String sourceNick, String sourceLogin, String sourceHostname, String target, String pingValue)
          This method is called whenever we receive a PING request.
protected  void onPrivateMessage(String sender, String login, String hostname, String message)
          This method is called whenever a private message is sent to the PircBot.
protected  void onQuit(String sourceNick, String sourceLogin, String sourceHostname, String reason)
          This method is called whenever someone (possibly us) quits from the server.
protected  void onServerPing(String response)
          The actions to perform when a PING request comes from the server.
protected  void onServerResponse(int code, String response)
          This method is called when we receive a numeric response from the IRC server.
protected  void onTime(String sourceNick, String sourceLogin, String sourceHostname, String target)
          This method is called whenever we receive a TIME request.
protected  void onUnknown(String line)
          This method is called whenever we receive a line from the server that the PircBot has not been programmed to recognise.
protected  void onVersion(String sourceNick, String sourceLogin, String sourceHostname, String target)
          This method is called whenever we receive a VERSION request.
 void op(String channel, String nick)
          Grants operator privilidges to a user on a channel.
 void partChannel(String channel)
          Parts a channel.
 void partChannel(String channel, String reason)
          Parts a channel, giving a reason.
 void quitServer()
          Quits from the IRC server.
 void quitServer(String reason)
          Quits from the IRC server with a reason.
 void sendAction(String target, String action)
          Sends an action to the channel or to a user.
 void sendInvite(String nick, String channel)
          Sends an invitation to join a channel.
 void sendMessage(String target, String message)
          Sends a message to a channel or user.
 void sendNotice(String target, String notice)
          Sends a notice to the channel or to a user.
 void sendRawLine(String line)
          Sends a raw line to the IRC server as soon as possible, bypassing the outgoing message queue.
protected  void setFinger(String finger)
          Sets the interal finger message.
protected  void setLogin(String login)
          Sets the interal login of the Bot.
 void setMessageDelay(long delay)
          Sets the number of milliseconds to delay between consecutive messages when there are multiple messages waiting in the outgoing message queue.
 void setMode(String channel, String mode)
          Set the mode of a channel.
protected  void setName(String name)
          Sets the internal name of the Bot.
 void setTopic(String channel, String topic)
          Set the topic for a channel.
 void setVerbose(boolean verbose)
          Sets the verbose mode.
protected  void setVersion(String version)
          Sets the internal version of the Bot.
 void startIdentServer()
          Starts an ident server (Identification Protocol Server, RFC 1413).
 void unBan(String channel, String hostmask)
          Unbans a user from a channel.
 void voice(String channel, String nick)
          Grants voice privilidges to a user on a channel.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

VERSION

public static final String VERSION
The definitive version number of this release of PircBot.

See Also:
Constant Field Values
Constructor Detail

PircBot

public PircBot()
Constructs a PircBot with the default settings. Your own constructors in classes which extend the PircBot abstract class should be responsible for changing the default settings if required.

Method Detail

connect

public final void connect(String hostname)
                   throws IOException,
                          IrcException,
                          NickAlreadyInUseException
Attempt to connect to the specified IRC server.

Parameters:
hostname - The hostname of the server to connect to.
Throws:
IOException - if it was not possible to connect to the server.
IrcException - if the server would not let us join it.
NickAlreadyInUseException - if our nick is already in use on the server.

connect

public final void connect(String hostname,
                          int port)
                   throws IOException,
                          IrcException,
                          NickAlreadyInUseException
Attempt to connect to the specified IRC server and port number.

Parameters:
hostname - The hostname of the server to connect to.
port - The port number to connect to on the server.
Throws:
IOException - if it was not possible to connect to the server.
IrcException - if the server would not let us join it.
NickAlreadyInUseException - if our nick is already in use on the server.

connect

public final void connect(String hostname,
                          int port,
                          String password)
                   throws IOException,
                          IrcException,
                          NickAlreadyInUseException
Attempt to connect to the specified IRC server using the supplied password.

Parameters:
hostname - The hostname of the server to connect to.
port - The port number to connect to on the server.
password - The password to use to join the server.
Throws:
IOException - if it was not possible to connect to the server.
IrcException - if the server would not let us join it.
NickAlreadyInUseException - if our nick is already in use on the server.

disconnect

protected final void disconnect()
This method disconnects from the server by closing the socket and ending the threads that read from and write to the server. This method is called when the connection to the server fails to ensure that the threads are stopped. It may also be called explicitly to disconnect from a server. You may wish to use the quitServer method to exit an IRC server normally.


startIdentServer

public void startIdentServer()
Starts an ident server (Identification Protocol Server, RFC 1413).

Most IRC servers attempt to contact the ident server on connecting hosts in order to determine the user's identity. A few IRC servers will not allow you to connect unless this information is provided.

So when a PircBot is run on a machine that does not run an ident server, it may be necessary to call this method to start one up.

Calling this method starts up an ident server which will respond with the login provided by calling getLogin() and then shut down immediately. It will also be shut down if it has not been contacted within 60 seconds of creation.

If you require an ident response, then the correct procedure is to start the ident server and then connect to the IRC server. The IRC server may then contact the ident server to get the information it needs.

The ident server will fail to start if there is already an ident server running on port 113, or if you are running as an unprivileged user who is unable to create a server socket on that port number.

If it is essential for you to use an ident server when connecting to an IRC server, then make sure that port 113 on your machine is visible to the IRC server so that it may contact the ident server.


joinChannel

public final void joinChannel(String channel)
Joins a channel.

Parameters:
channel - The name of the channel to join (eg #cs).

joinChannel

public final void joinChannel(String channel,
                              String key)
Joins a channel with a key.

Parameters:
channel - The name of the channel to join (eg #cs).
key - The key that will be used to join the channel.

partChannel

public final void partChannel(String channel)
Parts a channel.

Parameters:
channel - The name of the channel to leave.

partChannel

public final void partChannel(String channel,
                              String reason)
Parts a channel, giving a reason.

Parameters:
channel - The name of the channel to leave.
reason - The reason for parting the channel.

quitServer

public final void quitServer()
Quits from the IRC server.


quitServer

public final void quitServer(String reason)
Quits from the IRC server with a reason.

Parameters:
reason - The reason for quitting the server.

sendRawLine

public final void sendRawLine(String line)
Sends a raw line to the IRC server as soon as possible, bypassing the outgoing message queue.

Parameters:
line - The raw line to send to the IRC server.

sendMessage

public final void sendMessage(String target,
                              String message)
Sends a message to a channel or user. These messages are added to the outgoing message queue and sent at the earliest possible opportunity.

Parameters:
target - The name of the channel or user nick to send to.
message - The message to send.

sendAction

public final void sendAction(String target,
                             String action)
Sends an action to the channel or to a user.

Parameters:
target - The name of the channel or user nick to send to.
action - The action to send.

sendNotice

public final void sendNotice(String target,
                             String notice)
Sends a notice to the channel or to a user.

Parameters:
target - The name of the channel or user nick to send to.
notice - The notice to send.

changeNick

public final void changeNick(String newNick)
Attempt to change the current nick of this user.

Parameters:
newNick - The new nick to use.

setMode

public final void setMode(String channel,
                          String mode)
Set the mode of a channel. This method attempts to set the mode of a channel. This may require the bot to have operator status on the channel. For example, if the bot has operator status, we can grant operator status to "Dave" on the #cs channel by calling setMode("#cs", "+o Dave"); An alternative way of doing this would be to use the op method.

Parameters:
channel - The channel on which to perform the mode change.
mode - The new mode to apply to the channel. This may include zero or more arguments if necessary.

sendInvite

public final void sendInvite(String nick,
                             String channel)
Sends an invitation to join a channel. Some channels can be marked as "invite-only", so it may be useful to allow a bot to invite people into it.

Parameters:
nick - The nick of the user to invite
channel - The channel you are inviting the user to join.

ban

public final void ban(String channel,
                      String hostmask)
Bans a user from a channel. An example of a valid hostmask is "*!*compu@*.18hp.net". This may be used in conjunction with the kick method to permanently remove a user from a channel. Successful use of this method may require the bot to have operator status itself.

Parameters:
channel - The channel to ban the user from.
hostmask - A hostmask representing the user we're banning.

unBan

public final void unBan(String channel,
                        String hostmask)
Unbans a user from a channel. An example of a valid hostmask is "*!*compu@*.18hp.net". Successful use of this method may require the bot to have operator status itself.

Parameters:
channel - The channel to unban the user from.
hostmask - A hostmask representing the user we're unbanning.

op

public final void op(String channel,
                     String nick)
Grants operator privilidges to a user on a channel. Successful use of this method may require the bot to have operator status itself.

Parameters:
channel - The channel we're opping the user on.
nick - The nick of the user we are opping.

deOp

public final void deOp(String channel,
                       String nick)
Removes operator privilidges from a user on a channel. Successful use of this method may require the bot to have operator status itself.

Parameters:
channel - The channel we're deopping the user on.
nick - The nick of the user we are deopping.

voice

public final void voice(String channel,
                        String nick)
Grants voice privilidges to a user on a channel. Successful use of this method may require the bot to have operator status itself.

Parameters:
channel - The channel we're voicing the user on.
nick - The nick of the user we are voicing.

deVoice

public final void deVoice(String channel,
                          String nick)
Removes voice privilidges from a user on a channel. Successful use of this method may require the bot to have operator status itself.

Parameters:
channel - The channel we're devoicing the user on.
nick - The nick of the user we are devoicing.

setTopic

public final void setTopic(String channel,
                           String topic)
Set the topic for a channel. This method attempts to set the topic of a channel. This may require the bot to have operator status if the topic is protected.

Parameters:
channel - The channel on which to perform the mode change.
topic - The new topic for the channel.

kick

public final void kick(String channel,
                       String nick)
Kicks a user from a channel. This method attempts to kick a user from a channel and may require the bot to have operator status in the channel.

Parameters:
channel - The channel to kick the user from.
nick - The nick of the user to kick.

kick

public final void kick(String channel,
                       String nick,
                       String reason)
Kicks a user from a channel, giving a reason. This method attempts to kick a user from a channel and may require the bot to have operator status in the channel.

Parameters:
channel - The channel to kick the user from.
nick - The nick of the user to kick.
reason - A description of the reason for kicking a user.

dccSendFile

public final void dccSendFile(File file,
                              String nick,
                              int timeout)
Issues a DCC SEND request to the specified nick. After doing this, the recipient is allowed up to timeout milliseconds to accept the request by connecting to the PircBot to start downloading the file, otherwise the chance is lost. Once the recipient has connected, we close the connection if the download is completed, if the download fails or if no data is sent for a 30 second period. This methods starts a new Thread to operate in and thus returns immediately. The method performs no action if the filename does not exist.

Parameters:
nick - The nick of the recipient.
timeout - The number of milliseconds to wait for the recipient to accept the file (we recommend about 120000ms).

dccReceiveFile

protected final void dccReceiveFile(File file,
                                    long address,
                                    int port,
                                    int size)
Receives a file that is being sent to us by a DCC SEND request. When we receive a DCC SEND request, we use this method to connect to the sender and download the file. This method should only be called by the onDccSendRequest method if you choose to do so. If we do not receive any data for more than 30 seconds, then we close the connection. This method will overwrite any existing file which has the same filename.

Parameters:
address - The host address of the initiator as an integer.
port - The port number to connect to in order to download the file.
size - The size of the file. If not known, this must be -1.

dccAcceptChatRequest

protected final DccChat dccAcceptChatRequest(String sourceNick,
                                             long address,
                                             int port)
Attempts to accept a DCC CHAT request by a client. This method tries to establish the connection to the client. Once the connection has been established, a DccChat object is returned. The DccChat object can be used to send and receive lines of text over the direct connection. If a connection could not be established, the DccChat object returned is null. This method is typically called by the onDccChatRequest method.


log

public void log(String line)
Adds a line to the log. This log is currently output to the standard output. You may override this method if you wish to do something else with log entries. Each line in the log begins with a number which represents the logging time (as the number of milliseconds since the epoch). This timestamp and the following log entry are separated by a single space character, " ". Outgoing messages are distinguishable by a log entry that has ">>>" immediately following the space character after the timestamp. DCC events use "+++" and warnings about unhandled Exceptions and Errors use "###".

This implementation of the method will only cause log entries to be output if the PircBot has had its verbose mode turned on by calling setVerbose(true);

Parameters:
line - The line to add to the log.

handleLine

protected final void handleLine(String line)
This method handles events when any line of text arrives from the server, then calling the appropriate method in the PircBot. This method is protected and only called by the InputThread for this instance.

Parameters:
line - The raw line of text from the server.

onDisconnect

protected void onDisconnect()
This method carries out the actions to be performed when the PircBot gets disconnected. This may happen if the PircBot quits from the server, or if the connection is unexpectedly lost. If you wish to get your IRC bot to automatically rejoin a server after the connection has been lost, then this is probably the ideal method to override to implement such functionality. This abstract implementation performs no action.


onServerResponse

protected void onServerResponse(int code,
                                String response)
This method is called when we receive a numeric response from the IRC server.

Numerics in the range from 001 to 099 are used for client-server connections only and should never travel between servers. Replies generated in response to commands are found in the range from 200 to 399. Error replies are found in the range from 400 to 599.

For example, we can use this method to discover the topic of a channel when we join it. If we join the channel #test which has a topic of "I am King of Test" then the response will be "PircBot #test :I Am King of Test" with a code of 332 to signify that this is a topic. Check the IRC RFC for the full list of command response codes.

Parameters:
code - The three-digit numerical code for the response.
response - The full response from the IRC server.

onServerPing

protected void onServerPing(String response)
The actions to perform when a PING request comes from the server. This sends back a correct response, so if you override this method, be sure to either mimic its functionality or to call super.onServerPing(response);

Parameters:
response - The response that should be given back in your PONG.

onMessage

protected void onMessage(String channel,
                         String sender,
                         String login,
                         String hostname,
                         String message)
This method is called whenever a message is sent to a channel. This abstract implementation performs no action.

Parameters:
channel - The channel to which the message was sent.
sender - The nick of the person who sent the message.
login - The login of the person who sent the message.
hostname - The hostname of the person who sent the message.
message - The actual message sent to the channel.

onPrivateMessage

protected void onPrivateMessage(String sender,
                                String login,
                                String hostname,
                                String message)
This method is called whenever a private message is sent to the PircBot. This abstract implementation performs no action.

Parameters:
sender - The nick of the person who sent the private message.
login - The login of the person who sent the private message.
hostname - The hostname of the person who sent the private message.
message - The actual message.

onAction

protected void onAction(String sender,
                        String login,
                        String hostname,
                        String target,
                        String action)
This method is called whenever an ACTION is sent from a user. E.g. such events generated by typing "/me goes shopping" in most IRC clients. This abstract implementation performs no action.

Parameters:
sender - The nick of the user that sent the action.
login - The login of the user that sent the action.
hostname - The hostname of the user that sent the action.
target - The target of the action, be it a channel or our nick.
action - The action carried out by the user.

onJoin

protected void onJoin(String channel,
                      String sender,
                      String login,
                      String hostname)
This method is called whenever someone (possibly us) joins a channel which we are on. This abstract implementation performs no action.

Parameters:
channel - The channel which somebody joined.
sender - The nick of the user who joined the channel.
login - The login of the user who joined the channel.
hostname - The hostname of the user who joined the channel.

onPart

protected void onPart(String channel,
                      String sender,
                      String login,
                      String hostname)
This method is called whenever someone (possibly us) parts a channel which we are on. This abstract implementation performs no action.

Parameters:
channel - The channel which somebody parted from.
sender - The nick of the user who parted from the channel.
login - The login of the user who parted from the channel.
hostname - The hostname of the user who parted from the channel.

onNickChange

protected void onNickChange(String oldNick,
                            String login,
                            String hostname,
                            String newNick)
This method is called whenever someone (possibly us) changes nick on any of the channels that we are on. This abstract implementation performs no action.

Parameters:
oldNick - The old nick.
login - The login of the user.
hostname - The hostname of the user.
newNick - The new nick.

onKick

protected void onKick(String channel,
                      String kickerNick,
                      String kickerLogin,
                      String kickerHostname,
                      String recipientNick,
                      String reason)
This method is called whenever someone (possibly us) is kicked from any of the channels that we are in. This abstract implementation performs no action.

Parameters:
channel - The channel from which the recipient was kicked.
kickerNick - The nick of the user who performed the kick.
kickerLogin - The login of the user who performed the kick.
kickerHostname - The hostname of the user who performed the kick.
reason - The reason given by the user who performed the kick.

onQuit

protected void onQuit(String sourceNick,
                      String sourceLogin,
                      String sourceHostname,
                      String reason)
This method is called whenever someone (possibly us) quits from the server. We will only observe this if the user was in one of the channels to which we are connected. This abstract implementation performs no action.

Parameters:
sourceNick - The nick of the user that quit from the server.
sourceLogin - The login of the user that quit from the server.
sourceHostname - The hostname of the user that quit from the server.
reason - The reason given for quitting the server.

onMode

protected void onMode(String channel,
                      String sourceNick,
                      String sourceLogin,
                      String sourceHostname,
                      String mode)
Called when the mode of a channel is set. This abstract implementation performs no action.

Parameters:
channel - The channel that the mode operation applies to.
sourceNick - The nick of the user that set the mode.
sourceLogin - The login of the user that set the mode.
sourceHostname - The hostname of the user that set the mode.
mode - The mode that has been set.

onInvite

protected void onInvite(String targetNick,
                        String sourceNick,
                        String sourceLogin,
                        String sourceHostname,
                        String channel)
Called when we are invited to a channel by a user. This abstract implementation performs no action.

Parameters:
targetNick - The nick of the user being invited - should be us!
sourceNick - The nick of the user that sent the invitation.
sourceLogin - The login of the user that sent the invitation.
sourceHostname - The hostname of the user that sent the invitation.
channel - The channel that we're being invited to.

onDccSendRequest

protected void onDccSendRequest(String sourceNick,
                                String sourceLogin,
                                String sourceHostname,
                                String filename,
                                long address,
                                int port,
                                int size)
This method is called whenever a DCC SEND request is sent to the PircBot. This means that a client has requested to send a file to us. This abstract implementation performs no action, which means that all DCC SEND requests will be ignored by default. If you wish to save the file, then you may override this method and call the dccReceiveFile method from it, which connects to the sender and downloads the file, eg: -

public void onDccSendRequest(String sender, String login, String hostname, String filename, int address, int port, int size) {
    // Check to see if we trust the sender first?
    // Check that the filename isn't going to overwrite anything important?
    dccReceiveFile(new File(filename), address, port, size);
    // Method finishes when the download completes or if it fails.
}

Each time this method is called, it is called from within a new Thread in order to allow multiple files to be downloaded by the PircBot at the same time. Warning: Implementing this method and subsequently calling the dccReceiveFile method will cause a file to be written to disk. Please ensure that you make adequate security checks to make sure that this file will not overwrite anything important!

Parameters:
filename - The suggested filename to be used when saving the file.
address - The host address of the initiator as an integer.
port - The port number to connect to if we want to receive the file.
size - The size of the file in bytes. Older clients do not support this, in which case a value of -1 will be used.

onDccChatRequest

protected void onDccChatRequest(String sourceNick,
                                String sourceLogin,
                                String sourceHostname,
                                long address,
                                int port)
This method is called whenever a DCC CHAT request is sent to the PircBot. This means that a client has requested to chat to us directly rather than via the IRC server. This is useful for sending many lines of text to and from the bot without having to worry about flooding the server or any operators of the server being able to "spy" on what is being said. This abstract implementation performs no action, which means that all DCC CHAT requests will be ignored by default. If you wish to accept the connection, then you may override this method and call the dccAcceptChatRequest method from it, which connects to the sender of the chat request and returns a DccChat object which can be used to read lines from the user and to send lines back. Here is an example of how to use the DccChat object: -

public void onDccChatRequest(String sourceNick, String sourceLogin, String sourceHostname, long address, int port) {
    // Check to see if we want to accept the chat connection first?
    DccChat chat = dccAcceptChatRequest(sourceNick, address, port);
    if (chat != null) {
        try {
            chat.sendLine(Hi, what's your name?");
            String name = chat.readLine();
            chat.sendLine("Hello, " + name);
            chat.close();
        }
        catch (IOException e) {
            // The connection was lost
        }
    }
}

Each time this method is called, it is called from within a new Thread in order to allow multiple DCC Chat sessions to run at the same time.

Parameters:
address - The host address of the initiator as an integer.
port - The port number to connect to if we want to chat.

onVersion

protected void onVersion(String sourceNick,
                         String sourceLogin,
                         String sourceHostname,
                         String target)
This method is called whenever we receive a VERSION request. This abstract implementation responds with the PircBot's _version string, so if you override this method, be sure to either mimic its functionality or to call super.onVersion(...);

Parameters:
sourceNick - The nick of the user that sent the VERSION request.
sourceLogin - The login of the user that sent the VERSION request.
sourceHostname - The hostname of the user that sent the VERSION request.
target - The target of the VERSION request, be it our nick or a channel name.

onPing

protected void onPing(String sourceNick,
                      String sourceLogin,
                      String sourceHostname,
                      String target,
                      String pingValue)
This method is called whenever we receive a PING request. This abstract implementation responds correctly, so if you override this method, be sure to either mimic its functionality or to call super.onPing(...);

Parameters:
sourceNick - The nick of the user that sent the PING request.
sourceLogin - The login of the user that sent the PING request.
sourceHostname - The hostname of the user that sent the PING request.
target - The target of the PING request, be it our nick or a channel name.
pingValue - The value that was supplied as an argument to the PING command.

onTime

protected void onTime(String sourceNick,
                      String sourceLogin,
                      String sourceHostname,
                      String target)
This method is called whenever we receive a TIME request. This abstract implementation responds correctly, so if you override this method, be sure to either mimic its functionality or to call super.onTime(...);

Parameters:
sourceNick - The nick of the user that sent the TIME request.
sourceLogin - The login of the user that sent the TIME request.
sourceHostname - The hostname of the user that sent the TIME request.
target - The target of the TIME request, be it our nick or a channel name.

onFinger

protected void onFinger(String sourceNick,
                        String sourceLogin,
                        String sourceHostname,
                        String target)
This method is called whenever we receive a FINGER request. This abstract implementation responds correctly, so if you override this method, be sure to either mimic its functionality or to call super.onFinger(...);

Parameters:
sourceNick - The nick of the user that sent the FINGER request.
sourceLogin - The login of the user that sent the FINGER request.
sourceHostname - The hostname of the user that sent the FINGER request.
target - The target of the FINGER request, be it our nick or a channel name.

onNotice

protected void onNotice(String sourceNick,
                        String sourceLogin,
                        String sourceHostname,
                        String target,
                        String notice)
This method is called whenever we receive a notice. This abstract implementation performs no action.

Parameters:
sourceNick - The nick of the user that sent the notice.
sourceLogin - The login of the user that sent the notice.
sourceHostname - The hostname of the user that sent the notice.
target - The target of the notice, be it our nick or a channel name.
notice - The notice message.

onUnknown

protected void onUnknown(String line)
This method is called whenever we receive a line from the server that the PircBot has not been programmed to recognise. This abstract implementation performs no action.

Parameters:
line - The raw line that was received from the server.

setVerbose

public final void setVerbose(boolean verbose)
Sets the verbose mode. If verbose mode is set to true, then log entries will be made available.

Parameters:
verbose - true if verbose mode is to be used. Default is false.

setName

protected final void setName(String name)
Sets the internal name of the Bot. This should be set before joining any servers, otherwise the default nick will be used. You would typically call this method from the contstructor of your class that extends PircBot. The changeNick method should be used if you wish to change your nick when you are connected to a server.

Parameters:
name - The new name of the Bot.

setLogin

protected final void setLogin(String login)
Sets the interal login of the Bot. This should be set before joining any servers.

Parameters:
login - The new login of the Bot.

setVersion

protected final void setVersion(String version)
Sets the internal version of the Bot. This should be set before joining any servers.

Parameters:
version - The new version of the Bot.

setFinger

protected final void setFinger(String finger)
Sets the interal finger message. This should be set before joining any servers.

Parameters:
finger - The new finger message for the Bot.

getName

public final String getName()
Gets the internal name of the PircBot.

Returns:
The name of the PircBot.

getLogin

public final String getLogin()
Gets the internal login of the PircBot.

Returns:
The login of the PircBot.

getVersion

public final String getVersion()
Gets the internal version of the PircBot.

Returns:
The version of the PircBot.

getFinger

public final String getFinger()
Gets the internal finger message of the PircBot.

Returns:
The finger message of the PircBot.

isConnected

public final boolean isConnected()
Returns whether or not the PircBot is currently connected to a server.

Returns:
True if and only if the PircBot is currently connected to a server.

setMessageDelay

public final void setMessageDelay(long delay)
Sets the number of milliseconds to delay between consecutive messages when there are multiple messages waiting in the outgoing message queue. This has a default value of 1000ms. It is a good idea to stick to this default value, as it will prevent your bot from spamming servers and facing the subsequent wrath! However, if you do need to change this delay value (not recommended), then this is the method to use.

Parameters:
delay - The number of milliseconds between each outgoing message.

getMessageDelay

public final long getMessageDelay()
Returns the number of milliseconds that will be used to separate consecutive messages to the server from the outgoing message queue.

Returns:
Number of milliseconds.

getMaxLineLength

public final int getMaxLineLength()
Gets the maximum length of any line that is sent via the IRC protocol. The IRC RFC specifies that line lengths, including the trailing \r\n must not exceed 512 bytes. Hence, there is currently no option to change this value in PircBot. All lines greater than this length will be truncated before being sent to the IRC server.

Returns:
The maximum line length (currently fixed at 512)

longToIp

public int[] longToIp(long address)
A convenient method that accepts an I.P. address represented as a long and returns an integer array of size 4 representing the same I.P. address.